MkDocsの設定を行う

ここでは、MkDocs の設定を変えたり、記事を追加する方法を見ていきます。MkDocs のインストール、サイトの作成 mkdocs new は実行済みとします。

サイトタイトルを変えてみよう

まずは、サイトタイトルを変えてみます。

mkdocs.yml を開くと、次のようになっているはずです。

site_name: My Docs

この mkdocs.yml は、サイト全般に関する設定を行うファイルです。

今は、このサイトタイトルに関する設定だけが入っています。この名前を別のものに変えて、上書き保存してみましょう。そうすると、ページが自動で更新され、設定した通りにサイトタイトルが変更されたはずです。

site_url も次の行に追加しておくといいでしょう。site_url を設定すると、canonical URL が設定され、sitemap.xml などが正しく更新されます。

記事を追加してみよう

次は、記事の追加をしてみます。

index.md をコピペして何か別の名前にし、適当に内容を書いて保存してみます。その際、1行目を次のようにしてみましょう。

# サンプルタイトル

1個の # と半角スペースを書けば、h1タグに変換されます。こうして保存すると、サイトの一番上のナビゲーションのところに、h1タグに設定した内容が反映されていることがわかります。

しかし、h1タグの前に何かを書いたり、h1タグがなかったりすると、ナビゲーションのところには Markdown ファイルの名前がそのまま表示されます。

ナビゲーションを変えてみよう

さらに複数の記事を追加してみると、一番上のナビゲーションバーにどんどん記事が追加されていきます。記事が多くなってくると、少し見た目がカッコ悪いですね。

ナビゲーションの設定も、mkdocs.ymlで行います。次のようにしてみましょう。

site_name: My Docs
nav:
    - Home: index.md
    - サンプル: sample.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

こんなに階層を深くすることはないでしょうが、どのように表示されるかやってみると参考になると思います。

サイトの右上について

サイトの右上を見てみましょう。

テーマの設定を行っていない状態で複数ページを追加すると、「Previous」「Next」というナビゲーションが現れます。

また、検索機能もついています。が、デフォルトでは日本語検索はうまくいきません。あとで、日本語対応のテーマに変更するタイミングで、再度見ることにします。

テーマの変更について

MkDocs には、デフォルトでは2つのテーマが入っています。1つは、MkDocs の公式サイトと同じ MkDocs というテーマです。もう1つは、ReadTheDocs テーマです。テーマの切り替えは簡単にできるのでやってみましょう。

mkdocs.yml を開き、次の内容を追記します。

theme: readthedocs

テーマを変えると、自動的にサイトが更新され、見た目がガラッと変わったはずです。このテーマを採用しているサイトも多いので、見覚えのある人もいるのではないでしょうか。

おわりに

ここでは、MkDocsで、どの設定を変えればサイトのどこが変わるか、を中心に見てきました。サイトを更新していく方法を、より具体的に見ていきます。