はじめに
個人的にDjangoをやっていたのですがサーバー代が馬鹿にならないので静的サイトジェネレーターについて調べ始めました。巷ではGatsbyなどが流行っているようですが出来るだけPythonで楽をしたいのでMkDocsについて書きます。なおこの記事はテーマの自作について取り扱うのではなく、あくまで既存のテーマとそのカスタムに範囲が留まっています。
既存のテーマを使おう
公式のドキュメントに記載がありますが、デフォルトでインストールされているテーマを使用する場合にはtheme: テーマ名という一文をmkdocs.ymlに記述するだけで大丈夫です。
例としてreadthedocsというテーマを設定する場合にはtheme: readthedocsという一文を追記するだけで追記するだけでいいのです。簡単ですね！
MkDocsにはコミュニティによって作られたテーマが沢山あります。中でもかなり有名なのがマテリアルデザインを取り入れたmkdocs-materialです。外部のテーマを取り入れるのもかなり簡単で
pip install mkdocs-material
から
theme:
name: material
とするだけです。このテーマに関しての詳細は公式のgithubページをご覧ください。他にも面白テーマや実用的なテーマがこのページに多く載っています。ぜひ確認してみてくださいね。
カスタムCSS/Javascript
CSSやJavascriptを追加したいだけならばとても容易にできます。Documentation directoryに追加したいCSSやJavascriptのファイルを置くだけです。ここにより詳しく書いてありますが、例えばdocumentation directory以下にある
extra_css:
- css/extra.css
- css/second_extra.css
のような構造ではextra_cssをcssというサブディレクトリと共に追加することによってcssを追加しています。Javascriptの場合も同じ要領で追加できます。
テーマの上書き
公式ドキュメントによるとテーマのカスタマイズには新しいディレクトリをdocumentation directoryと同じ階層に作る必要性がありそうです。
mkdocs custom_theme
それができたらmkdocs.ymlにてカスタムテーマがどこにあるのか指示してあげましょう。
theme:
name: mkdocs
custom_dir: custom_theme/
custom_dir内で使用しているテーマに含まれているファイルと同じファイル名のファイルを作成すると自動的に現在使用しているテーマのファイルが新しく作ったファイルに置き換えられます。また、使用しているテーマに含まれない名前のファイルを作成すると自動的に既存のテーマに追加されます。
テンプレートブロックの上書き
htmlファイルを上書きする際にはbase.htmlを継承する方が楽です(もちろんbase.html自体を上書きする場合はその限りではありません)。
{% extends "base.html" %}
{% block htmltitle %}
<title>Custom title goes here</title>
{% endblock %}
このような形でテンプレートブロックを書くことで簡単に継承ができますね。これも詳細は前述の公式ドキュメントに詳しく載っています。
最後に
近々テーマの自作についての記事も書くかもしれません。間違いがあるようでしたら編集リクエスト等を積極的に送っていただけるとありがたいです。