テーマのカスタマイズ

ニーズに合わせてテーマを変更します。

既存のテーマにいくつかの調整を加えたい場合、最初から独自のテーマを作成する必要はありません。CSSやJavaScriptのみを必要とする軽微な調整については、docs_dirを使用できます。ただし、テンプレートのオーバーライドなど、より複雑なカスタマイズについては、theme custom_dir設定を使用する必要があります。

docs_dirの使用

extra_css および extra_javascript 設定オプションを使用すると、既存のテーマに調整やカスタマイズを加えることができます。これらを使用するには、ドキュメントディレクトリ内にCSSファイルまたはJavaScriptファイルを含めるだけです。

たとえば、ドキュメント内のヘッダーの色を変更するには、(例として) style.css というファイルを作成し、ドキュメントのMarkdownの横に配置します。そのファイルに次のCSSを追加します。

h1 {
  color: red;
}

次に、それを mkdocs.yml に追加する必要があります。

extra_css:
  - style.css

これらの変更を加えた後、mkdocs serve を実行すると、それらが表示されるはずです。すでにこれを実行している場合は、CSSの変更が自動的に取得され、ドキュメントが更新されることがわかるはずです。

注意

追加のCSSファイルまたはJavaScriptファイルは、ページコンテンツの後に生成されたHTMLドキュメントに追加されます。JavaScriptライブラリを含めたい場合は、テーマのcustom_dirを使用することで、ライブラリを含める方が成功する可能性があります。

theme custom_dirの使用

theme.custom_dir 設定オプションは、親テーマのファイルをオーバーライドするファイルのディレクトリを指すために使用できます。親テーマは、theme.name 設定オプションで定義されたテーマになります。custom_dir 内の親テーマ内のファイルと同じ名前を持つファイルは、親テーマ内の同じ名前のファイルを置き換えます。custom_dir 内の追加ファイルは、親テーマに追加されます。custom_dir の内容は、親テーマのディレクトリ構造を反映する必要があります。テンプレート、JavaScriptファイル、CSSファイル、画像、フォント、またはテーマに含まれるその他のメディアを含めることができます。

注意

これが機能するには、theme.name 設定が既知のインストール済みテーマに設定されている必要があります。name 設定が代わりに null (または定義されていない) に設定されている場合、オーバーライドするテーマはなく、custom_dir の内容は完全なスタンドアロンテーマである必要があります。詳細については、テーマ開発者ガイドを参照してください。

たとえば、mkdocs テーマ(ソースを参照)には、次のディレクトリ構造が含まれています(一部)

- css\
- fonts\
- img\
  - favicon.ico
  - grid.png
- js\
- 404.html
- base.html
- content.html
- nav-sub.html
- nav.html
- toc.html

そのテーマに含まれるファイルをオーバーライドするには、docs_dir の横に新しいディレクトリを作成します

mkdir custom_theme

次に、mkdocs.yml 設定ファイルを新しいディレクトリに向けて設定します

theme:
  name: mkdocs
  custom_dir: custom_theme/

404エラーページ(「ファイルが見つかりません」)をオーバーライドするには、custom_theme ディレクトリに 404.html という名前の新しいテンプレートファイルを追加します。テンプレートに含めることができるものについては、テーマ開発者ガイドを確認してください。

faviconをオーバーライドするには、custom_theme/img/favicon.ico に新しいアイコンファイルを追加します。

JavaScriptライブラリを含めるには、ライブラリを custom_theme/js/ ディレクトリにコピーします。

ディレクトリ構造は次のようになります。

- docs/
  - index.html
- custom_theme/
  - img/
    - favicon.ico
  - js/
    - somelib.js
  - 404.html
- config.yml

注意

親テーマ(name で定義)に含まれているが、custom_dir に含まれていないファイルは引き続き利用されます。custom_dir は、親テーマのファイルのみをオーバーライド/置き換えます。ファイルを削除したり、最初からテーマを構築したりする場合は、テーマ開発者ガイドを確認する必要があります。

テンプレートブロックのオーバーライド

組み込みのテーマは、その多くの部分を main.html テンプレートで個別にオーバーライドできるテンプレートブロック内に実装しています。custom_dir に main.html テンプレートファイルを作成し、そのファイル内に代替ブロックを定義するだけです。main.html が base.html を拡張していることを確認してください。たとえば、MkDocsテーマのタイトルを変更するには、置き換え用の main.html テンプレートに以下を含めます。

{% extends "base.html" %}

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

上記の例では、カスタム main.html ファイルで定義された htmltitle ブロックが、親テーマで定義されたデフォルトの htmltitle ブロックの代わりに使用されます。親で定義されている限り、必要なだけ多くのブロックを再定義できます。たとえば、Google Analyticsスクリプトを別のサービスのスクリプトに置き換えたり、検索機能を独自のスクリプトに置き換えたりできます。オーバーライドに使用できるブロックを判断するには、使用している親テーマを参照する必要があります。MkDocsテーマとReadTheDocsテーマは、次のブロックを提供します。

  • site_meta: ドキュメントのヘッドのメタタグを含みます。
  • htmltitle: ドキュメントのヘッドのページタイトルを含みます。
  • styles: スタイルシートのリンクタグを含みます。
  • libs: ページヘッダーに含まれるJavaScriptライブラリ(jQueryなど)を含みます。
  • scripts: ページが読み込まれた後に実行する必要があるJavaScriptスクリプトを含みます。
  • analytics: アナリティクススクリプトを含みます。
  • extrahead: カスタムタグ/スクリプトなどを挿入するための <head> 内の空のブロック。
  • site_name: ナビゲーションバーのサイト名を含みます。
  • site_nav: ナビゲーションバーのサイトナビゲーションを含みます。
  • search_button: ナビゲーションバーの検索ボックスを含みます。
  • next_prev: ナビゲーションバーの「次へ」および「前へ」ボタンを含みます。
  • repo: ナビゲーションバーのリポジトリリンクを含みます。
  • content: ページコンテンツとページの目次を含みます。
  • footer: ページフッターを含みます。

サイトの構造で変更が機能するように、ソーステンプレートファイルを表示する必要がある場合があります。カスタムブロック内で使用できる変数のリストについては、テンプレート変数を参照してください。ブロックの詳細な説明については、Jinjaドキュメントを参照してください。

custom_dirとテンプレートブロックの組み合わせ

JavaScriptライブラリを custom_dir に追加すると、ライブラリは利用可能になりますが、MkDocsによって生成されたページには含まれません。したがって、HTMLからライブラリへのリンクを追加する必要があります。

上記のディレクトリ構造(切り捨て)から開始します。

- docs/
- custom_theme/
  - js/
    - somelib.js
- config.yml

custom_theme/js/somelib.js ファイルへのリンクをテンプレートに追加する必要があります。somelib.js はJavaScriptライブラリであるため、論理的には libs ブロックに配置されます。ただし、新しいスクリプトのみを含む新しい libs ブロックは、親テンプレートで定義されたブロックを置き換え、親テンプレート内のライブラリへのリンクは削除されます。テンプレートを壊さないようにするために、ブロック内からの super の呼び出しと共にスーパーブロックを使用できます。

{% extends "base.html" %}

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

base_urlテンプレート変数は、リンクが常に現在のページを基準にしていることを確認するために使用されたことに注意してください。

これで、生成されたページには、テンプレートで提供されたライブラリへのリンクと、custom_dir に含まれるライブラリへのリンクが含まれます。custom_dir に含まれる追加のCSSファイルについても同様のことが必要です。