MkDocsで記事を書こう

MkDocs で記事を書くには、Markdown ファイルを作って、ドキュメント用のフォルダに置きます。デフォルトの設定では、ドキュメント用のフォルダは、docs フォルダです。MkDocs をインストールし、mkdocs new my-project を実行した直後は、次のような階層になっています。

mkdocs.yml
docs/
    index.md

yml ファイルは設定ファイルで、docs フォルダがドキュメント用フォルダ、その下の index.md が Markdown ファイルです。この Markdown ファイルが、サイトトップの index.html に対応します。

ファイルを追加してみよう

ファイルを追加して次のようにしてみます。

mkdocs.yml
docs/
    index.md
    about.md
    license.md

こうしてから build すると、site フォルダにファイルができます。公開すれば、次のような URL でアクセスできるようになります。対応はファイル名から推測できるでしょう。

/
/about/
/license/

実際には、各フォルダの下に index.html が作成されています。

Markdown ファイルを階層化したいこともあるでしょう。フォルダの構成を次のように変更したとしましょう。

docs/
    index.md
    user-guide/getting-started.md
    user-guide/configuration-options.md
    license.md

build 実行後には、次のような URL でアクセスできるようになります。

/
/user-guide/getting-started/
/user-guide/configuration-options/
/license/

Markdown ファイル以外は、変更されずにそのままコピーされます。例えば、画像などのファイルを docs フォルダの下に追加すれば、build 後には site フォルダにコピーされます。

ページ間の設定をしよう

ファイルを追加し、サイトにページを追加していくと、ナビゲーションなどの設定をしたくなります。テーマが自動で設定してくれますが、設定を自分の好きなものに変えることもできます。

まず、ナビゲーションの設定についてです。ナビゲーションの設定を行わない場合、docs フォルダの下にあるフォルダの構造がそのままナビゲーションの構造に反映されます。また、順番は、フォルダ名・ファイル名のアルファベット順です。ただし、index.html だけはつねに先頭になります。

これらの設定を変えたい場合は、手動で設定する必要があります。

ナビゲーションの設定は、mkdocs.yml ファイル内で行います。次のように、nav の設定を行います。

nav:
    - 'index.md'
    - 'about.md'

これが最低限の設定です。これで、ファイルの順番が指定できます。ファイルは docs フォルダからの相対パスで指定します。ファイルがなくても指定できますが、アクセスしても 404 ページが表示されるだけです。

ナビゲーションに表示される名前は、Markdown のファイル内のタイトルが使われます。もしタイトルが取得できない場合は、ファイル名が表示されます。この表示名も変えたい場合は、次のように設定します。

nav:
    - Home: 'index.md'
    - About: 'about.md'

これで、Home と About が並んで表示されるようになりました。このタイトルの設定は、サイト全体で適用されます。Markdown ファイル内でタイトルを設定しても、このナビゲーションで設定したタイトルが優先されます。

ナビゲーションは入れ子にすることもできます。例えば、次のように設定したとします。

nav:
    - Home: 'index.md'
    - 'User Guide':
        - 'Writing your docs': 'writing-your-docs.md'
        - 'Styling your docs': 'styling-your-docs.md'
    - About:
        - 'License': 'license.md'
        - 'Release Notes': 'release-notes.md'

これは、公式サイトの一部ですが、こうすると一番上には Home、User Guide、About という3つが並びます。User Guide の下には2つのページが並び、About の下にも2つのページが並ぶようになります。

About の下にある License のページは、docs/license.md ファイルが対応しています。つまり、ナビゲーションの階層と docs 下の階層は対応していなくてもよい（というか、自動での対応づけはしてくれない）ということです。

なお、セクション自体にページを対応させることはできません。例えば、About を選択したときにどこかのページに飛ばすことはできません。各セクションに含められるのは、複数のページと複数の子セクションだけです。WordPress などでは、サブカテゴリーのあるカテゴリーを選んだときに、カテゴリーのアーカイブページを表示することができますが、MkDocs ではそういうことはできません。index.md は作れって似たようなものを作るしかありません。

階層はもっと深くすることもできます。

nav:
    - Home: index.md
    - サンプル:
        - サンプル1:
            - サンプル1-1: sample1-1.md
            - サンプル1-2:
                - サンプル1-2-1: sample1-2-1.md
        - サンプル2: sample2.md
        - サンプル3: sample3.md

ただ、深くしすぎると目的のページにたどりつきにくくなるので、あまり深くするのはやめておいた方がいいでしょう。

nav に設定したページは、ナビゲーション内に表示されますが、docs フォルダにはあって nav に設定しなかったページはどうなるでしょうか。実は、HTML ファイルは作られていますが、どこからもリンクされないので、サイト内では見えない存在になります。ナビゲーション内の Previous、Next でもたどりつけないので、明示的にリンクを貼らないと、nav で設定しなかったページにたどりつくことはできません。

docs フォルダにあるのに nav の設定に含まれていないファイルがあるときには、 mkdocs serve や mkdocs build を実行したときに教えてくれます。

Markdownで書いてみよう

Markdown とは、HTML に変換することのできる記法のことで、HTML よりも表記が簡単で、扱いやすくなっています。MkDocs には、Markdown で書いたファイルを HTML に自動で変換してくれるので、めんどうな HTML の一部を簡単な記法で書くことができます。最近、いろいろなところで取り入れられている記法です。

一般的な Markdown の記法は、いろいろなところで紹介されているので、そちらを参考にしてください。以下では、MkDocs 特有の設定などを見ていきます。

まず、内部リンクについてです。一般的なリンクの書き方で内部リンクも書けます。リンク先は、相対パスで指定します。

Please see the [project license](license.md) for further details.

build したら、自動でハイパーリンクに変換されます。絶対パスで指定するのは非推奨です。

別のフォルダへリンクしたい場合は、次のようにします。

Please see the [project license](../about/license.md) for further details.

.. で1つ上の階層に行く、という意味です。

画像へリンクしたいこともあるでしょう。次のような構造だったとします。

mkdocs.yml
docs/
    index.md
    about.md
    license.md
    img/
        screenshot.png

この場合に、Markdown ファイルから画像ファイルを呼び出したいときは、次のように書きます。

![Screenshot](img/screenshot.png)

docs フォルダ内に、HTML ファイルをおくこともできます。ただ、MkDocs は、HTML ファイルの中身は何も変えずに、site フォルダの下にコピペします。なので、 HTML ファイルに Markdown の記法があったり、パスがあっても、何も変換されません。HTML ファイルを置く場合は、そのファイル内に書いたパスなどは、自分で正しく設定しなくてはいけません。

メタデータの設定

Markdown ファイルの冒頭に、メタデータを設定することができます。YAML 記法と MultiMarkdown 記法がサポートされています。

メタデータを設定すると、テーマによっては、特別な設定を行うことができるかもしれません。テーマによらずに設定できるのは、 template と title です。

template は、Markdown を変換する際に使用するテンプレートファイルの指定です。これは使用しているテーマによって指定する内容が変わります。 title はページのタイトルです。ページのタイトルは、nav の設定が最優先、その次にこの title、その次がページ内の h1 タグ、最後にファイル名、という順番で決まります。

例えば、YAML 記法で設定する場合は、次のようになります。

---
title: My Document
summary: A brief description of my document.
authors:
    - Waylan Limberg
    - Tom Christie
date: 2018-07-10
some_url: https://example.com
---
This is the first paragraph of the document.

3本ダッシュから3本ダッシュまでがメタデータの設定です。title 以外にもいろいろ設定していますが、これらがページ内にどう反映されるか（もしくは無視されるか）は、使用するテーマによって決まります。

おわりに

ここでは、MkDocs で記事を書く方法について見てきました。ファイルをどこに追加し、ファイル間の関係をどこで定義するか、どのように書いていくか、等を見てきました。

次は、ページの見た目を変えるための方法を見ていきます。