コンテンツにスキップ

MkDocsを使ってMarkdownでかけるマテリアルなサイトを構築する

MkDocsは静的コンテンツだけで構成するサイトを生成するツール。

  • ドキュメントはMarkdownで書くこができる。
  • サイトの構成はYAMLの設定ファイル1つだけ。

で非常にシンプルなので使いやすい。静的コンテンツといのがいい。

ここではMkDocsのインストールから始め、シンプルなサイトを立ち上げるまでの方法を説明していきます!!

MkDocsをインストールする

本家サイトでおすすめされているのはpipを使ったインストール。「pipってなに?」という人は、pythonを先にインストールしましょう。

MkDocsにはテーマがあり、僕のおすすめはMaterial for MkDocs。Material for MkDocsをインストールすれば、ついでにMkDocs本体もインストールされるので、Material for MkDocsだけインストールすればいい。

Material for MkDocsのインストールは

$ sudo pip3 install mkdocs-material

空のサイトを新規作成する

Material for MkDocsをインストールできたらサイトのテンプレートを新規作成する。

コマンドで指定した名前のディレクトリが作成され、その下にテンプレートができる。なので、適当なディレクトリに移動してmkdocsコマンドで作る。既存ディレクトリを指定しても大丈夫。既存のgitのワーキングディレクトリを指定しても大丈夫。

$ cd ~/workspace
$ mkdocs new crz33.com

すると、以下のようなテンプレートサイトができあがる。

crz33.com
    ├── docs
    │   └── index.md <-- サンプルのMarkdown
    └── mkdocs.yml   <-- 設定ファイル

とりあえずは修正せずそのまま立ち上げてみましょう。

空のサイトを起動する

すでに最低限の設定とサンプルのindex.mdができているので、立ち上げて確認できる。ローカルで確認するだけなら、次のとおり。

$ cd crz33.com
$ mkdocs serve

コンソールにもURLが出力されるが、ローカル起動でのサイトのURLは http://127.0.0.1:8000 。

サイトの設定をカスタマイズする

サイトの設定は、mkdocs.yml。

設定内容はConfigurationに細かく説明がある。

Markdownファイルのおすすめの構成

サイト内に記事を追加していく場合、次のようにフラットに配置するのがおすすめ。

crz33.com
├── README.md
├── docs
│   ├── 2020
│   │   └── 記事A.md
│   │   └── 記事B.md
│   │   └── 記事C.md
│   └── index.md
└── mkdocs.yml

最終的な記事のURLが変化しないようにするため。

よくやってしまう過ちは、カテゴリ名をディレクトリにして、ファイルを意味のある分類にしてしまうこと。そうすると、カテゴリの入れ替えや階層を深くしようとした場合に破綻する。

なので、記事はフラットにすべき。かわりにサイトマッップは手動でmkdocs.ymlに設定。

nav:
  - Home: index.md
  - カテゴリX:
    - 記事A: 2020/記事A.md
  - カテゴリY:
    - カテゴリYA:
      - 記事B: 2020/記事B.md
    - カテゴリYB:
      - 記事C: 2020/記事C.md

最終更新日: 2020年4月24日