テーマの選択

テーマの選択と設定。

---

MkDocsには、以下に説明するように、2つの組み込みテーマ（mkdocsとreadthedocs）が含まれています。ただし、多くのサードパーティのテーマも選択できます。

テーマを選択するには、mkdocs.yml設定ファイルでtheme設定オプションを設定します。

theme:
  name: readthedocs

mkdocs

デフォルトのテーマは、カスタムBootstrapテーマとして構築されており、MkDocsのほぼすべての機能をサポートしています。

デフォルトのテーマ設定オプションに加えて、mkdocsテーマは次のオプションをサポートしています。

• color_mode：テーマのデフォルトのカラーモードを、light、dark、またはautoのいずれかに設定します。autoモードでは、ユーザーのデバイスのシステム設定に基づいてlightまたはdarkに切り替わります。デフォルト：light。

• user_color_mode_toggle：ナビゲーションバーにトグルメニューを有効にして、ユーザーがブラウザ内から好みのcolor_mode（light、dark、auto）を選択し、今後のページロードのために設定を保存できるようにします。最初のページロード時のトグルメニューのデフォルトの選択は、color_modeに設定された値です。デフォルト：false。

  

• nav_style：トップナビゲーションバーのビジュアルスタイルを調整します。primary、dark、またはlightのいずれかに設定します。デフォルト：primary。このオプションはcolor_modeオプションとは独立しており、個別に定義する必要があります。

• highlightjs：highlight.js JavaScriptライブラリを使用して、コードブロック内のソースコードの強調表示を有効にします。デフォルト：True。

• hljs_style：highlight.jsライブラリには、コードブロック内のソースコードを強調表示するためのさまざまなスタイル（色のバリエーション）が用意されています。lightモードの場合、目的のスタイルの名前に設定します。デフォルト：github。

• hljs_style_dark：darkモードの場合、目的のhighlight.jsスタイルの名前に設定します。デフォルト：github_dark。

• hljs_languages：デフォルトでは、highlight.jsは23の一般的な言語のみをサポートしています。ここに他の言語を追加して、それらのサポートを含めます。

  theme:
    name: mkdocs
    highlightjs: true
    hljs_languages:
      - yaml
      - rust

• analytics：分析サービスの設定オプションを定義します。現在、Google Analytics v4はgtagオプションを介してのみサポートされています。

  • gtag：Google Analyticsを有効にするには、G-形式を使用するGoogle Analytics v4トラッキングIDに設定します。ウェブサイトやアプリ（GA4）のAnalyticsを設定するまたはGoogle Analytics 4プロパティにアップグレードするGoogleのドキュメントを参照してください。

    theme:
      name: mkdocs
      analytics:
        gtag: G-ABC123

    デフォルト（null）に設定すると、Google Analyticsはサイトで無効になります。

• shortcuts：キーボードショートカットキーを定義します。

  theme:
    name: mkdocs
    shortcuts:
      help: 191    # ?
      next: 78     # n
      previous: 80 # p
      search: 83   # s

  すべての値は数値キーコードである必要があります。すべてのキーボードで使用可能なキーを使用するのが最適です。https://keycode.info/を使用して、特定のキーのキーコードを判断できます。

  • help：キーボードショートカットを一覧表示するヘルプモーダルを表示します。デフォルト：191（？）

  • next：「次へ」のページに移動します。デフォルト：78（n）

  • previous：「前へ」のページに移動します。デフォルト：80（p）

  • search：検索モーダルを表示します。デフォルト：83（s）

• navigation_depth：サイドバーのナビゲーションツリーの最大深度。デフォルト：2。

• locale：テーマを構築するために使用されるロケール（言語/場所）。ロケールがまだサポートされていない場合は、デフォルトに戻ります。

  このテーマでサポートされているロケールは次のとおりです

  • en：英語（デフォルト）
  • de：ドイツ語
  • es：スペイン語
  • fa：ペルシア語
  • fr：フランス語
  • id：インドネシア語
  • it：イタリア語
  • ja：日本語
  • nb：ノルウェー語ブークモール
  • nl：オランダ語
  • nn：ノルウェー語ニーノシュク
  • pl：ポーランド語
  • pt_BR：ポルトガル語（ブラジル）
  • ru：ロシア語
  • tr：トルコ語
  • uk：ウクライナ語
  • zh_CN：中国語（簡体字、中国）
  • zh_TW：中国語（繁体字、台湾）

  詳細については、テーマのローカライズに関するガイドを参照してください。

readthedocs

Read the Docsサービスで使用されるデフォルトテーマのクローンで、親テーマと同じ制限された機能セットを提供します。親テーマと同様に、ナビゲーションは2レベルのみサポートされています。

デフォルトのテーマ設定オプションに加えて、readthedocsテーマは次のオプションをサポートしています。

• highlightjs：highlight.js JavaScriptライブラリを使用して、コードブロック内のソースコードの強調表示を有効にします。デフォルト：True。

• hljs_languages：デフォルトでは、highlight.jsは23の一般的な言語のみをサポートしています。ここに他の言語を追加して、それらのサポートを含めます。

  theme:
    name: readthedocs
    highlightjs: true
    hljs_languages:
      - yaml
      - rust

• analytics：分析サービスの設定オプションを定義します。

  • gtag：Google Analyticsを有効にするには、G-形式を使用するGoogle Analytics v4トラッキングIDに設定します。ウェブサイトやアプリ（GA4）のAnalyticsを設定するまたはGoogle Analytics 4プロパティにアップグレードするGoogleのドキュメントを参照してください。

    theme:
      name: readthedocs
      analytics:
        gtag: G-ABC123

    デフォルト（null）に設定すると、Google Analyticsはこのサイトでは無効になります

  • anonymize_ip：Google Analyticsの匿名IPアドレスを有効にするには、これをTrueに設定します。デフォルト：False。

• include_homepage_in_sidebar：サイドバーメニューにホームページを一覧表示します。MkDocsでは、ホームページをnav設定オプションにリストする必要があるため、この設定により、ホームページをサイドバーに含めるか除外するかを選択できます。サイト名/ロゴは常にホームページにリンクすることに注意してください。デフォルト：True。

• prev_next_buttons_location：bottom、top、both、またはnoneのいずれか。「次へ」ボタンと「前へ」ボタンをそれに応じて表示します。デフォルト：bottom。

• navigation_depth：サイドバーのナビゲーションツリーの最大深度。デフォルト：4。

• collapse_navigation：現在のページのページセクションヘッダーのみをサイドバーに含めます。デフォルト：True。

• titles_only：すべてのページのすべてのセクションヘッダーを除外し、ページタイトルのみをサイドバーに含めます。デフォルト：False。

• sticky_navigation：Trueの場合、ページをスクロールすると、サイドバーがメインページコンテンツとともにスクロールされます。デフォルト：True。

• locale：テーマを構築するために使用されるロケール（言語/場所）。ロケールがまだサポートされていない場合は、デフォルトに戻ります。

  このテーマでサポートされているロケールは次のとおりです

  • en：英語（デフォルト）
  • de：ドイツ語
  • es：スペイン語
  • fa：ペルシア語
  • fr：フランス語
  • id：インドネシア語
  • it：イタリア語
  • ja：日本語
  • nl：オランダ語
  • pl：ポーランド語
  • pt_BR：ポルトガル語（ブラジル）
  • ru：ロシア語
  • tr：トルコ語
  • uk：ウクライナ語
  • zh_CN：中国語（簡体字、中国）
  • zh_TW：中国語（繁体字、台湾）

  詳細については、テーマのローカライズに関するガイドを参照してください。

• logo：プレーンテキストのsite_nameの代わりにプロジェクトにロゴを設定するには、この変数を画像の場所に設定します。デフォルト：null。

サードパーティのテーマ

サードパーティのテーマのリストは、コミュニティWikiページとランク付けされたカタログにあります。独自のテーマを作成した場合は、そこに追加してください。