設定

利用可能なすべての設定項目のガイドです。

はじめに

プロジェクト設定は、デフォルトではプロジェクトディレクトリにあるmkdocs.ymlという名前のYAML設定ファイルを使用して設定されます。-f/--config-fileオプションを使用することで別のパスを指定できます（mkdocs build --helpを参照）。

最低限、この設定ファイルにはsite_nameが含まれている必要があります。その他の設定はすべてオプションです。

プロジェクト情報

site_name

これは必須設定であり、プロジェクトドキュメントのメインタイトルとして使用される文字列である必要があります。例：

site_name: Marshmallow Generator

テーマをレンダリングするとき、この設定はsite_nameコンテキスト変数として渡されます。

site_url

サイトの正規URLを設定します。これにより、各HTMLページのheadセクションにcanonicalURLを含むlinkタグが追加されます。MkDocsサイトの「ルート」がドメインのサブディレクトリ内にある場合は、そのサブディレクトリを必ず設定に含めてください（例：https://example.com/foo/）。

この設定はmkdocs serveにも使用されます。サーバーはURLのパスコンポーネントから取得したパスにマウントされます。たとえば、some/page.mdは、予想されるリモートレイアウトを模倣するためにhttp://127.0.0.1:8000/foo/some/page/から提供されます。

デフォルト: null

repo_url

設定すると、各ページにリポジトリ（GitHub、Bitbucket、GitLabなど）へのリンクが提供されます。

repo_url: https://github.com/example/repository/

デフォルト: null

repo_name

設定すると、各ページのリポジトリへのリンクの名前が提供されます。

デフォルト: 'GitHub'、'Bitbucket'、または'GitLab'（repo_urlがこれらのドメインと一致する場合）、それ以外の場合はrepo_urlのホスト名。

edit_uri

リポジトリホスト（GitHub、Bitbucketなど）、ブランチ、およびドキュメントディレクトリ自体の詳細を考慮して、ページを直接表示するときにベースrepo_urlからドキュメントディレクトリへのパスを指定します。MkDocsはrepo_urlとedit_uriを連結し、ページの入力パスを追加します。

設定されており、テーマがサポートしている場合は、ソースリポジトリ内のページに直接リンクを提供します。これにより、ページのソースを見つけて編集するのが簡単になります。repo_urlが設定されていない場合、このオプションは無視されます。一部のテーマでは、このオプションを設定すると、リポジトリリンクの代わりに編集リンクが使用される場合があります。他のテーマでは、両方のリンクが表示される場合があります。

edit_uriはクエリ（'?'）およびフラグメント（'#'）文字をサポートします。クエリまたはフラグメントを使用してファイルにアクセスするリポジトリホストの場合、edit_uriは次のように設定される可能性があります。（URI内の?と#に注意してください...）

# Query string example
edit_uri: '?query=root/path/docs/'

# Hash fragment example
edit_uri: '#root/path/docs/'

他のリポジトリホストの場合は、ドキュメントディレクトリへの相対パスを指定するだけです。

# Query string example
edit_uri: root/path/docs/

たとえば、この設定がある場合

repo_url: https://example.com/project/repo
edit_uri: blob/main/docs/

「foo/bar.md」という名前のページの編集リンクは、次のようになります。
https://example.com/project/repo/blob/main/docs/foo/bar.md

edit_uriは、必ずしもrepo_urlに対して相対的である必要はなく、絶対URLにすることができます。これにより、同じ結果が得られます。

edit_uri: https://example.com/project/repo/blob/main/docs/

より柔軟性が必要な場合は、以下のedit_uri_templateを参照してください。

注意

一部の既知のホスト（特にGitHub、Bitbucket、GitLab）では、edit_uriは「repo_url」から派生しており、手動で設定する必要はありません。repo_urlを定義するだけで、edit_uriの設定が自動的に設定されます。

たとえば、GitHubまたはGitLabでホストされているリポジトリの場合、edit_uriは自動的にedit/master/docs/として設定されます（editパスとmasterブランチに注意してください）。

Bitbucketでホストされているリポジトリの場合、同等のedit_uriは自動的にsrc/default/docs/として設定されます（srcパスとdefaultブランチに注意してください）。

デフォルト以外のURIを使用する場合（たとえば、別のブランチ）、edit_uriを目的の文字列に設定するだけです。ページに「編集URLリンク」を表示したくない場合は、edit_uriを空の文字列に設定して、自動設定を無効にします。

警告

GitHubおよびGitLabでは、デフォルトの「編集」パス（edit/master/docs/）は、オンラインエディターでページを開きます。この機能を使用するには、ユーザーがGitHub/GitLabアカウントを持っており、ログインしている必要があります。そうでない場合、ユーザーはログイン/サインアップページにリダイレクトされます。または、「blob」パス（blob/master/docs/）を使用して、匿名アクセスをサポートする読み取り専用ビューを開きます。

デフォルト: repo_urlがこれらのドメインと一致する場合は、GitHubおよびGitLabリポジトリの場合はedit/master/docs/、Bitbucketリポジトリの場合はsrc/default/docs/、それ以外の場合はnull

edit_uri_template

edit_uriのより柔軟なバリアントです。この2つは同等です。

edit_uri: 'blob/main/docs/'
edit_uri_template: 'blob/main/docs/{path}'

（それらは相互に排他的でもあります。両方を指定しないでください）。

ここから、パスのデフォルトの動作が不十分な場合に、パスの位置や書式を変更できます。

edit_uri_templateの内容は、通常のPython形式文字列で、次のフィールドのみが利用可能です。

{path}、例：foo/bar.md
{path_noext}、例：foo/bar

また、変換フラグ!qを使用してフィールドをパーセントエンコードできます。

{path!q}、例：foo%2Fbar.md

推奨される便利な設定

GitHub Wiki
（例：https://github.com/project/repo/wiki/foo/bar/_edit）

repo_url: 'https://github.com/project/repo/wiki'
edit_uri_template: '{path_noext}/_edit'

BitBucketエディター
（例：https://bitbucket.org/project/repo/src/master/docs/foo/bar.md?mode=edit）
```
repo_url: 'https://bitbucket.org/project/repo/'
edit_uri_template: 'src/master/docs/{path}?mode=edit'
```
GitLab Static Site Editor
（例：https://gitlab.com/project/repo/-/sse/master/docs%2Ffoo%2bar.md）
```
repo_url: 'https://gitlab.com/project/repo'
edit_uri_template: '-/sse/master/docs%2F{path!q}'
```
GitLab Web IDE
（例：https://gitlab.com/-/ide/project/repo/edit/master/-/docs/foo/bar.md）
```
edit_uri_template: 'https://gitlab.com/-/ide/project/repo/edit/master/-/docs/{path}'
```

デフォルト: null

site_description

サイトの説明を設定します。これにより、生成されたHTMLヘッダーにメタタグが追加されます。

デフォルト: null

site_author

作成者の名前を設定します。これにより、生成されたHTMLヘッダーにメタタグが追加されます。

デフォルト: null

copyright

テーマによってドキュメントに含める著作権情報を設定します。

デフォルト: null

remote_branch

gh-deployを使用してGitHub Pagesにデプロイするときにコミットするリモートブランチを設定します。このオプションは、gh-deployのコマンドラインオプションでオーバーライドできます。

デフォルト: gh-pages

remote_name

gh-deployを使用してGitHub Pagesにデプロイするときにプッシュするリモート名を設定します。このオプションは、gh-deployのコマンドラインオプションでオーバーライドできます。

デフォルト: origin

ドキュメントレイアウト

nav

この設定は、サイトのグローバルナビゲーションの形式とレイアウトを決定するために使用されます。最小限のナビゲーション設定は次のようになります。

nav:
  - 'index.md'
  - 'about.md'

ナビゲーション設定のすべてのパスは、docs_dir設定オプションに対して相対的である必要があります。サブセクションの作成方法など、詳細な内訳については、ページとナビゲーションの設定に関するセクションを参照してください。

ナビゲーション項目には、外部サイトへのリンクを含めることもできます。内部リンクのタイトルはオプションですが、外部リンクの場合は必須です。外部リンクは、完全なURLまたは相対URLにすることができます。ファイルに見つからないパスは、外部リンクであると見なされます。ドキュメントのページタイトルをMkDocsがどのように決定するかについては、メタデータに関するセクションを参照してください。

nav:
  - Introduction: 'index.md'
  - 'about.md'
  - 'Issue Tracker': 'https://example.com/'

上記の例では、最初の2つの項目はローカルファイルを指し、3番目の項目は外部サイトを指します。

ただし、MkDocsサイトがプロジェクトのサイトのサブディレクトリでホストされている場合があり、ドメイン全体を含めずに同じサイトの他の部分にリンクしたい場合があります。その場合は、適切な相対URLを使用できます。

site_url: https://example.com/foo/

nav:
  - Home: '../'
  - 'User Guide': 'user-guide.md'
  - 'Bug Tracker': '/bugs/'

上記の例では、2つの異なるスタイルの外部リンクが使用されています。まず、site_urlはMkDocsサイトがドメインの/foo/サブディレクトリでホストされていることを示していることに注意してください。したがって、Homeナビゲーション項目は、サーバーのルートまで1レベル上がる相対リンクであり、事実上https://example.com/を指します。Bug Tracker項目は、サーバーのルートからの絶対パスを使用しており、事実上https://example.com/bugs/を指します。もちろん、User GuideはローカルのMkDocsページを指します。

デフォルト: デフォルトでは、navにはdocs_dirとそのサブディレクトリ内にあるすべてのMarkdownファイルの英数字順にソートされたネストされたリストが含まれます。インデックスファイルは、常にサブセクション内で最初にリストされます。

exclude_docs

バージョン1.5で新しく追加

バージョン1.6で変更

この設定は、mkdocs serveの「下書き」機能には適用されなくなりました。「serve」で利用可能で「build」で利用できない下書きドキュメントがある場合は、exclude_docsを新しいdraft_docs設定オプションに置き換えてください。

この設定は、ビルドされたサイトに取り込まれないファイル（docs_dirの下）のパターンを定義します。

例

exclude_docs: |
  api-config.json    # A file with this name anywhere.
  /requirements.txt  # Top-level "docs/requirements.txt".
  *.py               # Any file with this extension anywhere.
  !/foo/example.py   # But keep this particular file.

これは、.gitignoreパターン形式に従います。

次のデフォルトは、ドットファイル（およびディレクトリ）と最上位のtemplatesディレクトリを除外するために、常に暗黙的に先頭に付加されます。

exclude_docs: |
  .*
  /templates/

したがって、この設定を本当に最初から開始するには、最初にこれらのエントリの否定されたバージョンを指定する必要があります。

それ以外の場合は、たとえば、特定のドットファイルのみをサイトに含めることを選択できます。

exclude_docs: |
  !.assets  # Don't exclude '.assets' although all other '.*' are excluded

draft_docs

バージョン1.6で新しく追加

この設定は、下書きとして扱われるファイル（docs_dirの下）のパターンを定義します。下書きファイルはmkdocs serve中に利用可能で「下書き」マークが含まれますが、ビルドには含まれません。この効果を防ぎ、「serve」を「build」と同じように動作させるには、mkdocs serve --cleanを実行できます。

例

draft_docs: |
  drafts/               # A "drafts" directory anywhere.
  _unpublished.md       # A md file ending in _unpublished.md
  !/foo_unpublished.md  # But keep this particular file.

これは、.gitignoreパターン形式に従います。

not_in_nav

バージョン1.5で新しく追加

バージョン1.6で新しく追加

もしnav設定が全く指定されていない場合、この設定で指定されたページは、推測されるナビゲーションから除外されるようになります。

サイトにいくつかのドキュメントを含めたいが、意図的にナビゲーションから除外したい場合、通常MkDocsはこれについて警告します。

このようなファイルパターン（docs_dirからの相対パス）をnot_in_nav設定に追加すると、そのような警告を防ぐことができます。

例

nav:
  - Foo: foo.md
  - Bar: bar.md

not_in_nav: |
  /private.md

前のオプションと同様に、これは.gitignoreのパターン形式に従います。

注意

特定のファイルをexclude_docsに追加すると、not_in_navよりも優先され、それを意味します。

検証

バージョン1.5で新しく追加

ドキュメントへのリンクを検証する際のMkDocsの診断メッセージの厳格さを設定します。

これは設定のツリーであり、それぞれの値は、warn、info、ignoreの3つのうちのいずれかになります。これにより、対応する重大度のログメッセージが生成されます。warnレベルは、もちろん、mkdocs build --strict（エラーになる）で使用することを意図しており、継続的テストで利用できます。

設定validation.links.absolute_linksには、さらに絶対リンクの検証のための特別な値relative_to_docsがあります。

MkDocs 1.6時点でのこの設定のデフォルト

validation:
  nav:
    omitted_files: info
    not_found: warn
    absolute_links: info
  links:
    not_found: warn
    anchors: info
    absolute_links: info
    unrecognized_links: info

（注：これはデフォルトを複製するだけなので、この例全体をコピーしないでください。異なる個々の項目のみを設定する必要があります。）

一部の動作のデフォルトは、すでにMkDocs 1.4以前とは異なっています。以前は無視されていました。

MkDocs 1.6がMkDocs 1.4以前のように動作するように設定（厳格さを低減）

validation:
  absolute_links: ignore
  unrecognized_links: ignore
  anchors: ignore

ほとんどのサイトで推奨される設定（最大の厳格さ）

validation:
  omitted_files: warn
  absolute_links: warn  # Or 'relative_to_docs' - new in MkDocs 1.6
  unrecognized_links: warn
  anchors: warn  # New in MkDocs 1.6

上記の例では、'nav'と'links'キーを省略していることに注意してください。ここで、absolute_links:は、nav: absolute_links:とlinks: absolute_links:の両方を設定することを意味します。

値の完全なリストと、それらが隠したり、より目立たせたりする可能性のあるログメッセージの例

validation.nav.omitted_files
- 次のページがドキュメントディレクトリに存在しますが、「nav」設定に含まれていません：...
validation.nav.not_found
- 'foo/bar.md'への参照が'nav'設定に含まれていますが、ドキュメントファイルに見つかりません。
- 'foo/bar.md'への参照が'nav'設定に含まれていますが、このファイルはビルドされたサイトから除外されています。
validation.nav.absolute_links
- '/foo/bar.html'への絶対パスが'nav'設定に含まれています。これはおそらく外部リソースを指しています。

validation.links.not_found
- ドキュメントファイル'example.md'には'../foo/bar.md'へのリンクが含まれていますが、ターゲットはドキュメントファイルに見つかりません。
- ドキュメントファイル'example.md'には、ビルドされたサイトから除外されている'foo/bar.md'へのリンクが含まれています。
validation.links.anchors
- ドキュメントファイル'example.md'には'../foo/bar.md#some-heading'へのリンクが含まれていますが、ドキュメント'foo/bar.md'にはアンカー'#some-heading'が含まれていません。
- ドキュメントファイル'example.md'には'#some-heading'へのリンクが含まれていますが、このページにはそのようなアンカーがありません。
validation.links.absolute_links
- ドキュメントファイル'example.md'には絶対リンク'/foo/bar.html'が含まれています。これはそのままにされました。'foo/bar.md'のことですか？
validation.links.unrecognized_links
- ドキュメントファイル'example.md'には認識されない相対リンク'../foo/bar/'が含まれています。これはそのままにされました。'foo/bar.md'のことですか？
- ドキュメントファイル'example.md'には認識されない相対リンク'mail@example.com'が含まれています。これはそのままにされました。'mailto:mail@example.com'のことですか？

絶対リンクの検証

バージョン1.6で新しく追加

歴史的に、Markdown内では、MkDocsは別の物理的な*.mdドキュメント（またはメディアファイル）につながる相対リンクのみを認識していました。これは、ソースページがMkDocsなしでも、たとえばGitHubで自由に閲覧できるため、従うべき良い慣例です。一方、絶対リンクは変更されないまま（期待どおりに機能しないことが多かった）か、最近では警告されるようになりました。常に相対リンクを使用する必要があるのが嫌な場合は、絶対リンクを選択して、正しく機能させることができます。

設定validation.links.absolute_linksを新しい値relative_to_docsに設定すると、/で始まるすべてのMarkdownリンクは、docs_dirルートからの相対パスとして解釈されます。次に、リンクは、以前のバージョンのMkDocsで相対リンクに対してすでに機能していた他のすべてのルールに従って、正当性が検証されます。HTML出力の場合、これらのリンクは引き続き相対的に変換されるため、サイトは引き続き確実に機能します。

したがって、任意のドキュメント（例： "dir1/foo.md"）は、以前の唯一の正しい方法である[link](../dir2/bar.md)に加えて、[link](/dir2/bar.md)としてドキュメント "dir2/bar.md"にリンクできます。

ただし、設定を有効にする必要があります。デフォルトでは、リンクをスキップするだけです。

絶対リンクを認識して検証するための設定

validation:
  links:
    absolute_links: relative_to_docs
    anchors: warn
    unrecognized_links: warn

ビルドディレクトリ

theme

ドキュメントサイトのテーマとテーマ固有の設定を設定します。文字列またはキーと値のペアのセットのいずれかになります。

文字列の場合、既知のインストール済みテーマの文字列名である必要があります。利用可能なテーマのリストについては、テーマの選択を参照してください。

キーと値のペアのセットの例を次に示します。

theme:
  name: mkdocs
  locale: en
  custom_dir: my_theme_customizations/
  static_templates:
    - sitemap.html
  include_sidebar: false

キーと値のペアのセットの場合、次のネストされたキーを定義できます。

ブロック

name

既知のインストール済みテーマの文字列名。利用可能なテーマのリストについては、テーマの選択を参照してください。

locale

サイトの言語を表すコード。詳細については、テーマのローカライズを参照してください。

custom_dir

カスタムテーマを含むディレクトリ。これは相対ディレクトリにすることもできます。その場合、構成ファイルを含むディレクトリからの相対パスとして解決されます。または、ローカルファイルシステムのルートからの絶対ディレクトリパスにすることもできます。

既存のテーマを調整したい場合は、詳細についてテーマのカスタマイズを参照してください。

ゼロから独自のテーマを構築したい場合は、テーマ開発者ガイドを参照してください。

static_templates

静的ページとしてレンダリングするテンプレートのリスト。テンプレートは、テーマのテンプレートディレクトリまたはテーマ構成で定義されたcustom_dirのいずれかに配置する必要があります。

（テーマ固有のキーワード）

テーマでサポートされている追加のキーワードも定義できます。詳細については、使用しているテーマのドキュメントを参照してください。

default: 'mkdocs'

docs_dir

ドキュメントのソースMarkdownファイルを含むディレクトリ。これは相対ディレクトリにすることもできます。その場合、構成ファイルを含むディレクトリからの相対パスとして解決されます。または、ローカルファイルシステムのルートからの絶対ディレクトリパスにすることもできます。

default: 'docs'

site_dir

出力HTMLおよびその他のファイルが作成されるディレクトリ。これは相対ディレクトリにすることもできます。その場合、構成ファイルを含むディレクトリからの相対パスとして解決されます。または、ローカルファイルシステムのルートからの絶対ディレクトリパスにすることもできます。

default: 'site'

注意

ソースコード管理を使用している場合は、通常、ビルド出力ファイルがリポジトリにコミットされないようにし、ソースファイルのみをバージョン管理下に置くようにする必要があります。たとえば、gitを使用している場合は、.gitignoreファイルに次の行を追加することができます。

site/

別のソースコード管理ツールを使用している場合は、特定のディレクトリを無視する方法についてそのドキュメントを確認する必要があります。

extra_css

テーマで含めるCSSファイル（docs_dirからの相対パス）のリストを、通常は<link>タグとして設定します。

例

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

default: []（空のリスト）。

extra_javascript

docs_dir内のJavaScriptファイルのリストを、テーマで<script>タグとして含めるように設定します。

バージョン1.5で変更

MkDocsの古いバージョンでは、単純な文字列のリストのみがサポートされていましたが、現在では、いくつかの追加の設定キーtype、async、deferが利用可能です。

例とそれらが生成するものを参照してください。

extra_javascript:
  - some_plain_javascript.js       # <script src="some_plain_javascript.js"></script>
        # New behavior in MkDocs 1.5:
  - implicitly_as_module.mjs       # <script src="implicitly_as_module.mjs" type="module"></script>
        # Config keys only supported since MkDocs 1.5:
  - path: explicitly_as_module.mjs # <script src="explicitly_as_module.mjs" type="module"></script>
    type: module
  - path: deferred_plain.js        # <script src="deferred_plain.js" defer></script>
    defer: true
  - path: scripts/async_module.mjs # <script src="scripts/async_module.mjs" type="module" async></script>
    type: module
    async: true

したがって、各項目は次のいずれかになります。

単純な文字列、または
必須のpathキーと3つのオプションキーtype（文字列）、async（ブール値）、defer（ブール値）を持つマッピング。

単純な文字列バリアントのみが.mjs拡張子を検出し、type="module"を追加します。それ以外の場合は、拡張子に関係なくtype: moduleを記述する必要があります。

default: []（空のリスト）。

注意

*.jsおよび*.cssファイルは、他の種類のファイルと同様に、上記の設定を介してページにリンクされているかどうかに関係なく、常にdocs_dirからサイトの展開されたコピーにコピーされます。

extra_templates

MkDocsでビルドされるdocs_dir内のテンプレートのリストを設定します。MkDocsのテンプレートの記述の詳細については、カスタムテーマに関するドキュメントと、特にテンプレートで利用可能な変数に関するセクションをお読みください。使用例については、extra_cssを参照してください。

default: []（空のリスト）。

extra

値が任意の有効なYAML構造にできるキーと値のペアのセットで、テンプレートに渡されます。これにより、カスタムテーマを作成する際に非常に柔軟性が高まります。

たとえば、プロジェクトのバージョンを表示することをサポートするテーマを使用している場合は、次のようにテーマに渡すことができます。

extra:
  version: 1.0

default: デフォルトでは、extraは空のキーと値のマッピングになります。

プレビューコントロール

ライブリロード

watch

mkdocs serve を実行する際に監視する追加ディレクトリを指定します。設定は YAML リストです。

watch:
  - directory_a
  - directory_b

mkdocs serve コマンドが呼び出されるたびに、-w/--watch オプションを渡す必要なく、カスタムのデフォルトを設定できます。

注意

設定ファイルで指定されたパスは、設定ファイルからの相対パスです。

-w/--watch CLI パラメーターで指定されたパスは相対パスではありません。

use_directory_urls

この設定は、生成されたドキュメントのディレクトリ構造、ひいてはページへのリンクに使用される URL 形式を制御します。

次の表は、use_directory_urls を true または false に設定した場合に、サイトで使用されるディレクトリ構造と URL がどのように異なるかを示しています。

use_directory_urls: false

この設定は、URL X が与えられたときにファイル X/index.html にアクセスできないシステムでドキュメントをホストする場合に必要です。false に設定すると、追加の X ディレクトリは作成されず、ファイルは単に X.html として保存されます。リンクは、ターゲットの*ディレクトリ*ではなく、ターゲットの*ファイル*を直接指すように作成されます。

ソースファイル	生成されたファイル	URL 形式
index.md	index.html	/index.html
api-guide.md	api-guide.html	/api-guide.html
about/license.md	about/license.html	/about/license.html

たとえば、これは次の場合に false に設定する必要があります。

ファイルシステムから直接ページを開く場合
ドキュメントを静的 S3 ウェブサイトに公開する場合。

use_directory_urls: true

use_directory_urls: true のデフォルトのスタイルは、よりユーザーフレンドリーな URL を作成し、通常はこれを使用することになります。

ソースファイル	生成されたファイル	URL 形式
index.md	/index.html	/
api-guide.md	/api-guide/index.html	/api-guide/
about/license.md	/about/license/index.html	/about/license/

デフォルト: true

strict

警告の処理方法を決定します。警告が発生したときに処理を停止するには true に設定します。警告を出力して処理を続行するには false に設定します。

これはコマンドラインフラグ --strict としても利用できます。

デフォルト: false

dev_addr

mkdocs serve を実行する際に使用するアドレスを決定します。IP:PORT の形式である必要があります。

mkdocs serve コマンドが呼び出されるたびに、--dev-addr オプションを渡す必要なく、カスタムのデフォルトを設定できます。

デフォルト: '127.0.0.1:8000'

参照: site_url。

書式設定オプション

markdown_extensions

MkDocs は、Markdown ファイルを HTML に変換するために Python Markdown ライブラリを使用します。Python Markdown は、ページの書式設定をカスタマイズするさまざまな拡張機能をサポートしています。この設定を使用すると、MkDocs がデフォルトで使用する拡張機能 (meta、toc、tables、および fenced_code) に加えて、拡張機能のリストを有効にできます。

たとえば、SmartyPants typography extension を有効にするには、次のように使用します。

markdown_extensions:
  - smarty

一部の拡張機能は、独自の設定オプションを提供します。設定オプションを設定する場合は、特定の拡張機能がサポートするオプションのキー/値マッピング (option_name: option value) をネストできます。使用している拡張機能のドキュメントを参照して、どのようなオプションがサポートされているかを確認してください。

たとえば、(含まれている) toc 拡張機能でパーマリンクを有効にするには、次のように使用します。

markdown_extensions:
  - toc:
      permalink: true

コロン (:) が拡張機能名 (toc) の後に続き、新しい行でオプション名と値をインデントしてコロンで区切る必要があることに注意してください。単一の拡張機能に複数のオプションを定義する場合は、各オプションを別々の行で定義する必要があります。

markdown_extensions:
  - toc:
      permalink: true
      separator: "_"

拡張機能ごとに追加の項目をリストに追加します。特定の拡張機能に設定する設定オプションがない場合は、その拡張機能のオプションを省略するだけです。

markdown_extensions:
  - smarty
  - toc:
      permalink: true
  - sane_lists

動的な設定値

拡張機能を動的に設定するために、環境変数から設定値を取得したり、現在レンダリングされている Markdown ファイルまたは MkDocs サイト全体のパスを取得したりできます。

上記の例では、各拡張機能はリスト項目 (- で始まる) です。代替として、キー/値ペアを代わりに使用できます。ただし、その場合はオプションが定義されていない拡張機能に対して空の値を指定する必要があります。したがって、上記の最後の例は次のように定義することもできます。

markdown_extensions:
  smarty: {}
  toc:
    permalink: true
  sane_lists: {}

この代替構文は、継承を介して一部のオプションをオーバーライドする場合に必要です。

その他の拡張機能

Python-Markdown のドキュメントには、すぐに利用できる拡張機能のリストが用意されています。特定の拡張機能で使用できる設定オプションのリストについては、その拡張機能のドキュメントを参照してください。

さまざまなサードパーティ製拡張機能 (Python-Markdown wiki、MkDocs プロジェクトカタログ) をインストールして使用することもできます。インストール手順と利用可能な設定オプションについては、これらの拡張機能によって提供されるドキュメントを参照してください。

default: []（空のリスト）。

hooks

バージョン 1.4 で新規追加

mkdocs.yml を基準とした、プラグインインスタンスとしてロードおよび使用される Python スクリプトへのパスのリスト。

たとえば

hooks:
  - my_hooks.py

すると、ファイル my_hooks.py には、任意のプラグインイベントハンドラー (self なし) を含めることができます。例:

def on_page_markdown(markdown, **kwargs):
    return markdown.replace('a', 'z')

高度な例

これにより、Markdown コンテンツに基づいて警告が生成されます (および strict モードでは警告は致命的です)。

import logging, re
import mkdocs.plugins

log = logging.getLogger('mkdocs')

@mkdocs.plugins.event_priority(-50)
def on_page_markdown(markdown, page, **kwargs):
    path = page.file.src_uri
    for m in re.finditer(r'\bhttp://[^) ]+', markdown):
        log.warning(f"Documentation file '{path}' contains a non-HTTPS link: {m[0]}")

これは、プラグインと比較して新しい機能を追加するものではありません。プラグインのようにインストールする必要がないため、1 回限りの使用が簡略化されるだけです。

mkdocs serve の場合、フックモジュールはビルドごとにリロードされないことに注意してください。

mkdocs-simple-hooks プラグインでこの機能を見たことがあるかもしれません。標準のメソッド名を使用している場合は、直接置き換えることができます。例:

-plugins:
-  - mkdocs-simple-hooks:
-      hooks:
-        on_page_markdown: 'my_hooks:on_page_markdown'
+hooks:
+  - my_hooks.py

MkDocs 1.6 で新規追加

フックファイルに隣接する foo.py ファイルがある場合、通常の Python 構文 import foo を使用してその関数にアクセスできます。

古いバージョンの MkDocs では、これを行うために sys.path にパスを追加するという回避策が必要でした。

plugins

サイトの構築時に使用するプラグインのリスト (オプションの設定付き)。詳細については、プラグインのドキュメントを参照してください。

デフォルト: ['search'] (MkDocs に含まれる "search" プラグイン)。

mkdocs.yml 設定ファイルで plugins 設定が定義されている場合、デフォルト (search など) は無視され、引き続き使用する場合はデフォルトを明示的に再度有効にする必要があります。

plugins:
  - search
  - your_other_plugin

特定のプラグインのオプションを定義するには、キー/値ペアのネストされたセットを使用します。

plugins:
  - search
  - your_other_plugin:
      option1: value
      option2: other value

デフォルトを含むすべてのプラグインを完全に無効にするには、plugins 設定を空のリストに設定します。

plugins: []

`enabled` オプション

MkDocs 1.6 で新規追加

各プラグインには、独自のオプションキーがあります。ただし、MkDocs では、各プラグインに enabled ブールオプションがあることも保証されています。これは、次の例のように、特定のプラグインを条件付きで有効にするために使用できます。

plugins:
  - search
  - code-validator:
      enabled: !ENV [LINT, false]

参照: 環境変数

代替構文

上記の例では、各プラグインはリスト項目 (- で始まる) です。代替として、キー/値ペアを代わりに使用できます。ただし、その場合はオプションが定義されていないプラグインに対して空の値を指定する必要があります。したがって、上記の最後の例は次のように定義することもできます。

plugins:
  search: {}
  your_other_plugin:
    option1: value
    option2: other value

この代替構文は、継承を介して一部のオプションをオーバーライドする場合に必要です。

Search

検索プラグインは、検索エンジンとして lunr.js を使用する MkDocs によってデフォルトで提供されます。次の設定オプションは、検索プラグインの動作を変更するために使用できます。

separator

インデックスを構築するときに単語区切り文字として使用される文字に一致する正規表現。デフォルトでは、空白とハイフン (-) が使用されます。単語区切り文字としてドット (.) を追加するには、次のようにします。

plugins:
  - search:
      separator: '[\s\-\.]+'

デフォルト: '[\s\-]+'

min_search_length

検索クエリの最小長を定義する整数値。デフォルトでは、検索結果の品質が短い検索語では低いため、長さが 3 文字未満の検索は無視されます。ただし、一部のユースケース (「MQ」の検索を生成する可能性のあるメッセージキューに関するドキュメントなど) では、短い制限を設定することをお勧めします。

plugins:
  - search:
      min_search_length: 2

デフォルト: 3

lang

ISO 639-1 言語コードで識別される検索インデックスを構築するときに使用する言語のリスト。Lunr Languages では、次の言語がサポートされています。

ar: アラビア語
da: デンマーク語
nl: オランダ語
en: 英語
fi: フィンランド語
fr: フランス語
de: ドイツ語
hu: ハンガリー語
it: イタリア語
ja: 日本語
no: ノルウェー語
pt: ポルトガル語
ro: ルーマニア語
ru: ロシア語
es: スペイン語
sv: スウェーデン語
th: タイ語
tr: トルコ語
vi: ベトナム語

追加の言語を貢献できます。

警告

検索では複数の言語を一緒に使用できますが、本当に必要な場合を除き、追加の言語を追加しないことをお勧めします。追加の言語ごとに、必要な帯域幅が大幅に増え、より多くのブラウザリソースが使用されます。一般的に、MkDocs の各インスタンスを単一の言語に保つことをお勧めします。

注意

Lunr Languages には現在、中国語またはその他のアジア言語のサポートは含まれていません。ただし、一部のユーザーは日本語を使用して適切な結果が得られたと報告しています。

デフォルト: theme.locale が設定されている場合はその値、それ以外の場合は [en]。

prebuild_index

オプションで、すべてのページの事前構築済みインデックスを生成できます。これにより、大規模なサイトでパフォーマンスが向上します。有効にする前に、使用しているテーマが事前構築済みインデックスの使用を明示的にサポートしていることを確認してください（組み込みテーマはサポートしています）。有効にするには、true に設定します。

警告

このオプションを使用するには、Node.js がインストールされており、コマンド node がシステムパス上にある必要があります。何らかの理由で node の呼び出しに失敗した場合、警告が発行されますが、ビルドは中断されずに続行されます。このような失敗をエラーとして発生させるには、ビルド時に --strict フラグを使用できます。

注意

小規模なサイトでは、事前構築済みインデックスを使用することは、ユーザーの体感的な改善がほとんどないにもかかわらず、帯域幅の要件が大幅に増加するため推奨されません。ただし、大規模なサイト（数百ページ）では、帯域幅の増加は比較的小さく、ユーザーは検索パフォーマンスの大幅な向上に気付くでしょう。

デフォルト: False

インデックス作成

ページのインデックスを作成するときに検索インデクサーが使用する戦略を設定します。このプロパティは、プロジェクトが大規模で、インデックスが大量のディスクスペースを消費する場合に特に役立ちます。

plugins:
  - search:
      indexing: 'full'

オプション

オプション	説明
`full`	各ページのタイトル、セクション見出し、および全文をインデックス化します。
`sections`	各ページのタイトルとセクション見出しをインデックス化します。
`titles`	各ページのタイトルのみをインデックス化します。

デフォルト: full

特別な YAML タグ

環境変数

ほとんどの場合、構成オプションの値は構成ファイルで直接設定されます。ただし、オプションとして、構成オプションの値を !ENV タグを使用して環境変数の値に設定できます。たとえば、site_name オプションの値を変数 SITE_NAME の値に設定するには、YAML ファイルに次を含めることができます。

site_name: !ENV SITE_NAME

環境変数が定義されていない場合、構成設定には null (または Python では None) 値が割り当てられます。デフォルト値はリストの最後の値として定義できます。こんな感じです。

site_name: !ENV [SITE_NAME, 'My default site name']

複数のフォールバック変数も使用できます。最後の値は環境変数ではなく、指定された環境変数のいずれも定義されていない場合に使用するデフォルト値である必要があることに注意してください。

site_name: !ENV [SITE_NAME, OTHER_NAME, 'My default site name']

文字列、ブール値、整数、浮動小数点数、日付スタンプ、null などの環境変数内で定義された単純な型は、YAML ファイルで直接定義された場合と同様に解析されます。つまり、値は適切な型に変換されます。ただし、リストやキー/値ペアなどの複合型は、単一の環境変数内で定義することはできません。

詳細については、pyyaml_env_tag プロジェクトを参照してください。

現在のファイルまたはサイトを基準とするパス

バージョン1.5で新しく追加

一部の Markdown 拡張機能は、現在処理中の Markdown ファイルのパス、または現在のサイトのルートパスを知ることでメリットが得られます。そのため、構成ファイル内のほとんどのコンテキストで特別なタグ !relative を使用できますが、既知のユースケースは markdown_extensions 内のみです。

可能な値の例を以下に示します。

- !relative  # Relative to the directory of the current Markdown file
- !relative $docs_dir  # Path of the docs_dir
- !relative $config_dir  # Path of the directory that contains the main mkdocs.yml
- !relative $config_dir/some/child/dir  # Some subdirectory of the root config directory

(ここで、$docs_dir および $config_dir は現在認識されている唯一の特別なプレフィックスです。)

例

markdown_extensions:
  - pymdownx.snippets:
      base_path: !relative  # Relative to the current Markdown file

これにより、pymdownx.snippets 拡張機能は、現在の Markdown ファイルを基準としたファイルを含めることができます。このタグがないと、パスを知る方法はありません。

注意

デフォルトの場合でも、拡張機能のベースパスは技術的には現在の作業ディレクトリですが、mkdocs.yml のディレクトリであると想定されています。したがって、パスを相対パスにしたくない場合でも、デフォルトの動作を改善するために、常にこのイディオムを使用することをお勧めします。

markdown_extensions:
  - pymdownx.snippets:
      base_path: !relative $config_dir  # Relative to the root directory with mkdocs.yml

構成の継承

通常、1つのファイルにサイト全体の構成が保持されます。ただし、一部の組織では、複数のサイトを管理し、それらすべてで共通の構成を共有する場合があります。それぞれに個別の構成を保持するのではなく、共通の構成オプションは、各サイトのプライマリ構成ファイルが継承する親構成ファイルで定義できます。

構成ファイルの親を定義するには、INHERIT (すべて大文字) キーを親ファイルのパスに設定します。パスは、プライマリファイルの場所を基準とする必要があります。

構成オプションを親構成とマージするには、それらのオプションをキー/値ペアとして定義する必要があります。特に、markdown_extensions および plugins オプションは、リスト項目を使用しない（- で始まる行）代替構文を使用する必要があります。

たとえば、共通（親）構成が base.yml で定義されているとします。

theme:
  name: mkdocs
  locale: en
  highlightjs: true

markdown_extensions:
  toc:
    permalink: true
  admonition: {}

次に、"foo" サイトの場合、プライマリ構成ファイルは foo/mkdocs.yml で定義されます。

INHERIT: ../base.yml
site_name: Foo Project
site_url: https://example.com/foo

mkdocs build を実行すると、foo/mkdocs.yml のファイルが構成ファイルとして渡されます。MkDocs は次に、そのファイルを解析し、親ファイル base.yml を取得して解析し、2つをディープマージします。これにより、MkDocs は次のマージされた構成を受け取ります。

site_name: Foo Project
site_url: https://example.com/foo

theme:
  name: mkdocs
  locale: en
  highlightjs: true

markdown_extensions:
  toc:
    permalink: true
  admonition: {}

ディープマージを使用すると、プライマリ構成ファイル内のさまざまな値を追加および/または上書きできます。たとえば、あるサイトで定義リストのサポートを追加し、パーマリンクに異なる記号を使用し、異なる区切り文字を定義するとします。そのサイトのプライマリ構成ファイルで、次のように行うことができます。

INHERIT: ../base.yml
site_name: Bar Project
site_url: https://example.com/bar

markdown_extensions:
  def_list: {}
  toc:
    permalink: 
    separator: "_"

この場合、上記の構成は base.yml とディープマージされ、次の構成になります。

site_name: Bar Project
site_url: https://example.com/bar

theme:
  name: mkdocs
  locale: en
  highlightjs: true

markdown_extensions:
  def_list: {}
  toc:
    permalink: 
    separator: "_"
  admonition: {}

admonition 拡張機能が親構成から保持され、def_list 拡張機能が追加され、toc.permalink の値が置き換えられ、toc.separator の値が追加されたことに注意してください。

任意のキーの値を置き換えたり、マージしたりできます。ただし、キー以外のものは常に置き換えられます。したがって、リストに項目を追加することはできません。リスト全体を再定義する必要があります。

nav 構成はネストされたリストで構成されているため、ナビゲーション項目をマージできないことを意味します。もちろん、nav 構成全体を新しい構成に置き換えることはできます。ただし、通常、ナビゲーション全体はプロジェクトのプライマリ構成ファイルで定義されることが想定されています。

警告

念のため、パスベースのすべての構成オプションはプライマリ構成ファイルからの相対パスである必要があり、MkDocs はマージ時にパスを変更しません。したがって、複数の異なるサイトで継承される親ファイルでパスを定義すると、期待どおりに機能しない場合があります。パスベースのオプションは、一般的にプライマリ構成ファイルでのみ定義するのが最適です。

継承は、コマンドラインでキーを上書きする簡単な方法としても使用できます。stdin を構成ファイルとして使用するなどです。例:

echo '{INHERIT: mkdocs.yml, site_name: "Renamed site"}' | mkdocs build -f -

キー	アクション
`?`	このヘルプを開く
`n`	次のページ
`p`	前のページ
`s`	検索

設定

はじめに

プロジェクト情報

site_name

site_url

repo_url

repo_name

edit_uri

edit_uri_template

site_description

site_author

copyright

remote_branch

remote_name

ドキュメントレイアウト

nav

exclude_docs

draft_docs

not_in_nav

検証

絶対リンクの検証

ビルドディレクトリ

theme

name

locale

custom_dir

static_templates

（テーマ固有のキーワード）

docs_dir

site_dir

extra_css

extra_javascript

extra_templates

extra

プレビューコントロール

ライブリロード

watch

use_directory_urls

strict

dev_addr

書式設定オプション

markdown_extensions

hooks

plugins

enabled オプション

代替構文

Search

separator

min_search_length

lang

prebuild_index

インデックス作成

オプション

特別な YAML タグ

環境変数

現在のファイルまたはサイトを基準とするパス

構成の継承

`enabled` オプション