MkDocsでサイトの見た目を変えよう

ここでは、テーマを変更したり、テーマの内容を変えて、サイトの見た目を変える方法を見ていきます。

テーマを別のものに変えてみよう

MkDocs には、2つのテーマがデフォルトで入っています。他の人が作ったテーマを使うこともできます。また、これらの一部を上書きして使ったり、自分でテーマを作ることも可能です。

デフォルトでは、mkdocs テーマが適用されています。Bootstrap をベースにして作られたテーマです。highlight.js が使えるようになっています。また、ショートカットの設定や、ナビゲーションのスタイル（primary、dark、light）を選ぶことができます。

このテーマを変更するには、mkdocs.yml で次のように書きます。

theme: readthedocs

この readthedocs テーマも、デフォルトで入っています。これも、highlight.js が使えるようになっています。他にも、前後への記事をどこに表示するか、サイドバーにタイトルだけを表示するか、などの設定が mkdocs.yml 内で行えます。

他の人が作ったテーマは、MkDocs community wiki で探せます。

テーマをカスタマイズする場合、簡単なものであれば docs ファルダ内に CSS ファイルや JavaScript ファイルを追加するだけでOKです。テンプレートの上書きなど、もう少し複雑なものは、custom_dir の設定を利用します。

まず、一部の色を変えるなど、簡単なカスタマイズであれば、docs 内に CSS ファイルなどを追加し、 mkdocs.yml 内で次のように設定します。

extra_css:
    - css/extra.css
    - css/second_extra.css

こうすれば、追加で設定した CSS が反映されます。

もう少し、HTML の構造など、大幅にテーマの内容を変えたい場合は、custom_dir を docs フォルダと同じ階層に作ります。名前は何でもいいですが、次のように設定します。

theme:
    name: mkdocs
    custom_dir: custom_theme/

ここでは、custom_theme というフォルダにしています。

このフォルダの下にファイルを置けば、テーマ内のファイルが上書きされます。なので、そもそも、テーマ内にどんなファイルがあって、どんな内容なのかを把握しておく必要があります。

custom_dir を使えば、テーマの既存ファイルを上書きすることはできますが、今あるものを削除することはできません。そうしたい場合は、一からテーマを作るしかありません。

テンプレートは、たくさんのテンプレートブロックで構成されています。デフォルトのテンプレートのフォルダ内にある main.html を見ると、base.html を拡張していることがわかります。base.html ファイルの中は、たくさんのテンプレートブロックで構成されています。

このうち、テンプレートブロックを1つだけ上書きして、他の構造はそのまま使い回すこともできます。custom_dir 内で main.html を作成し、以下のように書きます。

{% extends "base.html" %}

{% block htmltitle %}
<title>Custom title goes here</title>
{% endblock %}

base.html ファイル内では、タイトルの設定を行っていますが、上のように書けばタイトルの設定のみ上書きすることができます。テーマ内にテンプレートブロックが用意されていれば、このように一部分だけ上書きすることもできます。

また、上書きではなく、追記することもできます。例えば、libs ブロックでは、JavaScript のライブラリの設定がまとめられています。ここに何か別のライブラリを使いたいけれど、デフォルトで設定していたものも使いたい、としましょう。この場合、次のように書きます。

{% extends "base.html" %}

{% block libs %}
    {{ super() }}
    <script src="{{ base_url }}/js/somelib.js"></script>
{% endblock %}

super() を使えば、もとのテンプレートブロックの内容が展開されるので、別の設定を追加することができるようになります。

ここでは、ページの見た目や、ページの構造の一部を変えるための方法を見てきました。テンプレートをいじるには、テンプレートやテーマの構造について詳しく知らないといけません。次は、テーマの構成について見ていきます。