MkDocsのプロジェクト作る手順メモ

Memo
目次

ドキュメント作るたびにプロジェクト作るんで、忘れやすい手順メモ
Windows10の作業メモだけど、管理者権限うんぬん以外はだいたい同じだと思う。

1. プロジェクト作成

管理者権限つけたコマンドプロンプトで以下作業をする。

順番に、

  1. プロジェクト作成
  2. 作ったプロジェクトのディレクトリに移動
  3. 日本語に対応したテーマをインストール
  4. 拡張プラグインをインストール
  5. 画像用のimgディレクトリ作成
  6. プレビュー起動

インストールのとこは2回目以降はやんなくていい。

$ mkdocs new project-name
$ cd project-name
$ pip install mkdocs-material
$ pip install mkdocs-awesome-pages-plugin
$ mkdir img
$ mkdocs serve

2. 設定ファイル追記

プロジェクトディレクトリ直下にある mkdocs.yml が設定ファイルなんで、以下の内容コピペする。

site_name: サイト名
theme:
  name: 'material'
  language: 'ja'
extra:
  search:
    language: 'ja'
plugins:
  - search # necessary for search to work
  - awesome-pages
markdown_extensions:
  - codehilite:
      linenums: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - pymdownx.inlinehilite
  - pymdownx.magiclink
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tabbed
  - pymdownx.tilde

** - pymdownx.superfences をつけると linenums: true が無効になります。なった。 ** ** 要約するとコードのタブ機能を有効にすると、デフォルトでコードの行表示有効にするオプションが効かなくなります。
コードに毎回手動で linenums=“1” って入れると表示されるけどめんどい。 **

3. コンテンツ作ってく

docs/ 以下にmarkdownファイルを作る。
画像はさっき作った docs/img に入れる。

4. htmlページをビルドして完成

以下のコマンドで site/ ディレクトリにhtmlファイルが生成される。

$ mkdocs build