リリースノート

アップグレード

MkDocsを最新バージョンにアップグレードするには、pipを使用してください。

pip install -U mkdocs

現在インストールされているバージョンは、mkdocs --versionで確認できます。

$ mkdocs --version
mkdocs, version 1.5.0 from /path/to/mkdocs (Python 3.10)

メンテナンスチーム

MkDocsチームの現在および過去のメンバー。

バージョン 1.6.1 (2024-08-30)

修正

  • 環境変数SOURCE_DATE_EPOCH=0が設定されている場合のビルドエラーを修正しました。#3795
  • mkdocs_theme.yml設定が空の場合のビルドエラーを修正しました。#3700
  • 設定を上書きするのではなく、python -WとPYTHONWARNINGSをサポートしました。#3809
  • 0.0.0.0開発サーバーの警告を削除することにより、厳密モードでDockerで実行することをサポートしました。#3784
  • sitemap.xmlから不要なchangefreqを削除しました。#3629
  • メニューのドロップダウンを閉じるときのJavaScriptコンソールエラーを修正しました。#3774
  • 繰り返しクリックで発生するJavaScriptコンソールエラーを修正しました。#3730
  • ドロップダウン選択で発生する可能性のあるJavaScriptコンソールエラーを修正しました。#3694

追加

  • オランダ語の翻訳を追加しました。#3804
  • 中国語（簡体字）の翻訳を追加および更新しました。#3684

バージョン 1.6.0 (2024-04-20)

ローカルプレビュー

  • mkdocs serveは、5つ以上のタブが開いているときにブラウザをロックしなくなりました。これは、タブが非アクティブになるたびにポーリング接続を閉じることで実現されます。バックグラウンドタブも自動リロードしなくなります。代わりに、タブが再び開かれたときに発生します。コンテキスト：#3391

  • 新しいフラグserve --openを追加しました。これにより、ブラウザでサイトを開きます。
    最初のビルドが完了すると、このフラグにより、デフォルトのOS Webブラウザがローカルサイトのホームページで開かれます。
    コンテキスト：#3500

ドラフト

バージョン1.5から変更

exclude_docs設定が2つの別々の概念に分割されました。

exclude_docs設定には、mkdocs serveの特別な動作がなくなりました。リストされたドキュメントは常にサイトから完全に除外されるようになりました。

MkDocs 1.5でexclude_docsキーが行っていたように「ドラフト」機能を使用したい場合は、新しい設定キーdraft_docsに切り替えてください。

ドキュメントを参照してください。

その他の変更

  • 「ドラフト」ページに存在しないファイルへのリンクがある場合、警告レベルを下げます。コンテキスト：#3449

ページタイトルの推測の更新

MkDocs 1.5では、最初の見出しからページタイトルを推測する動作が変更されました。残念ながら、これにより、エッジケースでエスケープされていないHTMLタグまたはエンティティが表示される可能性がありました。

タグはタイトルから常に完全にサニタイズされるようになりました。ただし、Page.titleにはHTMLエンティティが含まれている必要があり、テーマに直接渡されることに変わりはありません。

画像（特に、一部の拡張機能の絵文字）は、alt属性の値を通じてのみタイトルに保持されます。

コンテキスト：#3564、#3578

テーマ

  • 組み込みテーマがポーランド語もサポートするようになりました（#3613）

「readthedocs」テーマ

  • 修正：「readthedocs」テーマで、深くネストされたナビゲーション構成（3レベル以上）を正しく処理できるようになりました。これにより、すべてのセクションが混乱して展開され、垂直方向にジャンプすることはありません。（#3464）

  • 修正：「readthedocs」テーマで、既知の3つのホストのいずれでない場合でも、リポジトリへのリンク（汎用ロゴ付き）が表示されるようになりました。（#3435）

  • 「readthedocs」テーマには、フッターにある「テーマ」という単語の翻訳も追加されました。これは誤って常に英語のままでした。（#3613、#3625）

「mkdocs」テーマ

「mkdocs」テーマは、新しいバージョンのBootstrapに大幅に更新され、スタイルがわずかに見直されました。色（特に注意書きの色）のコントラストが大幅に向上しました。

「mkdocs」テーマで、ダークモードのサポートが追加されました。これは、自動（OS/ブラウザの設定に基づく）と手動トグルの両方があります。これらのオプションはどちらもデフォルトで有効になっていません。明示的に設定する必要があります。
ドキュメントのcolor_mode、user_color_mode_toggleを参照してください。

破壊的変更の可能性

jQueryは「mkdocs」テーマに含まれなくなりました。スクリプトでjQueryに依存していた場合は、最初に追加スクリプトとして（mkdocs.ymlに）個別に追加する必要があります。

extra_javascript:
  - https://code.jquery.com/jquery-3.7.1.min.js

または、スクリプトファイルがドキュメントディレクトリからコピーおよび含まれている場合はさらに良いです。

コンテキスト：#3493、#3649

設定

すべてのプラグインの新しい「enabled」設定

プラグインの中には、プラグインを何もしないようにするために、enabled: false（または通常は環境変数で制御される）という設定があるという慣習を採用しているものがあったかもしれません。

現在、すべてのプラグインにこの設定があります。プラグインは、この設定を自分で実装し、その動作を決定することを選択できます（以前のバージョンのMkDocsを削除しない限り、当面は引き続き行う必要があります）。ただし、すべてのプラグインに常にフォールバックがあります。

ドキュメントを参照してください。コンテキスト：#3395

検証

従来、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" にリンクできるようになりました。

ただし、この設定を有効にする必要があります。デフォルトでは、このようなリンクの処理はスキップされます。

ドキュメントを参照してください。背景：#3485

nav:設定内の絶対リンクも常にスキップされていました。validation.nav.absolute_linksを使用すると、同じ方法で検証することも可能になりました。ただし、この構文は先頭のスラッシュなしで記述できる構文と冗長になるため、あまり意味がありません。

アンカー

警告を有効にすることが推奨される新しい設定があります。

validation:
  anchors: warn

これが生成する可能性のある警告の例

WARNING -  Doc file 'foo/example.md' contains a link '../bar.md#some-heading', but the doc 'foo/bar.md' does not contain an anchor '#some-heading'.

以下に示すアンカーを宣言するいずれの方法も、MkDocsによって検出されます

## Heading producing an anchor

## Another heading {#custom-anchor-for-heading-using-attr-list}

<a id="raw-anchor"></a>

[](){#markdown-anchor-using-attr-list}

アンカーを挿入するプラグインおよび拡張機能は、これと互換性を持たせるために、生のHTMLではなく、etree要素を操作モードとして挿入するtreeprocessorとして開発する必要があります。これは、この目的では検出できないためです。

ユーザーとして、誤って報告された欠落アンカーに対処していて、これを解決する方法がない場合は、このオプションをignoreに設定することで、これらのメッセージを無効にすることができます（デフォルトではINFOレベルです）。

ドキュメントを参照してください。背景：#3463

その他の変更

  • nav設定がまったく指定されていない場合、not_in_nav設定（当初は1.5.0で追加）は追加の動作を取得します。not_in_navでカバーされるドキュメントは、自動的に推測されるナビゲーションの一部にはなりません。背景：#3443

  • 修正：markdown_extensionsの!relative YAMLタグ（当初は1.5.0で追加） - 多くの典型的なユースケースで壊れていました。

    ドキュメントを参照してください。背景：#3466

  • 構成の検証は、奇妙な二次エラーが表示されないように、最初のエラーで終了するようになりました。背景：#3437

  • MkDocsは、「ファイルが見つかりません」などの予期しないエラーに対するエラーメッセージを短縮していましたが、そうではなくなりました。完全なエラーメッセージとスタックトレースが表示されます（エラーに適切なハンドラーがある場合は除く）。背景：#3445

プラグイン開発者向けのアップグレード

プラグインは、複数の優先度で同じイベントタイプの複数のハンドラーを追加できます

mkdocs.plugins.CombinedEventについては、ドキュメントを参照してください。背景：#3448

真の生成されたファイルを有効にし、File APIを拡張

ドキュメントを参照してください。

  • ファイルのコンテンツを取得するための公式APIとなる、新しい属性のペアFile.content_string/content_bytesが追加され、MkDocs自身で使用されます。

    これは、File.abs_src_pathにあるファイルを手動で読み取る必要があった古いアプローチに代わるものですが、これは依然としてこれらの新しい属性が内部で行う主なアクションです。

  • Fileのコンテンツは文字列によって裏付けられることができ、abs_src_pathに存在する実際のファイルである必要はなくなりました。

    属性File.content_stringまたはFile.content_bytesを設定することが可能であり、abs_src_pathよりも優先されます。

    さらに、abs_src_pathが存在することが保証されなくなり、代わりにNoneになる可能性があります。MkDocs自体はすべての場合で物理ファイルを使用しますが、最終的にはこの属性を設定しないプラグインが登場するでしょう。

  • プラグインがFile()コンストラクターの代わりに使うべき新しいコンストラクターFile.generated()があります。docs_dirやuse_directory_urlsなどの値を手動で探す必要がないため、はるかに便利です。そのシグネチャは次のいずれかです。

    f = File.generated(config: MkDocsConfig, src_uri: str, content: str | bytes)
f = File.generated(config: MkDocsConfig, src_uri: str, abs_src_path: str)

    このように、フックからでも仮想ファイルを追加するのが非常に簡単になりました

    def on_files(files: Files, config: MkDocsConfig):
    files.append(File.generated(config, 'fake/path.md', content="Hello, world!"))

    大きなコンテンツの場合は、物理ファイルを使用するのが最適ですが、偽の未使用のdocs_dirを指定してパスを操作する必要はなくなりました。

  • 規約により生まれた新しい属性File.generated_byがあります。生成されたファイルの場合、このファイルを作成したプラグインの名前（plugins:コレクションのキー）に設定する必要があります。この属性は、File.generated()コンストラクターを使用すると自動的に設定されます。

  • プラグインまたはフックからなど、Fileのedit_uri属性を設定してデフォルト（src_uriと同じ）とは異なるようにすることができ、これはドキュメントの編集リンクに反映されます。これは、一部のページが実際のファイルで裏付けられておらず、代わりに他のソースファイルまたはスクリプトから動的に作成される場合に役立ちます。したがって、フックはedit_uriをそのソースファイルまたはスクリプトに設定できます。

  • Fileオブジェクトは、元のsrc_dir、dest_dir、use_directory_urlsの値を属性として保存するようになりました。

  • Fileのフィールドは要求に応じて計算されますが、キャッシュされます。上記の3つの属性のみが主要な属性であり、部分的にdest_uriも同様です。このように、例えばFileのdest_uriを上書きすることができ、abs_dest_pathはそれに基づいて計算されます。ただし、値をキャッシュしているため、最初にdel f.abs_dest_pathを使用して属性をクリアする必要があります。

  • Fileインスタンスはハッシュ可能になりました（dictのキーとして使用できます）。2つのファイルは、完全に同じFileのインスタンスでない限り、「等しい」とは見なされなくなりました。

その他の変更

  • Filesオブジェクト内のFileオブジェクトの内部ストレージが再設計されたため、Files._filesにアクセスすることを選択したプラグインには、非推奨の警告が表示されます。

  • Filesコレクション内のFileオブジェクトの順序は、navを自動的に推測する場合、重要ではなくなりました。デフォルトのアルファベット順に従って強制的にソートされます。

背景：#3451、#3463

フックとデバッグ

  • フックファイルは、importステートメントを使用して隣接する*.pyファイルをインポートできるようになりました。以前は、これはsys.pathの回避策を通じてのみ可能でした。ドキュメントの新しい記述を参照してください。背景：#3568

  • 詳細な-vログは、プラグインイベントのシーケンスをより詳細に表示します。イベントタイプだけでなく、呼び出された各プラグインを1つずつ表示します。背景：#3444

非推奨

  • Python 3.7はサポートされなくなり、Python 3.12が正式にサポートされます。背景：#3429

  • テーマ構成ファイルmkdocs_theme.ymlはYAMLタグを実行しなくなりました。背景：#3465

  • プラグインイベントon_page_read_sourceは、常にそれよりも優れた代替手段があるため（目的の相互作用に応じて、新しいFile APIまたは単にon_page_markdownを参照）、ソフト非推奨となりました。

    複数のプラグイン/フックがこのイベントハンドラーを適用すると、互いに上書きするため、その場合には警告が表示されるようになりました。

    ドキュメントを参照してください。背景：#3503

APIの非推奨

  • File.page に Page またはそのサブクラス以外の型を設定することが許可されなくなりました。背景: #3443 - バージョン 1.5.3 での非推奨化と #3381 に続くものです。

  • Theme._vars は非推奨になりました。theme._vars['foo'] の代わりに theme['foo'] を使用してください。

  • utils: modified_time(), get_html_path(), get_url_path(), is_html_file(), is_template_file() が削除されました。path_to_url() は非推奨になりました。

  • LiveReloadServer.watch() は、カスタムコールバックを受け付けなくなりました。

背景: #3429

その他

  • sitemap.xml.gz ファイルは、わずかに再現性が向上し、ビルドごとに変更されるのではなく、1日に1回（日付が変わるとき）のみ変更されるようになりました。背景: #3460

その他の小さな改善点。 コミットログを参照してください。

バージョン 1.5.3 (2023-09-18)

  • mkdocs serve が高速にナビゲートすると、すべてのブラウザータブがロックされることがある問題を修正しました (#3390)

  • "search" プラグインでサポートされる新しい言語を多数追加しました - lunr-languages を 1.12.0 に更新しました (#3334)

  • バグ修正 (1.5.0 での回帰): "readthedocs" テーマで、ネストされたページの「パンくずリストナビゲーション」のスタイルが壊れていました (#3383)

  • 組み込みテーマで、中国語（繁体字、台湾）もサポートされるようになりました (#3154)

  • プラグインは File.page を Page の独自のサブクラスに設定できるようになりました。また、File.page が Page の厳密なサブクラス以外に設定されている場合は警告が表示されるようになりました。 (#3367, #3381)

    Page をインスタンス化するだけで、ファイルが自動的に設定されるため、不要な Page を作成しないように注意する必要があります。

その他の小さな改善点。 コミットログを参照してください。

バージョン 1.5.2 (2023-08-02)

  • バグ修正 (1.5.0 での回帰): --no-livereload の機能を復元しました。 (#3320)

  • バグ修正 (1.5.0 での回帰): 新しいページタイトルの検出が、アンカーリンクを削除できない場合がありました。これを修正しました。(#3325)

  • 1.5 より前の API を部分的に復活させました。extra_javascript の項目は、ほとんどの場合、文字列に戻り、追加の script 機能が使用されている場合にのみ、ExtraScriptValue になるようになりました。

    プラグインは、config.extra_javascript に自由に文字列を追加できますが、値を読み取る際には、それが ExtraScriptValue 項目である場合に備えて、str(value) として読み取る必要があります。.type などの属性を照会するには、最初に isinstance を確認する必要があります。静的型チェックがそれをガイドします。(#3324)

コミットログを参照してください。

バージョン 1.5.1 (2023-07-28)

  • バグ修正 (1.5.0 での回帰): ExtraScriptValue をパスとして扱うことができるようにしました。これにより、一部のプラグインは破壊的な変更にもかかわらず、引き続き機能します。

  • バグ修正 (1.5.0 での回帰): index.html、index.md、および README.md のような 3 つの競合するファイルを持つ特別な設定のエラーを防止しました。 (#3314)

コミットログを参照してください。

バージョン 1.5.0 (2023-07-26)

新しいコマンド mkdocs get-deps

このコマンドは、MkDocs サイトのビルドに必要な Python の依存関係を推測します。インストールする必要がある PyPI パッケージを単純に出力します。ターミナルでは、次のようにインストールコマンドと直接組み合わせることができます。

pip install $(mkdocs get-deps)

このコマンドを実行した直後に mkdocs build を実行すると、インストールする依存関係を考える必要なく、ほとんどの場合「すぐに動作する」ようにすることを意図しています。

その仕組みは、mkdocs.yml で themes:、plugins:、markdown_extensions: 項目をスキャンし、既知のプロジェクトの大規模なリスト（カタログ、下記参照）に基づいて逆引きを行うことです。

もちろん、このようなコマンドで「virtualenv」を使用することもできます。また、安定性が必要な環境（CI など）の場合、この方法で依存関係を直接インストールすることは、依存関係のピン留めを妨げるため、あまり信頼できるアプローチではないことに注意してください。

このコマンドでは、使用する構成ファイル（現在のディレクトリの mkdocs.yml の代わりに）や、使用するプロジェクトのカタログ（デフォルトの場所からダウンロードする代わりに）をオーバーライドできます。 mkdocs get-deps --help を参照してください。

背景: #3205

MkDocs には公式のプラグインカタログがあります

https://github.com/mkdocs/catalog をチェックして、すべての汎用プラグイン、テーマ、拡張機能をそこに追加してください。これにより、mkdocs get-deps で検索できるようになります。

これは「best-of-mkdocs」から名前が変更され、大幅な更新を受けました。pip インストールコマンドに加えて、ページにはプラグインを追加するために必要な構成ボイラープレートが表示されるようになりました。

ご存知かもしれませんが、Markdown 内では、MkDocs は別の物理的な *.md ドキュメント（またはメディアファイル）につながる相対リンクのみを認識します。これは、ソースページを MkDocs なしでも、たとえば GitHub で自由に閲覧できるため、従うべき良い慣習です。MkDocs は、出力でこれらの *.md リンクを必要に応じて *.html に変換する必要があることを認識しており、そのようなリンクが実際に既存のファイルにつながっていない場合は、常に通知します。

ただし、リンクのチェックは非常に緩く、多くの譲歩がありました。たとえば、/（「絶対」）で始まるリンクや、/で終わるリンクはそのまま残され、警告は表示されませんでした。これにより、現在では機能するものの検証が行われない非常に脆弱なリンクや、use_directory_urls が有効になっている場合に、混乱を招くような追加の .. レベルが必要なリンクがサイトソースに潜入する可能性がありました。

現在、相対リンクの検証に加えて、MkDocs は認識されないタイプのリンク（絶対リンクを含む）に対して INFO メッセージを出力します。それらは次のようになります。

INFO - Doc file 'example.md' contains an absolute link '/foo/bar/', it was left as is. Did you mean 'foo/bar.md'?

変更（INFO メッセージも）を一切行わず、MkDocs 1.4 からの沈黙に戻したい場合は、次の構成を mkdocs.yml に追加してください（推奨されません）。

validation:
  absolute_links: ignore
  unrecognized_links: ignore

反対に、これらを WARNING メッセージとして出力し、mkdocs build --strict を失敗させたい場合は、代わりにこれらを warn に構成することをお勧めします。

推奨される実際の設定と詳細については、ドキュメントを参照してください。背景: #3283

nav 構成のドキュメントへのリンクも、デフォルトは変更されていませんが、構成可能な検証が行われるようになりました。

nav から忘れられ、除外されていたファイルの検証をオンにすることをお勧めします。例:

validation:
  nav:
    omitted_files: warn
    absolute_links: warn

これにより、次のメッセージが、以前の唯一のオプションであった INFO レベルではなく、WARNING レベルで表示され、mkdocs --strict によってキャッチされるようになります。

INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration: ...

ドキュメントを参照してください。背景: #3283, #1755

ドキュメントを意図的に「nav にない」としてマークする

新しい構成 not_in_nav があります。これを使用すると、上記 omitted_files 警告タイプから特定のファイルパターンを除外できます。これらのファイルに対してメッセージは表示されなくなります。（結果として、この構成を * に設定することは、omitted_files を完全に無視することと同じです。）

これは、nav から忘れられたファイルに関するこれらの警告が一般的に好きだが、nav から意図的に除外した一部のページをビルドしてコピーしたい場合に便利です。

not_in_nav 構成は、gitignore のようなパターンのセットです。別のそのような構成の説明については、次のセクションを参照してください。

ドキュメントを参照してください。背景: #3224, #1888

除外されたドキュメントファイル

新しい構成 exclude_docs があります。これにより、MkDocs は docs_dir の下の特定のファイルを無視し、ビルドの一部としてビルドされた site にコピーしないように指示されます。

これまで、MkDocs は常にドットで始まるファイル名を無視し、それがすべてでした。これで、すべてが構成可能になりました。これらの無視を解除したり、より多くのファイルパターンを無視したりできます。

exclude_docs 設定は、.gitignore パターン形式に従い、複数行の YAML 文字列として指定します。例：

exclude_docs: |
  *.py               # Excludes e.g. docs/hooks/foo.py
  /requirements.txt  # Excludes docs/requirements.txt

リンクの検証（上記で説明）も exclude_docs の影響を受けます。mkdocs serve 実行中は、メッセージでその相互作用が説明されますが、mkdocs build 実行中は、除外されたファイルは存在しないものとして扱われます。

関連する追加の変更として、ディレクトリ内に README.md と index.md の両方のファイルがあり、そのうちの 1 つだけを公開したい場合は、この機能を使用して 1 つを明示的に無視し、警告を回避できます。

ドキュメントを参照してください。コンテキスト：#3224

ドラフト

バージョン 1.6 から削除

exclude_docs 設定は、mkdocs serve に対して「ドラフト」機能を適用しなくなりました。これは draft_docs に名前が変更されました。

exclude_docs 設定には別の動作があります。除外された Markdown ページはすべて mkdocs serve でのみプレビュー可能であり、上部に「DRAFT」マーカーが表示されます。その後、それらはもちろん mkdocs build または gh-deploy から除外されます。

mkdocs serve に特別な動作をさせず、代わりに完全に通常のビルドを実行させたい場合は、新しいフラグ mkdocs serve --clean を使用します。

ドキュメントを参照してください。コンテキスト：#3224

mkdocs serve はビルドエラー後に終了しなくなりました

サイトの再構築中にエラー（設定またはプラグインから）が発生した場合、mkdocs serve はスタックトレースを出力した後、以前は終了していました。現在は、作成者が問題を修正するためにファイルを編集するまでサーバーがフリーズし、その後リロードを続けます。

ただし、最初のビルドでのエラーは、以前と同様に mkdocs serve を終了させます。

コンテキスト：#3255

ページタイトルはすべてのスタイルの見出しから推測されるようになります

MkDocs には常に、ドキュメントの最初の行に基づいて（nav で指定されていない場合）ページのタイトルを推測する機能がありましたが、それは正確な文字 # で始まる <h1> 見出しである必要がありました。現在、あらゆるスタイルの Markdown 見出しが理解されます（#1886）。以前の単純な解析のため、その最初の見出しで attr_list 属性を使用することも不可能でした（#3136）。これも修正されました。

Markdown 拡張機能は現在のドキュメントからの相対パスを使用できます

これは pymdownx.snippets や markdown_include.include などの拡張機能を対象としています。含めるパスを、現在レンダリングされている Markdown ドキュメントを基準にするか、docs_dir を基準にするかを指定できるようになりました。他の拡張機能も、もちろん新しい !relative YAML タグを利用できます。

markdown_extensions:
  - pymdownx.snippets:
      base_path: !relative

ドキュメントを参照してください。コンテキスト：#2154、#3258

<script> タグは type="module" やその他の属性を指定できます

extra_javascript で、.mjs ファイル拡張子を使用するか、type: module キーを明示的に指定すると、スクリプトは type="module" 属性付きで追加されます。defer: true および async: true キーも利用できます。

extra_javascript の更新されたドキュメントを参照してください。

最初は組み込みテーマでのみサポートされ、他のテーマは後から追従する必要があります（下記参照）。

コンテキスト：#3237

テーマ開発者向けの変更（対応が必要！）

コンストラクト {% for script in extra_javascript %} を使用することは、<script> タグの属性をカスタマイズできないため、完全に廃止されました。これは機能し続けますが、MkDocs の一部の機能をブロックします。

代わりに、config.extra_javascript （これはすでにしばらくの間そうでした）を使用し、それを新しい script_tag フィルターと組み合わせる必要があります。

    {%- for script in config.extra_javascript %}
      {{ script | script_tag }}
    {%- endfor %}

ドキュメントを参照してください。

プラグイン開発者向けのアップグレード

  • 破壊的な変更：config.extra_javascript はもはや単なる文字列のリストではなく、ExtraScriptValue 項目のリストになりました。したがって、リスト値を文字列として扱うことはできなくなりました。古いバージョンとの互換性を維持したい場合は、常に項目を str(item) として参照してください。また、必要に応じて、プレーンな文字列をリストに追加することもできます。上記の <script> タグに関する情報を参照してください。コンテキスト：#3237

  • File に新しい属性 inclusion があります。その値は、exclude_docs と not_in_nav の両方の設定から計算され、それらの動作を実装します。プラグインはこの値を読み取ったり、書き込んだりできます。新しい File インスタンスは、デフォルトでは設定の内容に従いますが、プラグインはファイルごとに明示的にこの決定を行うことを選択できます。

  • File を作成する際、作成後に更新する（およびその他の依存属性を更新する）のではなく、dest_uri を直接設定できるようになりました。コンテキスト

  • 新しい設定オプション DictOfItems が追加されました。ListOfItems と同様に、同じ型のすべての設定オプションのマッピングを検証します。キーは任意ですが、常に文字列です。コンテキスト：#3242

  • 新しい関数 get_plugin_logger が追加されました。プラグインがメッセージをログに記録するための標準化された方法を選択するには、イディオムを使用してください。

    log = mkdocs.plugins.get_plugin_logger(__name__)
...
log.info("Hello, world")

    コンテキスト：#3245

  • SubConfig 設定オプションは、指定された特定の設定タイプで便利にサブクラス化できます。例：class ExtraScript(SubConfig[ExtraScriptValue]):。これがどのように役立つかを確認するには、コード内でこのクラスを検索してください。コンテキスト

  • バグ修正：SubConfig には、パス（FilesystemObject オプションから）が、意図したとおりにメイン設定ファイルからの相対パスにされていなかったというバグがありました。これは、config_file_path が適切に継承されていなかったためです。これは修正されました。コンテキスト：#3265

  • Config メンバーには、Python の予約語との衝突を回避する方法が用意されています。これは、各メンバーの名前から末尾のアンダースコアを削除することで実現されます。

    ユーザーが async: true として設定でき、プログラムで config.async_ として読み取ることができる async ブール値オプションを追加する例

    class ExampleConfig(Config):
    async_ = Type(bool, default=False)

    以前は、新しいスタイルのスキーマで予約名を持つ設定キーを作成することは不可能でした。コンテキスト

  • Theme はその属性が適切に宣言され、新しい属性 theme.locale、theme.custom_dir を取得しました。

  • いくつかの型注釈がより正確になりました。例：

    • context パラメーターは型 TemplateContext（TypedDict）を取得しました。コンテキスト
    • クラス Page、Section、Link に共通の基本クラス StructureItem が追加されました。コンテキスト
    • いくつかのメソッドが Config の受け入れをやめ、当初の意図どおりに MkDocsConfig のみを受け入れるようになりました。コンテキスト
    • config.mdx_configs は適切な型を取得しました。コンテキスト：#3229

テーマの更新

  • 組み込みテーマは主に <script defer> に依存することをやめました。これは、extra_javascript の一部の使用に影響を与える可能性があり、主に「ページが完全にロードされたか」のカスタム処理の必要性をなくします。コンテキスト：#3237

  • "mkdocs" テーマには、> ブロック引用符のスタイルが追加されました。以前は、まったく区別されていませんでした。コンテキスト：#3291

  • "readthedocs" テーマは、アップストリームに従って v1.2.0 に更新され、<kbd> とパンくずリストナビゲーションのスタイルが改善されました。コンテキスト：#3058

  • 両方の組み込みテーマで、highlight.js のバージョンが 11.8.0 に、jQuery が 3.6.0 に更新されました。

バグ修正

ナビゲーションの相対パスはルートを超えて移動できます

1.2 の回帰 - ナビゲーションの相対パスはサイトのルートを超えて移動できなくなり、ルートに切り捨てられていました。このような移動は推奨されず、警告が生成されますが、これはドキュメント化された動作でした。この動作が復元されました。

コンテキスト：#2752、#3010

MkDocs は stdin から設定を受け入れることができます

これは、その場での設定オーバーライドに使用できます。設定の継承の下部にある更新されたセクションを参照してください。

これを使用するコマンドは mkdocs build -f - です。以前のバージョンでは、これを行うとエラーが発生していました。

コンテキスト

新しいコマンドラインフラグ

  • mkdocs --no-color build は、カラー出力と行の折り返しを無効にします。このオプションは、環境変数 NO_COLOR=true を通じても利用できます。関連 issue: #3282
  • mkdocs build --no-strict は、strict 設定を false で上書きします。関連 issue: #3254
  • mkdocs build -f - (上記で直接説明されています)。
  • mkdocs serve --clean (上記で説明されています)。
  • mkdocs serve --dirty は、mkdocs serve --dirtyreload の新しい名称です。

非推奨事項

  • extra_javascript は、まれにプラグインを壊す可能性のある変更を受けました。テーマ開発者は注意が必要です。上記のエントリを参照してください。

  • Python-Markdown のピン留めが <3.4 から解除されました。このバージョンは、機能が削除されることが知られています。これらの削除の影響を受ける場合は、自分でバージョンを固定することもできます：Markdown <3.4。関連 issue: #3222, #2892

  • mkdocs.utils.warning_filter は、非推奨になったことに関する警告を表示するようになりました。MkDocs 1.2 以降は何もしません。代わりに get_plugin_logger を使用するか、mkdocs.plugins.* の下でログを記録することを検討してください。関連 issue: #3008

  • Theme の _vars 属性へのアクセスは非推奨になりました。キーに直接アクセスしてください。

  • Config の user_configs 属性へのアクセスは非推奨になりました。注意: config.user_configs[*]['theme']['custom_dir'] の代わりに、新しい属性 config.theme.custom_dir を使用してください。

その他の小さな改善点。 コミットログ を参照してください。

バージョン 1.4.3 (2023-05-02)

  • バグ修正: hooks 機能において、dataclasses のような高度な Python 機能を使用している場合、モジュールがロードに失敗しなくなるようになりました (#3193)

  • バグ修正: ページに URL が設定されていない場合、None のサイトマップエントリを作成しないようにしました。これは、ナビゲーションから一部のファイルを除外するサイトに影響します (07a297b)

  • "readthedocs" テーマ

    • アクセシビリティ: ホームロゴ (#3129) と検索入力 (#3046) に aria ラベルを追加しました
    • "readthedocs" テーマが、"mkdocs" テーマと同じように hljs_style: 設定をサポートするようになりました (#3199)

  • 翻訳

    • 組み込みテーマがインドネシア語をサポートするようになりました (#3154)
    • zh_CN の翻訳を修正しました (#3125)
    • tr_TR の翻訳が tr になりました。使用方法は影響を受けません (#3195)

コミットログ を参照してください。

バージョン 1.4.2 (2022-11-01)

  • Python 3.11 を正式にサポートします (#3020)

    ヒント

    単に Python 3.11 にアップグレードするだけで、サイトのビルド時間を 10〜15% 短縮できます。

  • 同じプラグインの複数のインスタンスをサポートします (#3027)

    plugins: 設定の下のリストにプラグインが複数回指定されている場合、それぞれ独自の構成を持つプラグインのインスタンスが 2 つ (またはそれ以上) 作成されます。

    以前は、このケースは想定されておらず、そのためバグがありました。

    これが機能するようになったとしても、プラグインがクラス変数 supports_multiple_instances = True を追加しない限り、デフォルトでは MkDocs から警告が表示されます。

  • バグ修正 (1.4.1 での回帰): プラグインがプレーン文字列を warnings に入れたときにエラーにならないようにしました (#3016)

  • バグ修正: 相対リンクは常に末尾にスラッシュ付きでレンダリングされるようにしました (#3022)

    以前は、use_directory_urls の下で、サブページからメインのインデックスページへのリンクが、他のすべてのケースでは <a href="../../"> のように見えるリンクであるにもかかわらず、例えば <a href="../.."> としてレンダリングされていました。これにより、Web ブラウザとサーバーの組み合わせによっては望ましくない動作が発生しました。この特殊なケースのバグは削除されました。

  • 組み込みの "mkdocs" テーマがノルウェー語をサポートするようになりました (#3024)

  • プラグイン関連の警告がより読みやすくなりました (#3016)

コミットログ を参照してください。

バージョン 1.4.1 (2022-10-15)

  • テーマ名前空間のプラグインのロードをサポートします (#2998)

    プラグインのエントリポイントは 'sometheme/someplugin' として名前を付けることができます。これにより、次の結果になります

    • 現在のテーマが 'sometheme' の場合、プラグイン 'sometheme/someplugin' が 'someplugin' よりも常に優先されます。
    • 現在のテーマが 'sometheme' ではない場合、このプラグインを使用する唯一の方法は、plugins: [sometheme/someplugin] を指定することです。

    plugins: ['someplugin'] の代わりに plugins: ['/someplugin'] を指定して、テーマ名前空間のプラグインを確実に回避することもできます。

  • バグ修正: mkdocs serve が非 ASCII パスとリダイレクトで正しく動作するようにしました (#3001)

  • Windows: カラー表示のログ出力を保証するために、'colorama' が MkDocs の依存関係になりました (#2987)

  • プラグイン関連の設定オプションには、より信頼性の高い検証とエラーレポートがあります (#2997)

  • setup.py の翻訳サブコマンドは完全に削除されました。ドキュメント [1] [2] で、新しい代替手段を確認してください (#2990)

  • 'mkdocs' パッケージ (wheel と source) は、setup.py の代わりに Hatch ビルドシステムと pyproject.toml によって生成されるようになりました (#2988)

その他の小さな改善点。 コミットログ を参照してください。

バージョン 1.4.0 (2022-09-27)

機能のアップグレード

フック (#2978)

新しい hooks: 設定により、実際のプラグインをセットアップしてインストールする必要なしに、ローカルの Python ファイルからプラグインのようなイベントハンドラーを追加できます。

ドキュメント を参照してください。

edit_uri の柔軟性 (#2927)

新しい edit_uri_template: 設定があります。
edit_uri と同様に動作しますが、編集 URL を構築する方法をより一般的にカバーします。
ドキュメント を参照してください。

さらに、repo_url が省略されている場合でも、edit_uri 機能が完全に動作するようになりました (#2928)

プラグイン開発者向けのアップグレード

注意

このリリースでは、プラグインとその設定の実装に大きな変更があります。ただし、すべての合理的に一般的なユースケースで破壊的な変更をゼロにすることが目的です。または、少なくともコード修正が必要な場合は、常に古い MkDocs バージョンとの互換性を維持する方法があるはずです。このリリースで何かが壊れた場合は報告してください。

プラグインイベントハンドラーのイベント順序をカスタマイズします (#2973)

プラグインは、イベントハンドラーの優先度値を設定することを選択できるようになりました。これにより、古い動作 (各イベントタイプに対して、ハンドラーが plugins 設定 にプラグインが表示される順序で呼び出される) が上書きされる可能性があります。

これが設定されている場合、優先度の高いイベントが最初に呼び出されます。優先度が選択されていないイベントは、デフォルトで 0 になります。優先度が同じイベントは、設定に表示される順序で並べられます。

推奨される優先度値: 100 "最初", 50 "早期", 0 "デフォルト", -50 "後期", -100 "最後"。
異なるプラグインが互いにより正確な関係を発見するにつれて、値はさらに調整される必要があります。

ドキュメント を参照してください。

mkdocs serve でビルド間で持続する新しいイベント (#2972)

新しいイベントは on_startup と on_shutdown です。これらは、mkdocs の呼び出しの最初と最後に実行されます。
on_startup は、mkdocs がどのように呼び出されたか (例: serve --dirtyreload) に関する情報も受け取ります。

ドキュメント を参照してください。

バックスラッシュを扱わないように File.src_path を置き換えます (#2930)

プロパティ src_path は、Windows でバックスラッシュを使用しますが、仮想パスであるため、意味がありません。
破壊的な変更を加えないために、この プロパティの使用方法に変更はありませんが、今後は次のようにする必要があります

  • File.src_path の代わりに File.src_uri を使用してください
  • そして、File.dest_path の代わりに File.dest_uri を使用してください。

これらは一貫してフォワードスラッシュを使用し、MkDocs 自体が使用する決定的なソースになりました。

ソースコード を参照してください。

関連するヒントとして: これらのパスを処理するために os.path.* または pathlib.Path() を使用するのをやめ、代わりに posixpath.* または pathlib.PurePosixPath() を使用する必要があります

MkDocs は型アノテーションが付けられており、mypy での使用に対応しています (#2941, #2970)

イベントハンドラーメソッドの型アノテーション (#2931)

MkDocs のプラグインイベントメソッドには、型アノテーションが付くようになりました。すでにイベントにアノテーションを追加しているかもしれませんが、それらは元のものと一致するように検証されるようになりました。

ソースコード と ドキュメント を参照してください。

大きな更新点の1つは、メソッドのパラメータにconfig: base.Configではなく、より具体的にconfig: defaults.MkDocsConfigとアノテーションする必要があるということです。これにより、それがMkDocs自体のメイン設定であることが明確になるだけでなく、オブジェクトの属性を介してタイプセーフなアクセスも可能になります（次のセクションを参照）。

ソースコードとドキュメントを参照してください。

ConfigOptionのスキーマをクラスベースにリワーク（#2962）

プラグインを開発する際、それが受け入れる設定は、プラグインクラスのconfig_scheme変数で指定していました。
この方法は現在、ソフトデプリケーションとなっており、代わりにbase.Configのサブクラスで設定を指定する必要があります。

古い例

from mkdocs import plugins
from mkdocs.config import base, config_options

class MyPlugin(plugins.BasePlugin):
    config_scheme = (
        ('foo', config_options.Type(int)),
        ('bar', config_options.Type(str, default='')),
    )

    def on_page_markdown(self, markdown: str, *, config: base.Config, **kwargs):
        if self.config['foo'] < 5:
            if config['site_url'].startswith('http:'):
                return markdown + self.config['baz']

このコードスニペットには実際には多くの間違いがありますが、すべての型チェックに合格し、一部のケースではサイレントに実行され、成功さえします。

そこで、新しい同等の例として、新しいスタイルのスキーマと属性ベースのアクセスに変更しました。
(「mypy」からのエラーがインラインで追加されています)

from mkdocs import plugins
from mkdocs.config import base, config_options as c

class MyPluginConfig(base.Config):
    foo = c.Optional(c.Type(int))
    bar = c.Type(str, default='')

class MyPlugin(plugins.BasePlugin[MyPluginConfig]):
    def on_page_markdown(self, markdown: str, *, config: defaults.MkDocsConfig, **kwargs):
        if self.config.foo < 5:  # Error, `foo` might be `None`, need to check first.
            if config.site_url.startswith('http:'):  # Error, MkDocs' `site_url` also might be `None`.
                return markdown + self.config.baz  # Error, no such attribute `baz`!

これにより、コードを実行する前に静的型チェッカーからのエラーに気づき、それに応じて修正できます。

class MyPlugin(plugins.BasePlugin[MyPluginConfig]):
    def on_page_markdown(self, markdown: str, *, config: defaults.MkDocsConfig, **kwargs):
        if self.config.foo is not None and self.config.foo < 5:  # OK, `int < int` is valid.
            if (config.site_url or '').startswith('http:'):  # OK, `str.startswith(str)` is valid.
                return markdown + self.config.bar  # OK, `str + str` is valid.

ドキュメントを参照してください。

また、config属性fooをOptionalとして明示的にマークする必要があったことに注意してください。
新しいスタイルの設定では、すべての属性がデフォルトで必須としてマークされており、required=Falseまたはrequired=Trueの指定は許可されていません！

新規：config_options.Optional (#2962)

何かをOptionalでラップすることは、「デフォルトをNoneにしたい」という概念に似ています。そして、default=Noneと記述しても実際には機能しないため、このように表現する必要があります。

破壊的な変更：メソッドBaseConfigOption.is_required()が削除されました。代わりに.requiredを使用してください。（#2938）
また、requiredプロパティもほとんど使用されなくなりました。
クラスベースの設定では、オプションが「必須」であるかどうかについて新しい定義があります。

  • デフォルトがなく、
  • config_options.Optionalでラップされていません。
新規：config_options.ListOfItems (#2938)

各項目が同じ制約に従う必要がある項目のリストを定義します。検証済みのType(list)のようなものです。

整数のリストを表現する方法の例（from mkdocs.config import config_options as cを使用）

説明 コードエントリ
指定する必要がある foo = c.ListOfItems(c.Type(int))
オプション、デフォルトは[] foo = c.ListOfItems(c.Type(int), default=[])
オプション、デフォルトはNone foo = c.Optional(c.ListOfItems(c.Type(int)))

ドキュメントの例を参照してください。

更新：config_options.SubConfig (#2807)

SubConfigは、設定オプションのすべての検証をサイレントに無視していました。現在は、validate=Trueを渡すか、これがデフォルトになった新しいクラスベースの設定を使用する必要があります。

これにより、すべてのキーが事前に定義され、値の型が厳密に検証されたネストされたサブディクショナリを検証するために使用できます。

ドキュメントの例を参照してください。

設定オプションへのその他の変更点

URLのデフォルトは、''ではなくNoneになりました。これは、if config.some_url:のように、同じ方法で真偽値をチェックできます。（#2962）

FilesystemObjectはもはや抽象的ではなく、直接使用でき、オプションの存在チェック付きの「ファイルまたはディレクトリ」を表します。（#2938）

バグ修正

  • 異なるインスタンス間で値がリークしないようにSubConfig、ConfigItems、MarkdownExtensionsを修正（#2916、#2290）
  • SubConfigは、スタックトレースなしで正しい種類の検証エラーを発生させます。（#2938）
  • config_options.Deprecated(moved_to)でドット区切りのリダイレクトを修正（#2963）

ConfigOption.defaultを処理するためのロジックを調整（#2938）

非推奨の設定オプションクラス：ConfigItems (#2983)、OptionallyRequired (#2962)、RepoURL (#2927)

テーマの更新

  • 「MkDocs」テーマでのadmonitionのスタイル（#2981）

    • コントラストを上げるために色を更新
    • admonitionスタイルを<details>タグにも適用して、それを提供するMarkdown拡張機能をサポートします（pymdownx.details、callouts）

  • 組み込みテーマがこれらの言語もサポートするようになりました

    • ロシア語（#2976）
    • トルコ語（トルコ）（#2946）
    • ウクライナ語（#2980）

将来の互換性

  • extra_css:およびextra_javascript:は、バックスラッシュ\が渡されると警告を発します。（#2930、#2984）

  • DeprecationWarningをINFOメッセージとして表示します。（#2907）

    使用しているプラグインまたは拡張機能が、他のライブラリの非推奨の機能に依存している場合、近い将来に壊れる危険性があります。プラグイン開発者は、これらにタイムリーに対処する必要があります。

  • Python 3.10以降では、importlib_metadataへの依存関係を回避します（#2959）

  • Python 3.6のサポートを終了（#2948）

パブリックAPIへの互換性のない変更

  • mkdocs.utils:
    • create_media_urlsおよびnormalize_urlは、バックスラッシュ\が渡されると警告を発します。（#2930）
    • is_markdown_fileは、MkDocsビルドがすでに動作していた方法である、大文字と小文字を区別しないバリアント（.MDなど）の受け入れを停止します。（#2912）
    • ハードデプリケーション：modified_time、reduce_list、get_html_path、get_url_path、is_html_file、is_template_file。（#2912）

その他

  • プラグインがLiveReloadServerのwatchにパスを追加する場合、それらをunwatchできるようになりました。（#2777）

  • バグ修正（1.2での回帰）：mkdocs serveでIPv6アドレスでのリッスンをサポートします。（#2951）

その他の小さな改善点については、コミットログを参照してください。

バージョン1.3.1 (2022-07-19)

  • Python-Markdownのバージョンを<3.4に固定し、多くの外部拡張機能を破壊する最新リリースを除外します（#2893）

  • Markdown拡張機能のロードに失敗した場合、その名前とトレースバックを出力します（#2894）

  • 「readthedocs」テーマのバグ修正（1.3.0での回帰）：パンくずリストに欠落しているスペースを追加します（#2810）

  • バグ修正：「readme.md」（小文字）ファイルが存在する場合、他の方法では認識されないため、文句を言わないでください（#2852）

  • 組み込みテーマがこれらの言語もサポートするようになりました

    • イタリア語（#2860）

その他の小さな改善点については、コミットログを参照してください。

バージョン1.3.0 (2022-03-26)

機能のアップグレード

  • ReadTheDocsテーマがアップストリームに従いv0.4.1からv1.0.0に更新されました（#2585）

    最も注目すべき変更点

    • 新しいオプションlogo：タイトルにsite_nameを表示する代わりに、代わりに表示する画像のパスを指定できます。
    • Google Analyticsの新しいオプションanonymize_ip。
    • 依存関係がアップグレードされました：jQueryが3.6.0にアップグレードされ、Modernizr.jsが削除され、その他がアップグレードされました。

    テーマの設定オプションのドキュメントを参照してください

  • 組み込みテーマがこれらの言語もサポートするようになりました

    • ドイツ語（#2633）
    • ペルシア語（ファルシ語）（#2787）

  • mkdocs serve 実行時に監視するカスタムディレクトリをサポート (#2642)

    MkDocs はデフォルトで *docs* ディレクトリと設定ファイルを監視します。YAML の watch キーまたはコマンドラインフラグ --watch を使用して、変更を監視するディレクトリを追加できるようになりました。

    通常、MkDocs は他のディレクトリにアクセスすることはありません（そのため、この機能は必要ないはずです）が、一部のプラグインや拡張機能はアクセスする場合があります。

    ドキュメントを参照してください。

  • gh_deploy 用の新しい --no-history オプション (#2594)

    デプロイ時にコミットの履歴を破棄し、代わりに単一のルートコミットに置き換えることができます。

バグ修正

  • 組み込みテーマで検索機能を使用する際の XSS 脆弱性が修正されました (#2791)

  • edit_uri オプションを設定しても、repo_url に不要な末尾のスラッシュが追加されなくなりました (#2733)

その他

  • 破壊的変更：長い間非推奨となっていた pages 設定オプションを使用するとエラーが発生するようになりました (#2652)

    エラーを修正するには、pages を nav に変更するだけです。

  • パフォーマンスの最適化：MkDocs の起動時に、他のコマンドのコードと依存関係はインポートされなくなります (#2714)

    この最も目に見える効果は、mkdocs serve の依存関係が mkdocs build の使用時にはインポートされないことです。

  • nav の再帰的な検証 (#2680)

    ネストされた nav 構造の検証が、エラーを早期かつ確実に報告するように再構成されました。いくつかのエッジケースが無効として宣言されました。

その他の小さな改善点については、コミットログを参照してください。

バージョン 1.2.4 (2022-03-26)

  • Jinja2 3.1.0 との互換性 (#2800)

    Jinja2 の破壊的変更により、MkDocs は AttributeError: module 'jinja2' has no attribute 'contextfilter' というメッセージでクラッシュしていました。

バージョン 1.2.3 (2021-10-12)

  • 組み込みテーマがこれらの言語もサポートするようになりました

    • 簡体字中国語 (#2497)
    • 日本語 (#2525)
    • ブラジルポルトガル語 (#2535)
    • スペイン語 (#2545、以前は#2396)

  • サードパーティプラグインは、同じ名前の組み込みプラグインよりも優先されます (#2591)

  • バグ修正：一部の言語の翻訳をロードする機能を修正：コアサポート (#2565) およびフォールバック付きの検索プラグインサポート (#2602)

  • バグ修正（1.2 のリグレッション）：開発サーバーでのディレクトリトラバーサルを防止 (#2604)

  • バグ修正（1.2 のリグレッション）：厳密モードで Web サーバーの警告がビルド失敗として扱われるのを防止 (#2607)

  • バグ修正：Windows でターミナルにカラフルなメッセージを正しく表示 (#2606)

  • バグ修正：Python バージョン 3.10 が --version で誤って表示されていた (#2618)

その他の小さな改善点については、コミットログを参照してください。

バージョン 1.2.2 (2021-07-18)

  • バグ修正（1.2 のリグレッション）：Unicode 文字を含むファイル/パスの提供を修正 (#2464)

  • バグ修正（1.2 のリグレッション）：ライブリロードファイル監視をポーリングオブザーバーを使用するように戻す (#2477)

    これは、非ネイティブ Docker やネットワークマウントなどの仮想ファイルシステムにまたがる使用を合理的にサポートするために必要でした。

    これは、以前から常に使用されていたものと非常によく似たポーリングアプローチに戻ることを意味し、レイテンシーと CPU 使用率に関する同じ欠点のほとんどが残ります。

  • 1.2 からリバート：site_url 設定の要件と use_directory_urls の制限を削除 (#2490)

  • バグ修正（1.2 のリグレッション）：mkdocs serve サーバーでディレクトリインデックスを提供するときに URL に末尾のスラッシュを要求しない (#2507)

    404 エラーを表示する代わりに、ディレクトリかどうかを検出し、以前のように末尾にスラッシュが追加されたパスにリダイレクトします。

  • バグ修正：現在のディレクトリにある設定ファイルで gh_deploy を修正 (#2481)

  • バグ修正：「readthedocs」テーマの反転したパンくずリストを修正 (#2179)

  • 「--config」が渡されないときにファイル名として「mkdocs.yaml」を許可 (#2478)

  • URL で ";" を特殊文字として扱わない：urlparse -> urlsplit (#2502)

  • ページ数の多いサイトのビルドパフォーマンスを向上（一部は既に 1.2 で完了済み）(#2407)

バージョン 1.2.1 (2021-06-09)

  • バグ修正（1.2 のリグレッション）：'gh-deploy' が常にプッシュすることを確認。

バージョン 1.2 (2021-06-04)

バージョン 1.2 の主な追加点

テーマローカライゼーションのサポートが追加されました (#2299)

mkdocs および readthedocs テーマで、theme.locale パラメータを使用した言語ローカライゼーションがサポートされるようになりました。デフォルトは en (英語) です。このリリースでサポートされているその他の言語は fr (フランス語) と es (スペイン語) のみです。提供されている翻訳の使用方法の詳細については、ユーザーガイドを参照してください。翻訳はデフォルトでは行われないことに注意してください。ユーザーはまず、次のコマンドで必要な依存関係をインストールする必要があります

pip install 'mkdocs[i18n]'

翻訳の貢献は大歓迎であり、翻訳ガイドに詳しく記載されています。

サードパーティテーマの開発者は、テーマ開発ガイドの関連セクションを確認することをお勧めします。

組み込みテーマのテンプレートを更新するコントリビューターは、コントリビューティングガイドを確認する必要があります。

search プラグインの lang 設定が、theme.locale で指定された言語をデフォルトとするようになりました。

設定ファイルでの環境変数のサポートが追加されました (#1954)

環境変数を !ENV タグを使用して設定ファイルで指定できるようになりました。変数の値は YAML パーサーによって解析され、適切な型に変換されます。

somekey: !ENV VAR_NAME
otherkey: !ENV [VAR_NAME, FALLBACK_VAR, 'default value']

詳細については、設定ドキュメントの環境変数を参照してください。

設定の継承のサポートが追加されました (#2218)

設定ファイルが親設定ファイルから継承できるようになりました。プライマリファイルで、親ファイルの相対パスを INHERIT キーに設定します。

INHERIT: path/to/base.yml

2 つのファイルはディープマージされます。詳細については、設定の継承を参照してください。

gh-deploy コマンドの更新 (#2170)

ベンダリング（および変更された）ghp_import のコピーが、アップストリームライブラリへの依存関係に置き換えられました。バージョン 1.0.0 以降、ghp-import には、直接呼び出すことを可能にする Python API が含まれています。

MkDocs は、次のものを含む、最近のバグ修正と新機能を利用できるようになりました。

  • GitHub Pages にデプロイする際に、.nojekyll ファイルが自動的に含まれるようになりました。
  • --shell フラグが利用可能になり、Windows でより適切に動作すると報告されています。
  • Git の作成者とコミッターの環境変数が尊重される必要があります (#1383)。

mkdocs serve の自動リロードと HTTP サーバーの再構成 (#2385)

mkdocs serve で、標準ライブラリの http.server と watchdog に基づく、新しい基盤となるサーバー + ファイル監視実装が使用されるようになりました。以前使用されていた livereload ライブラリ（および tornado とともに依存関係から削除されました）と同様の機能を提供します。

これにより、リロードの応答性とタイミングの一貫性が向上します。複数の急速なファイル変更により、サイトが繰り返しリビルドされることがなくなりました（issue #2061）。

サーバーのほぼすべての側面がわずかに異なりますが、実際に見える変更はわずかです。ログ出力は古いものと似ているだけです。動作の低下は予想されず、発見された場合は報告する必要があります。

site_url のサブパスに従ってローカルサイトのルートをオフセット (#2424)

mkdocs serve を使用し、site_url をたとえば http://example.org/sub/path/ として指定した場合、ローカルで提供されるサイトのルートは http://127.0.0.1:8000/sub/path/ となり、すべてのドキュメントパスがそれに応じてオフセットされるようになりました。

build_error イベントが追加されました (#2103)

プラグイン開発者は、サイトのビルド中に例外が発生した場合にコードを実行するために、on_build_errorフックを使用できるようになりました。

詳細は、プラグインのドキュメントのon_build_errorを参照してください。

3つの新しい例外: BuildError、PluginError、および Abort (#2103)

MkDocsには、mkdocs.exceptionsに定義された3つの新しい例外（BuildError、PluginError、およびAbort）が追加されました。

  • PluginErrorは、ビルドを停止し、*トレースバックなしで*エラーメッセージをログに記録するために、プラグインから発生させることができます。
  • BuildErrorは、サードパーティのプラグイン開発者は使用すべきではなく、内部使用のみに予約されています。
  • Abortは、ビルドを中断し、トレースバックなしでエラーを表示するために内部的に使用されます。

詳細は、プラグインのドキュメントのエラーの処理を参照してください。

検索インデックス戦略の構成

ユーザーは、検索用にサイトをインデックスするときに使用する戦略を指定できるようになりました。ユーザーは次のオプションから選択できます。

  • full: ページタイトル、セクション見出し、およびページ全文を検索インデックスに追加します。
  • sections: ページタイトルとセクション見出しのみを検索インデックスに追加します。
  • titles: ページタイトルのみを検索インデックスに追加します。

詳細は、構成ドキュメントの検索インデックスを参照してください。

1.2における後方互換性のない変更

  • site_url構成オプションが必須になりました。設定されていない場合は、警告が表示されます。将来のリリースでは、エラーが発生します（#2189）。

    site_urlが空の文字列に設定されている場合、use_directory_urls構成オプションは強制的にfalseに設定されます。その場合、use_directory_urlsが明示的にfalseに設定されていない場合は、警告が表示されます（#2189）。

    注意

    これはリリース1.2.2で元に戻されました。

  • google_analytics構成オプションは、Googleが新しいGoogle Analytics 4プロパティに移行しているため、非推奨になりました。テーマの構成の一部として構成できる代替手段については、テーマのドキュメントを参照してください。たとえば、mkdocsおよびreadthedocsテーマにはそれぞれ、新しいGoogle Analytics 4プロパティを使用する新しいtheme.analytics.gtag構成オプションが追加されています。Googleのドキュメントで、Google Analytics 4プロパティにアップグレードする方法を確認してください。次に、theme.analytics.gtagを「G-」IDに設定し、「UA-」IDを含むgoogle_analytics構成オプションを削除します。古い「UA-」IDと新しい「G-」IDがGoogleアカウントで適切にリンクされており、「G-」IDを使用している限り、データはGoogle Analyticsによって古い形式と新しい形式の両方で利用可能になります。詳しくは、#2252を参照してください。

  • --livereloadサーバーを使用する場合、テーマのファイルはデフォルトで監視対象ファイルの一覧から除外されるようになりました。この新しいデフォルトの動作は、ほとんどのユーザーが必要とするものであり、サイトコンテンツを編集する際のパフォーマンスが向上します。テーマ開発者は、--watch-themeオプションを使用して、以前の動作を有効にできます（#2092）。

  • mkdocsテーマでは、ページを印刷するときにサイドバーが削除されるようになりました。これにより、テーブルなどのコンテンツのより適切なレンダリングのために水平方向のスペースが解放されます（#2193）。

  • mkdocs.config.DEFAULT_SCHEMAグローバル変数は、構成の各インスタンスが一意であることを保証する関数mkdocs.config.defaults.get_schema()に置き換えられました（#2289）。

  • mkdocs.utils.warning_filterは非推奨になり、現在は何も行いません。プラグインは、将来のリリースで削除される可能性があるため、この参照を削除する必要があります。警告が確実にカウントされるようにするには、単にmkdocsログ（例：mkdocs.plugins.pluginname）にログを記録してください。

  • on_serveイベント（serverオブジェクトとbuilder関数を受け取る）は、サーバーの書き換えの影響を受けます。serverは、livereload.server.Serverではなく、mkdocs.livereload.LiveReloadServerになりました。プラグインがこれらで実行できる一般的なアクションは、server.watch(some_dir, builder)を呼び出すことです。これは基本的に、監視対象のディレクトリにそのディレクトリを追加し、ファイルの変更時にサイトを再構築させます。これはまだ機能しますが、watchに他の関数を渡すと、非推奨となり、警告が表示されます。この2番目のパラメーターはすでにオプションであり、互換性のためにこの正確なbuilder関数のみを受け入れます。

  • plugins.search.prebuild_index構成オプションのpythonメソッドは、バージョン1.2の時点で非推奨保留中です。バージョン1.3では使用すると警告が表示され、バージョン1.4ではエラーが発生することが予想されます。ユーザーは、検索用の事前構築済みインデックスを生成するために別の方法を使用することをお勧めします。

  • lunrおよびlunr[languages]依存関係は、デフォルトではインストールされなくなりました。これらの依存関係は、検索インデックスを事前構築し、現在は非推奨保留中のpythonオプションを使用するまれなユーザーにのみ必要です。この機能を使用する場合は、lunrおよびlunr[languages]を手動でインストールする必要があります。依存関係が必要だがインストールされていない場合は、警告が表示されます。

バージョン1.2のその他の変更と追加

  • バグ修正：セクションをフィルタリングするときに、_get_by_typeでナビゲーションの子項目を適切に処理します（#2203）。
  • Python 3.9の公式サポートが追加され、Python 3.5のサポートは終了しました。
  • バグ修正：ReadTheDocsテーマでナビゲーション項目が部分的に切り取られる問題を修正しました（#2297）。
  • Structure Filesオブジェクトに、プラグイン開発者がFilesツリーを操作するのに役立つremoveメソッドが追加されました。対応するsrc_pathsは、この動的な動作に対応するためにプロパティになりました。詳しくは、#2305を参照してください。
  • highlight.jsを10.5.0に更新しました。詳しくは、#2313を参照してください。
  • バグ修正：検索プラグインが日本語で動作するようになりました。詳しくは、#2178を参照してください。
  • ドキュメントがリファクタリングされました（#1629）。
  • readthedocsテーマでのテーブルのスタイルを復元しました（#2028）。
  • site_urlがスラッシュで終わるようにします（#1785）。
  • pagesテンプレートコンテキスト変数のドキュメントを修正しました（#1736）。
  • lunr依存関係が0.5.9に、lunr.jsが対応する2.3.9バージョンに更新されました（#2306）。
  • エラー、警告、およびデバッグメッセージを識別するために、ログメッセージで色が使用されるようになりました。
  • バグ修正：use_directory_urlsがFalseの場合にホームページを識別します（#2362）。

バージョン1.1.2（2020-05-14）

  • バグ修正：IPアドレスを正規化し、サポートされていないアドレスエラーを警告に変更しました（#2108）。

バージョン1.1.1（2020-05-12）

  • バグ修正：SOURCE_DATE_EPOCH環境変数をサポートすることで、圧縮されたサイトマップを決定論的にできるようにしました（#2100）。
  • バグ修正：use_directory_urlsがfalseの場合でも、README.mdをindex.htmlとして使用します（#2081）。
  • バグ修正：バックスラッシュで始まるリンクを無視します（#1680）。
  • バグ修正：プラグインがserver.watchに渡せるように、on_serveイベントにbuilderを渡します（#1952）。
  • バグ修正：nltkの非互換性を回避するために、lunr[languages]==0.5.8を使用します（#2062）。
  • バグ修正：wheelがPython 3のみであることを確認します（#2021）。
  • バグ修正：dev_addrの検証をクリーンアップし、0.0.0.0を許可しないようにします（#2022）。
  • 検索プラグインのmin_search_lengthパラメーターのサポートを追加しました（#2014）。
  • バグ修正：readthedocsテーマのcodeの色を修正しました（#2027）。

バージョン1.1（2020-02-22）

バージョン1.1の主な追加機能

prebuild_indexエンジンとしてのLunr.pyのサポート

Mkdocsは、Lunr.py（Lunr.jsの純粋なPython実装）を使用してインデックスを事前構築できるようになり、必要に応じてNodeJS環境のインストールを回避できます。詳細については、prebuild_indexドキュメントを参照してください。

readthedocsテーマがアップストリームで更新されました（#588および#1374）

readthedocsテーマは、アップストリームのSphinxテーマ（バージョン0.4.1）にさらに近づきました。アップストリーム構成オプションをミラーリングする多くの新しいテーマ構成設定が追加されました。詳細については、テーマドキュメントを参照してください。

mkdocsテーマをBootswatch 4.1.3に更新しました（#1563）

mkdocsテーマが、Bootswatch 4.1のすべての機能をサポートするようになりました。さらに、このアップデートで2つのファイル名が変更されました。mkdocsテーマを継承するテーマを使用している場合、テーマ開発者は、これらのファイル名を次のように更新する必要があるかもしれません。

css/bootstrap-custom.min.css => css/bootstrap.min.css
js/bootstrap-3.0.3.min.js => js/bootstrap.min.js

コマンドラインでの設定サポートの改善（#1401）

build、serve、およびgh-deployサブコマンドで、ディレクトリURLを作成するかどうかを制御するフラグがサポートされるようになりました。--use-directory-urls / --no-directory-urls。さらに、gh-deployサブコマンドは、buildおよびserveが持つすべての設定オプションをサポートするようになり、--strict、--theme、--theme-dir、および--site-dirが追加されました。

lunr-languagesサポートの更新（#1729）

lunr-languagesプラグインが1.4.0に更新され、アラビア語（ar）とベトナム語（vi）のサポートが追加されました。さらに、オランダ語と日本語の言語コードが標準値であるnlとjaにそれぞれ変更されました。古い言語コード（duとjp）はエイリアスとして残りますが、将来のMkDocsのバージョンで削除される可能性があります。

バージョン1.1におけるその他の変更点と追加点

  • バグ修正：テーマ内のネストされたドットファイルが確実に無視されるようにし、その動作を文書化（#1981）。
  • 最小依存関係をMarkdown 3.2.1に更新。
  • セキュリティ上の懸念に対処するため、最小依存関係をJinja 2.10.1に更新（#1780）。
  • lunr.js 2.3.8に更新（#1989）。
  • Python 3.8のサポートを追加。
  • Python 3.4のサポートを削除。
  • Python 2.7のサポートを削除。MkDocsは現在PY3のみ（#1926）。
  • バグ修正：Python 3.8+のWindowsで適切なasyncioイベントループを選択（#1885）。
  • バグ修正：ネストされたインデックスページがホームページとして識別されないように修正（#1919）。
  • バグ修正：デプロイバージョンを正しく識別（#1879）。
  • バグ修正：custom_dirのValidationErrorメッセージを正しくビルド（#1849）。
  • バグ修正：テーマからMarkdownファイルとREADMEを除外（#1766）。
  • バグ修正：エンコードされたURLを考慮（#1670）。
  • バグ修正：テーマファイルがdocs_dirファイルをオーバーライドしないように修正（#1671）。
  • バグ修正：URLフラグメントを正規化しないように修正（#1655）。
  • バグ修正：sitemap.xmlで外部URLをスキップ（#1742）。
  • バグ修正：Windowsでテーマファイルがdocs_dirファイルをオーバーライドしないように修正（#1876）
  • readthedocsテーマにcanonicalタグを追加（#1669）。
  • gitが利用できない場合の改善されたエラーメッセージ。
  • mkdocsテーマのnav_styleテーマオプションのサポートを追加（#1930）。
  • バグ修正：mkdocsテーマで、長い/ネストされたドロップダウンがより一貫して動作するように修正（#1234）。
  • バグ修正：mkdocsテーマの複数行のナビゲーションヘッダーがドキュメントの内容を不明瞭にしないように修正（#716）。
  • mkdocsテーマのnavigation_depthテーマオプションのサポートを追加（#1970）。
  • page.tocアイテムのlevel属性が、<hN>タグのレベルと一致するように1から始まるインデックスになるように変更（#1970）。

バージョン1.0.4（2018-09-07）

  • バグ修正：Markdownで絶対リンクを無視（#1621）。

バージョン1.0.3（2018-08-29）

  • バグ修正：ナビゲーションで相対パスを使用した場合に警告（#1604）。
  • バグ修正：空のtheme_config.ymlファイルを正しく処理（#1602）。

バージョン1.0.2（2018-08-22）

  • バグ修正：エラーテンプレートに絶対base_urlを提供（#1598）。

バージョン1.0.1（2018-08-13）

  • バグ修正：検索ボックスで[Enter]キーを押したときにページがリロードされないように修正（#1589）。
  • バグ修正：すべてのアセットの準備が整うまでsearchを呼び出さないように修正（#1584）。
  • バグ修正：index.mdが存在する場合、README.mdを除外（#1580）。
  • バグ修正：ホームページに関するreadthedocsテーマのナビゲーションバグを修正（#1576）。

バージョン1.0（2018-08-03）

バージョン1.0の主な追加点

ページ、ファイル、およびナビゲーションの内部リファクタリング

ページ、ファイル、およびナビゲーションの内部処理が完全にリファクタリングされました。リファクタリングに含まれる変更点は以下にまとめられています。

  • 非表示ページのサポート。ナビゲーション構成に含まれているかどうかに関係なく、すべてのMarkdownページがビルドに含まれるようになりました（#699）。
  • ナビゲーションに外部サイトへのリンクを含めることができるようになりました（#989 #1373 & #1406）。
  • ページデータ（タイトルを含む）は、ページがレンダリングされる前に、すべてのページに対して正しく決定されるようになりました（#1347）。
  • 自動的に生成されるナビゲーションは、インデックスページを先頭にソートするようになりました。つまり、インデックスページはディレクトリの最初の子供としてリストされ、他のすべてのドキュメントはインデックスページの後にファイル名でアルファベット順にソートされます（#73 & #1042）。
  • README.mdファイルがディレクトリ内のインデックスファイルとして扱われるようになり、index.htmlにレンダリングされます（#608）。
  • すべてのファイルのURLは一度計算され、ファイルコレクションに保存されます。これにより、すべての内部リンクが構成に関係なく常に正しく計算されることが保証されます。これにより、他のMarkdownページへのリンクだけでなく、すべての内部リンクを検証することもできます。（#842 & #872）。
  • 新しいurlテンプレートフィルターにより、すべてのURLが現在のページからの相対URLになるようにスマートに保証します（#1526）。
  • on_filesプラグインイベントが追加されました。これを使用して、docs_dirにないファイルを含めたり、ファイルを除外したり、ページURLを再定義したり（つまり、拡張子のないURLを実装したり）、その他さまざまな方法でファイルを操作したりできます。
後方互換性のない変更

内部リファクタリングの一部として、いくつかの後方互換性のない変更が導入されました。以下にまとめられています。

use_directory_urlsがFalseの場合にURLが変更されました

以前は、すべてのMarkdownページは、use_directory_urls設定の構成方法に関係なく、ファイル名が変更されてインデックスページになっていました。ただし、パスのマングリングが必要なのは、use_directory_urlsがTrue（デフォルト）に設定されている場合のみです。use_directory_urlsがFalseに設定されている場合、パスのマングリングは発生しなくなります。これにより、まだインデックスファイルではなかったすべてのページのURLが異なります。この動作はデフォルト以外の構成にのみ影響し、オプションをFalseに設定する最も一般的なユースケースはローカルファイルシステム（file://）の参照であるため、ほとんどのユーザーには影響しない可能性があります。ただし、WebサーバーでホストされているMkDocsサイトでuse_directory_urlsをFalseに設定している場合、ほとんどのURLが壊れてしまいます。以下に示すように、新しいURLははるかに合理的です。

Markdownファイル 古いURL 新しいURL
index.md index.html index.html
foo.md foo/index.html foo.html
foo/bar.md foo/bar/index.html foo/bar.html

use_directory_urlsがTrue（デフォルト）に設定されている場合、URLまたはファイルパスに変更はありませんが、MkDocsは内部的に生成されたすべてのURLに末尾のスラッシュを一貫して含めるようになります。

pages構成設定の名前がnavに変更されました

pages構成設定は非推奨であり、構成ファイルに設定されている場合は警告を発行します。設定の名前がnavに変更されました。構成を更新するには、設定の名前をnavに変更するだけです。つまり、構成が次のようになっていた場合

pages:
  - Home: index.md
  - User Guide: user-guide.md

次のように構成を編集するだけです。

nav:
  - Home: index.md
  - User Guide: user-guide.md

現在のリリースでは、pages設定が含まれているが、nav設定が含まれていない構成では、pages構成がnavにコピーされ、警告が発行されます。ただし、将来のリリースでは、そうならない可能性があります。pagesとnavの両方が定義されている場合、pages設定は無視されます。

テンプレート変数とbase_url

以前のバージョンのMkDocsでは、一部のURLでbase_urlテンプレート変数がURLの先頭に追加されることを期待しており、他のURLではそうではありませんでした。テンプレートコンテキストに追加される前にURLが変更されないという点で、その矛盾は解消されました。

例えば、テーマテンプレートでは、以前はsite_nameへのリンクを以下のように記述していたかもしれません。

<a href="{{ nav.homepage.url }}">{{ config.site_name }}</a>

そして、MkDocsは現在のページからの相対URLであるホームページのURLを魔法のように返していました。その「魔法」は削除され、urlテンプレートフィルターを使用する必要があります。

<a href="{{ nav.homepage.url|url }}">{{ config.site_name }}</a>

この変更は、すべてのナビゲーションアイテムとページ、およびpage.next_pageとpage.previous_page属性に適用されます。当面の間、extra_javascriptとextra_css変数は以前と同様に（urlテンプレートフィルターなしで）動作しますが、これらは非推奨となり、対応する構成値（それぞれconfig.extra_javascriptとconfig.extra_css）を代わりにフィルターと組み合わせて使用する必要があります。

{% for path in config.extra_css %}
    <link href="{{ path|url }}" rel="stylesheet">
{% endfor %}

ナビゲーションに外部サイトへのリンクを含めることができるようになりました。当然ながら、これらのアイテムにはbase_urlを付加するべきではありません。ただし、urlテンプレートフィルターはURLが絶対パスであることを認識する賢さを持っているため、それを変更しません。したがって、すべてのナビゲーションアイテムをフィルターに渡すことができ、変更が必要なものだけが変更されます。

{% for nav_item in nav %}
    <a href="{{ nav_item.url|url }}">{{ nav_item.title }}</a>
{% endfor %}

パスベースの設定は設定ファイルからの相対パスになります（#543）

以前は、さまざまな構成オプションの相対パスは、現在の作業ディレクトリからの相対パスとして解決されていました。現在は、構成ファイルからの相対パスとして解決されるようになりました。ドキュメントでは常に、構成ファイル（プロジェクトルート）を含むディレクトリからさまざまなMkDocsコマンドを実行することを推奨してきたため、この変更はほとんどのユーザーに影響を与えません。ただし、自動ビルドの実装や、プロジェクトルート以外の場所からのコマンドの実行がはるかに簡単になります。

-f/--config-fileオプションを使用して、構成ファイルを指定するだけで済みます。

mkdocs build --config-file /path/to/my/config/file.yml

以前と同様に、ファイルが指定されていない場合、MkDocsは現在の作業ディレクトリにあるmkdocs.ymlという名前のファイルを探します。

YAMLメタデータのサポートを追加しました（#1542）

以前は、MkDocsはMultiMarkdownスタイルのメタデータのみをサポートしていました。これは、さまざまなデータ型を認識せず、かなり制限がありました。MkDocsはMarkdownドキュメントでYAMLスタイルのメタデータもサポートするようになりました。MkDocsは、YAMLスタイルのメタデータまたはMultiMarkdownスタイルのメタデータを使用しているかを判断するために、デリミタ（---または...）の有無に依存します。

以前は、MkDocsはデリミタの間のMultiMarkdownスタイルのメタデータを認識していました。現在、デリミタが検出されたが、デリミタの間のコンテンツが有効なYAMLメタデータではない場合、MkDocsはそのコンテンツをMultiMarkdownスタイルのメタデータとして解析しようとしません。したがって、MultiMarkdownスタイルのメタデータにはデリミタを含めてはなりません。詳細は、MultiMarkdownスタイルのメタデータのドキュメントを参照してください。

バージョン0.17より前は、MkDocsはすべてのメタデータ値を文字列のリストとして返していました（1行であっても、1つの文字列のリストを返していました）。バージョン0.17では、その動作は各値を単一の文字列として返すように変更されました（複数行は結合されました）。これは一部のユーザーにとって制限があることがわかりました（#1471を参照）。この動作は、現在のバージョンのMultiMarkdownスタイルのメタデータでは引き続き継続されます。ただし、YAMLスタイルのメタデータは、"安全な" YAMLデータ型の全範囲をサポートしています。したがって、複雑なメタデータはYAMLスタイルを使用することをお勧めします（詳細はYAMLスタイルのメタデータのドキュメントを参照してください）。実際、将来のバージョンのMkDocsでは、MultiMarkdownスタイルのメタデータのサポートが非推奨になる可能性があります。

検索プラグインのリファクタリング

検索プラグインは、次の機能のサポートを含むように完全にリファクタリングされました。

  • フォールバック付きでブラウザでWebワーカーを使用（#1396）。
  • オプションで、検索インデックスをローカルで事前構築（#859 & #1061）。
  • lunr.js 2.xにアップグレード（#1319）。
  • 英語以外の言語での検索のサポート（#826）。
  • ユーザーが単語の区切り文字を定義できるように（#867）。
  • 長さが2を超えるクエリの検索のみを実行（#1127）。
  • require.jsへの依存関係を削除（#1218）。
  • 検索インデックスの圧縮（#1128）。

ユーザーは、利用可能な構成オプションを確認できます。テーマの作成者は、検索とテーマがどのように相互作用するかを確認する必要があります。

theme_dir構成オプションが完全に非推奨に

バージョン0.17以降、非推奨のtheme_dirオプションはcustom_dirオプションに置き換えられました。ユーザーがtheme_dirオプションを設定していた場合、MkDocsバージョン0.17は値をtheme.custom_dirオプションにコピーし、警告を発行しました。バージョン1.0以降、値はコピーされなくなり、エラーが発生します。

バージョン1.0へのその他の変更と追加

  • キーボードショートカットは、一般的に使用されるアクセシビリティショートカットと競合しないように変更されました（#1502）。
  • ユーザーフレンドリーなYAML解析エラー（#1543）。
  • Python 3.7を正式にサポート。
  • テーマ構成ファイルが見つからない場合、エラーが発生するようになりました。
  • 空のextra_cssおよびextra_javascript設定で警告が発生しなくなりました。
  • 組み込みテーマにhighlight.js構成設定を追加（#1284）。
  • 結果が選択されたときに検索モーダルを閉じる（#1527）。
  • AnchorLinksにレベル属性を追加（#1272）。
  • gh-deployスクリプトにMkDocsバージョンチェックを追加（#640）。
  • Markdown拡張機能のエラーメッセージを改善。（#782）。
  • Python 3.3の公式サポートを終了し、tornado>=5.0を設定（#1427）。
  • GitLab編集リンクのサポートを追加（#1435）。
  • リリースノートからGitHub issueへのリンク（#644）。
  • gh-deployコミットメッセージで{sha}と{version}を展開（#1410）。
  • sitemap.xmlを圧縮（#1130）。
  • JSスクリプトの読み込みを遅延（#1380）。
  • 検索入力にtitle属性を追加（#1379）。
  • RespondJSを最新バージョンに更新（#1398）。
  • Google Analyticsを常にHTTPS経由で読み込み（#1397）。
  • スクロールのフレームレートを改善（#1394）。
  • より多くのバージョン情報を提供。（#1393）。
  • writing-your-docs.mdをリファクタリング（#1392）。
  • 100％未満にズームするときのSafariのバグを回避（#1389）。
  • bodyとアニメーションへのclickyクラスの追加を削除。（#1387）。
  • 検索プラグインがextra_javascriptファイルを再注入するのを防止（#1388）。
  • より柔軟にするためにcopy_media_filesユーティリティ関数をリファクタリング（#1370）。
  • PyPIデプロイメントドキュメントを削除（#1360）。
  • Python-Markdownライブラリへのリンクを更新（#1360）。
  • MkDocsコマンドのmanページを生成する方法をドキュメント化（#686）。

バージョン0.17.5 (2018-07-06)

  • バグ修正: Python 3.7とPEP 479の非互換性を修正（#1518）。

バージョン0.17.4 (2018-06-08)

  • バグ修正: sitemap.xmlにマルチレベルネストのサポートを追加（#1482）。

バージョン0.17.3 (2018-03-07)

  • バグ修正: 5.0の変更により、依存関係tornado>=4.1,<5.0を設定（#1428）。

バージョン0.17.2 (2017-11-15)

  • バグ修正: extra_* 設定の回帰を修正しました (#1335 & #1336)。

バージョン 0.17.1 (2017-10-30)

  • バグ修正: 末尾のスラッシュがない repo_url をサポートします。(#1321)。
  • バグ修正: mkdocs.toc.TableOfContext に長さのサポートを追加します (#1325)。
  • バグ修正: サードパーティのテーマ向けに、検索プラグインにテーマ固有の設定を追加します (#1316)。
  • バグ修正: ローカルサーバーで site_url を dev_addr でオーバーライドします (#1317)。

バージョン 0.17.0 (2017-10-19)

バージョン 0.17.0 の主な追加点

プラグイン API。 (#206)

新しい プラグイン API が MkDocs に追加され、ユーザーは独自のカスタム動作を定義できるようになりました。API の詳細については、付属のドキュメントを参照してください。

以前組み込まれていた検索機能は削除され、動作は変更せずにプラグイン（「search」という名前）にラップされました。MkDocs がビルドすると、検索インデックスは mkdocs/search_index.json ではなく search/search_index.json に書き込まれるようになりました。構成にプラグイン設定が定義されていない場合、search プラグインはデフォルトで含まれます。デフォルトのオーバーライドについては、構成ドキュメントを参照してください。

テーマのカスタマイズ。 (#1164)

テーマ固有のカスタマイズを提供するためのサポートが追加されました。テーマの作成者は、テーマ構成に記載されているデフォルトオプションを定義できます。テーマは、別のテーマを継承し、レンダリングするさまざまな静的テンプレートを定義し、テンプレート内の動作を制御するための任意のデフォルト変数を定義できるようになりました。テーマの構成は、テンプレートファイルのルートに配置する必要がある mkdocs_theme.yml という名前の構成ファイルで定義します。構成ファイルが見つからない場合は警告が表示され、今後のリリースではエラーが表示されます。

ユーザーは、ネストされたオプションを受け入れるようになった mkdocs.yml 構成ファイルの theme 構成オプションでこれらのデフォルトをオーバーライドできます。このようなネストされたオプションの 1 つが custom_dir オプションで、これは現在非推奨の theme_dir オプションに代わるものです。以前に theme_dir オプションを設定していたユーザーには警告が発行され、今後のリリースではエラーが予想されます。

構成が以前に次のように theme_dir を定義していた場合

theme: mkdocs
theme_dir: custom

構成は次のように調整する必要があります

theme:
  name: mkdocs
  custom_dir: custom

詳細については、theme 構成オプションのドキュメントを参照してください。

以前に非推奨になったテンプレート変数を削除しました。 (#1168)

ページテンプレート

ページテンプレートのプライマリ エントリ ポイントが base.html から main.html に変更されました。これにより、ユーザーが main.html をオーバーライドし、base.html を拡張しながら base.html を引き続き存在させることができます。バージョン 0.16 では、main.html テンプレートが存在しない場合でも base.html は引き続き機能しましたが、非推奨の警告が表示されました。バージョン 1.0 では、main.html テンプレートが存在しない場合、ビルドは失敗します。

コンテキスト変数

テンプレート コンテキスト内のページ固有の変数名が カスタムテーマで定義されているようにリファクタリングされました。古い変数名はバージョン 0.16 で警告を発行しましたが、バージョン 1.0 で削除されました。

次の古いページ変数は、ユーザーが作成したテンプレートおよびサードパーティのテンプレートで新しいものに更新する必要があります。

古い変数名 新しい変数名
current_page page
page_title page.title
content page.content
toc page.toc
meta page.meta
canonical_url page.canonical_url
previous_page page.previous_page
next_page page.next_page

さらに、いくつかのグローバル変数が変更または削除されており、ユーザーが作成したテンプレートおよびサードパーティのテンプレートは、以下に示すように更新する必要があります。

古い変数名 新しい変数名または式
current_page page
include_nav nav|length>1
include_next_prev (page.next_page or page.previous_page)
site_name config.site_name
site_author config.site_author
page_description config.site_description
repo_url config.repo_url
repo_name config.repo_name
site_url config.site_url
copyright config.copyright
google_analytics config.google_analytics
homepage_url nav.homepage.url
favicon {{ base_url }}/img/favicon.ico

自動設定される extra_css および extra_javascript は完全に非推奨になりました。 (#986)

以前のバージョンの MkDocs では、extra_css または extra_javascript 設定が空の場合、MkDocs は docs_dir をスキャンし、検出されたすべての CSS ファイルと JavaScript ファイルを各設定に自動的に設定していました。バージョン 0.16 では、この動作は非推奨になり、警告が発行されました。0.17 では、一覧表示されていない CSS ファイルと JavaScript ファイルは HTML テンプレートには含まれませんが、警告が発行されます。つまり、それらは引き続き site-dir にコピーされますが、明示的にリストされていない場合、テーマに影響を与えることはありません。

docs_dir 内のすべての CSS ファイルと JavaScript ファイルは、今後 extra_css または extra_javascript 構成設定に明示的にリストする必要があります。

バージョン 0.17.0 のその他の変更と追加

  • MkDocs テーマに「編集リンク」サポートを追加しました (#1129)
  • BOM を考慮して、utf-8-sig でファイルを開きます (#1186)
  • シンボリックリンクが一貫して追跡されるようになりました (#1134)
  • 含まれるテーマにキーボード ナビゲーション ショートカットのサポートが追加されました (#1095)
  • config_options のリファクタリングと改善 (#1296)
  • Python 3.6 のサポートを正式に追加しました (#1296)
  • readthedocs テーマに 404 エラー ページを追加しました (#1296))
  • Markdown 処理の内部リファクタリング (#713)
  • mkdocs-bootstrap テーマと mkdocs-bootswatch テーマの特別なエラー メッセージを削除しました (#1168)
  • レガシーのページ構成はサポートされなくなりました (#1168)
  • 非推奨の json コマンドが削除されました (#481)
  • Python 2.6 のサポートが中止されました (#165)
  • ビルド中にファイル アクセス許可がコピーされなくなりました (#1292)
  • edit_uri でクエリ文字列とフラグメント文字列をサポートします (#1224 & #1273)

バージョン 0.16.3 (2017-04-04)

  • readthedocs テーマでの自動スクロールによって発生するエラーを修正しました (#1177)
  • ドキュメントのいくつかのタイプミスを修正しました (#1181 & #1185)
  • 0.16.2 で導入された livereload サーバーへの回帰を修正しました (#1174)

バージョン 0.16.2 (2017-03-13)

  • システムルート (/) は site_dir または docs_dir の有効なパスではありません (#1161)
  • readthedocs テーマ ナビゲーションのリファクタリング (#1155 & #1156)
  • 開発サーバーでカスタム エラー ページを提供するサポートを追加しました (#1040)
  • エラー ページで nav.homepage.url が空白でないことを確認します (#1131)
  • livereload の依存関係を 2.5.1 に増やしました (#1106)

バージョン 0.16.1 (2016-12-22)

  • scrollspy の動作がナビゲーションバーに影響を与えないことを確認します (#1094)
  • テーマはユーザーが明示的に要求した場合にのみ「ロード」します (#1105)

バージョン 0.16 (2016-11-04)

バージョン 0.16.0 の主な追加点

テンプレート変数のリファクタリング。（#874）

ページコンテキスト

カスタムテーマで定義されているように、テンプレートコンテキスト内のページ固有の変数名がリファクタリングされました。古い変数名は警告を発しますが、バージョン0.16では引き続き動作します。ただし、将来のバージョンで削除される可能性があります。

次の古いページ変数は、ユーザーが作成したテンプレートおよびサードパーティのテンプレートで新しいものに更新する必要があります。

古い変数名 新しい変数名
current_page page
page_title page.title
content page.content
toc page.toc
meta page.meta
canonical_url page.canonical_url
previous_page page.previous_page
next_page page.next_page
グローバルコンテキスト

さらに、多数のグローバル変数が変更または非推奨となりました。以下に示すように、ユーザー作成およびサードパーティのテンプレートを更新する必要があります。

以前は、グローバル変数 include_nav はナビゲーションのページ数に基づいてプログラムで変更されていました。この変数は警告を発しますが、バージョン0.16では引き続き動作します。ただし、将来のバージョンで削除される可能性があります。代わりに {% if nav|length>1 %} を使用してください。

以前は、グローバル変数 include_next_prev はナビゲーションのページ数に基づいてプログラムで変更されていました。この変数は警告を発しますが、バージョン0.16では引き続き動作します。ただし、将来のバージョンで削除される可能性があります。代わりに {% if page.next_page or page.previous_page %} を使用してください。

以前は、グローバル変数 page_description は現在のページがホームページであるかどうかに基づいてプログラムで変更されていました。現在は単に config['site_description'] にマップされるだけです。テンプレート内で条件付きで説明を変更するには {% if page.is_homepage %} を使用してください。

グローバル変数 homepage_url は nav.homepage.url に直接マップされ、非推奨になっています。この変数は警告を発しますが、バージョン0.16では引き続き動作します。ただし、将来のバージョンで削除される可能性があります。代わりに nav.homepage.url を使用してください。

グローバル変数 favicon は構成設定 site_favicon にマップされます。テンプレート変数と構成設定の両方が非推奨になり、警告を発しますが、バージョン0.16では引き続き動作します。将来のバージョンで削除される可能性があります。代わりにテンプレートで {{ base_url }}/img/favicon.ico を使用してください。ユーザーはカスタムのファビコンアイコンのコピーを docs_dir または theme_dir のいずれかの img/favicon.ico に保存するだけで済みます。

多くの変数は、config 内の同様の名前の変数に直接マップされます。これらの変数は非推奨になり、警告を発しますが、バージョン0.16では引き続き動作します。ただし、将来のバージョンで削除される可能性があります。代わりに config.var_name を使用してください。ここで、var_name は 構成変数の1つの名前です。

以下は、グローバルコンテキストに加えられたすべての変更の概要です。

古い変数名 新しい変数名または式
current_page page
include_nav nav|length>1
include_next_prev (page.next_page or page.previous_page)
site_name config.site_name
site_author config.site_author
page_description config.site_description
repo_url config.repo_url
repo_name config.repo_name
site_url config.site_url
copyright config.copyright
google_analytics config.google_analytics
homepage_url nav.homepage.url
favicon {{ base_url }}/img/favicon.ico

テンプレートのカスタマイズの強化。（#607）

組み込みテーマは、多くのパーツがテンプレートブロックでラップされるように更新されました。これにより、theme_dir 構成設定を使用して各個々のブロックを簡単にオーバーライドできます。新しい設定なしで、別の分析サービスを使用したり、デフォルトの検索機能を置き換えたり、ナビゲーションの動作を変更したりできます。詳細については、関連するドキュメントを参照してください。

この機能を有効にするために、ページテンプレートのプライマリエントリーポイントが base.html から main.html に変更されました。これにより、ユーザーが main.html をオーバーライドし、base.html を拡張しながら、base.html を引き続き存在させることができます。バージョン0.16では、main.html テンプレートが存在しない場合、base.html は引き続き動作しますが、非推奨となり、警告が表示されます。バージョン1.0では、main.html テンプレートが存在しないとビルドが失敗します。カスタムおよびサードパーティのテンプレートは、それに応じて更新する必要があります。

サードパーティのテーマを更新する最も簡単な方法は、次の行のみを含む main.html ファイルを追加することです。

{% extends "base.html" %}

これにより、テーマには main.html エントリーポイントが含まれ、組み込みテーマと同様の方法でブロックのオーバーライドもサポートされます。サードパーティのテーマは、このようなカスタマイズをサポートするために、テンプレートのさまざまな部分をブロックでラップすることをお勧めします。

自動入力される extra_css と extra_javascript の非推奨。（#986）

以前のバージョンの MkDocs では、extra_css または extra_javascript 構成設定が空の場合、MkDocs は docs_dir をスキャンし、見つかったすべての CSS および JavaScript ファイルを使用して各設定を自動入力していました。この動作は非推奨となり、警告が表示されます。次のリリースでは、自動入力機能は動作しなくなり、リストされていない CSS および JavaScript ファイルは HTML テンプレートに含まれなくなります。つまり、それらは site-dir にコピーされますが、明示的にリストされていない場合はテーマに影響を与えません。

docs_dir 内のすべての CSS ファイルと JavaScript ファイルは、今後 extra_css または extra_javascript 構成設定に明示的にリストする必要があります。

ダーティビルドのサポート。（#990）

大規模なサイトの場合、ページの作成に必要なビルド時間が問題になる可能性があるため、「ダーティ」ビルドモードが作成されました。このモードでは、生成されたHTMLとソースマークダウンの変更時間を比較するだけです。マークダウンがHTML以降に変更されている場合、ページが再構築されます。それ以外の場合、ページはそのまま残ります。このモードは、mkdocs serve コマンドと mkdocs build コマンドの両方で呼び出すことができます。

mkdocs serve --dirtyreload
mkdocs build --dirty

ページの構築におけるこの方法は、コンテンツの開発専用であることに注意することが重要です。ナビゲーションやその他のリンクは他のページで更新されないためです。

より厳密なディレクトリ検証

以前は、site_dir が docs_dir の子ディレクトリである場合、警告が表示されていました。これにより、エラーが発生するようになりました。さらに、docs_dir が子ディレクトリではなく、構成ファイルを含むディレクトリに設定されている場合もエラーが発生するようになりました。ドキュメント化されたレイアウトにより適合するように、ディレクトリ構造を再配置する必要があります。

バージョン 0.16.0 のその他の変更点と追加点

  • バグ修正：Windows で Python 3 を使用した gh-deploy コマンドのサポート（#722）
  • バグ修正：Python パッケージのビルドに .woff2 フォントファイルを含める（#894）
  • ドキュメントホームページ/チュートリアルのさまざまな更新と改善（#870）
  • バグ修正：構成ファイルの変更に対するライブリロードのサポート（#735）
  • バグ修正：メディアファイルと一緒にメディア以外のテンプレートファイルがコピーされなくなった（#807）
  • mkdocs build および mkdocs serve コマンドでテーマディレクトリを指定するフラグ（-e/--theme-dir）を追加（#832）
  • Windows および Python 2 での Unicode ファイル名の問題を修正。（#833）
  • MkDocs テーマのインラインコードのスタイルを改善。（#718）
  • バグ修正：JavaScript に渡すときに変数を JSON に変換（#850）
  • ReadTheDocs テーマを更新して、アップストリームのフォントサイズと色に近づけました。（#857）
  • マウスがパーマリンクマーカーから遠く離れている場合に表示される問題を修正（#843）
  • バグ修正：ページ構成を自動的に作成するときに、ディレクトリ名に含まれるピリオドを処理（#728）
  • 大規模なドキュメントのパフォーマンスが向上する Lunr 0.7 への検索を更新（#859）
  • バグ修正：「再現可能な」ビルドのための SOURCE_DATE_EPOCH 環境変数をサポート（#938）
  • メディアファイルのコピー時にリンクを追跡（#869）。
  • 「編集」リンクをリポジトリのルートではなく、ソースリポジトリ内のファイルに直接ポイントするように変更（#975）、新しいedit_uri設定で構成可能。
  • バグ修正：CLI で指定されていない場合、厳密モードの構成値をオーバーライドしない（#738）。
  • リポジトリへのプッシュを強制する gh-deploy コマンドに --force フラグを追加（#973）。
  • readthedocs テーマで現在選択されているメニュー項目の配置を改善（#888）。
  • http://user.github.io/repo => https://user.github.io/repo/（#1029）。
  • インストール手順を改善（#1028）。
  • 幅の広いテーブルに対応し、インラインコードスパンを常にラップ（#834）。
  • バグ修正：エラーテンプレートから nav & media リンクで絶対 URL を使用（#77）。

バージョン 0.15.3（2016-02-18）

  • 指定されたテーマが見つからない場合のエラーメッセージを改善。
  • 相対シンボリックリンクの問題を修正（#639）

バージョン 0.15.2 (2016-02-08)

バージョン 0.15.1 (2016-01-30)

  • パッケージメンテナー向けに、サポートされる最小のClickバージョンを3.3に下げました。(#763)

バージョン 0.15.0 (2016-01-21)

バージョン 0.15.0 の主な追加点

インストール可能なテーマのサポートを追加

MkDocsは、Pythonパッケージを通じて配布されるテーマをサポートするようになりました。この追加により、BootstrapとBootswatchのテーマは外部のgitリポジトリとPythonパッケージに移動されました。これらの特定のテーマの詳細については、それぞれのドキュメントを参照してください。

これらは、将来のリリースまでMkDocsにデフォルトで含まれます。その後、pipを使用してインストールできるようになります。pip install mkdocs-bootstrap および pip install mkdocs-bootswatch

テーマの使用とカスタマイズの詳細については、テーマのカスタマイズのドキュメントを、新しいテーマの作成と配布については、カスタムテーマのドキュメントを参照してください。

バージョン 0.15.0 のその他の変更点と追加点

  • Markdownファイルへの絶対リンクを使用する際の問題を修正しました。(#628)
  • Python 2.6のサポートを非推奨とし、1.0.0で削除予定です。(#165)
  • Pythonバージョン3.5の公式サポートを追加しました。
  • site_descriptionおよびsite_authorのサポートを、ReadTheDocsテーマに追加しました。(#631)
  • FontAwesomeを4.5.0に更新しました。(#789)
  • X-UA-Compatibleを使用してIEのサポートを強化しました。(#785)
  • Pythonの-mフラグのサポートを追加しました。(#706)
  • バグ修正: 自動生成されたページの順序を一定に保ちます。(#638)
  • バグ修正: MkDocsテーマの目次がページに対して長すぎる場合に、スクロールするようにしました。(#204)
  • バグ修正: ページ属性のancestorsに、最初のものだけでなくすべての子孫を追加するようにしました。(#693)
  • バグ修正: ビルド出力に再びHTMLを含めるようにしました。(#691)
  • バグ修正: Read the Docsにファイル名を渡すようにしました。(#721 および RTD#1480)
  • バグ修正: Clickのunicode_literals警告を抑制しました。(#708)

バージョン 0.14.0 (2015-06-09)

  • すべての設定文字列がUnicodeとしてロードされるようにすることで、Unicode処理を改善しました。(#592)
  • sixライブラリへの依存関係を削除しました。(#583)
  • ghp-importライブラリへの依存関係を削除しました。(#547)
  • すべてのサブコマンドに--quietおよび--verboseオプションを追加しました。(#579)
  • ほとんどのコマンドラインオプションに短いオプション (-a) を追加しました。(#579)
  • readthedocsテーマに著作権フッターを追加しました。(#568)
  • mkdocs serveで要求されたポートが既に使用されている場合、ユーザに完全なスタックトレースを表示しないようにしました。(#596)
  • バグ修正: スペースを含む検索時にJavaScriptのエンコード問題を修正しました。(#586)
  • バグ修正: mkdocs.ymlがgitリポジトリのルートにない場合に、gh-deployが機能するようにしました。(#578)
  • バグ修正: TOCの解析中にHTMLエンティティを処理（ドロップせずにパススルー）するようにしました。(#612)
  • バグ修正: extra_templatesを空のリストにデフォルト設定し、自動的に検出しないようにしました。(#616)

バージョン 0.13.3 (2015-06-02)

  • バグ修正: site_dirがdocs_dir内にある場合、ビルドに問題がないため、複数の回数ビルドするユーザーに不便が生じるため、検証エラーを警告に軽減しました。(#580)

バージョン 0.13.2 (2015-05-30)

  • バグ修正: すべてのエラーと警告が終了前にログに記録されるようにしました。(#536)
  • バグ修正: ReadTheDocsとの互換性の問題を修正しました。(#554)

バージョン 0.13.1 (2015-05-27)

  • バグ修正: pages設定にパスのリストのみを含む最小限の設定での問題を修正しました。(#562)

バージョン 0.13.0 (2015-05-26)

バージョン 0.13.0 の非推奨事項

JSONコマンドを非推奨に

このリリースでは、mkdocs jsonコマンドは非推奨とされ、使用すると非推奨の警告が表示されます。MkDocsの今後のリリース、遅くともバージョン1.0で削除される予定です。mkdocs jsonコマンドは、ユーザーがドキュメントの内容をJSONファイルとして出力する便利な方法を提供していましたが、MkDocsに検索機能が追加されたことで、この機能は重複しています。

MkDocsビルドのすべての内容を含む新しいインデックスが、site_dirに作成されます。したがって、site_dirのデフォルト値を使用すると、site/mkdocs/search_index.jsonにあります。

この新しいファイルは、すべてのMkDocsビルド (mkdocs buildを使用) で作成され、有効にするための設定は必要ありません。

ページ構成の変更

mkdocs.ymlファイルでページ、特にネストされたページを定義する新しい方法を提供し、既存のアプローチを非推奨とし、サポートはMkDocs 1.0で削除されます。

組み込みテーマの削除に関するユーザーへの警告

mkdocsとreadthedocs以外のすべてのテーマは、MkDocsの将来のリリースで外部パッケージに移動されます。これにより、MkDocsのリリース外でより簡単にサポートと更新を行うことができます。

バージョン 0.13.0 の主な追加点

MkDocsに検索のサポートが追加されました。これは、JavaScriptライブラリlunr.jsに基づいています。mkdocsとreadthedocsの両方のテーマに追加されています。独自のテーマに追加するための検索のサポートについては、カスタムテーマのドキュメントを参照してください。

新しいコマンドラインインターフェース

MkDocsのコマンドラインインターフェースは、PythonライブラリClickで書き直されました。これは、MkDocsがより使いやすいインターフェースと、より優れたヘルプ出力を備えていることを意味します。

この変更は、ドキュメント化されていなかったため、さまざまなコマンドに設定オプションを渡すことができましたが、部分的に後方互換性がありません。現在、設定オプションの小さなサブセットのみがコマンドに渡すことができます。コマンドと利用可能な引数をすべて表示するには、mkdocs --helpおよびmkdocs build --helpを使用してください。

追加のHTMLおよびXMLファイルのサポート

extra_javascriptおよびextra_css設定オプションと同様に、extra_templatesという新しいオプションが追加されました。これは、プロジェクトのdocsディレクトリにある.htmlまたは.xmlファイルで自動的に入力されます。

ユーザーは静的なHTMLおよびXMLファイルを配置してコピーするか、Jinja2構文を使用して、グローバル変数を活用することもできます。

デフォルトでは、MkDocsはこのアプローチを使用してドキュメントのサイトマップを作成します。

バージョン 0.13.0 のその他の変更点と追加点

  • Markdown拡張機能の設定オプションのサポートを追加しました。(#435)
  • MkDocsは、Python wheelsを提供するようになりました。(#486)
  • ホームページにのみビルド日付とMkDocsバージョンを含めるようにしました。(#490)
  • ドキュメントビルドのサイトマップを生成するようにしました。(#436)
  • 設定でネストされたページを定義するより明確な方法を追加しました。(#482)
  • テンプレートに任意の変数を渡すためのextra configオプションを追加しました。(#510)
  • よりシンプルな開発サーバーのために、mkdocs serve に --no-livereload を追加しました。（#511）
  • すべてのテーマに著作権表示のサポートを追加しました。（#549）
  • mkdocs gh-deploy でカスタムコミットメッセージのサポートを追加しました。（#516）
  • バグ修正: index.md という名前の Markdown ファイルと同じディレクトリ内のメディアへのリンクを修正しました。（#535）
  • バグ修正: Unicode ファイル名に関するエラーを修正しました。（#542）。

バージョン 0.12.2 (2015-04-22)

  • バグ修正: ページ設定で一部の子タイトルが欠落しているが、他のタイトルが提供されている場合にエラーが発生する問題を修正しました。（#464）

バージョン 0.12.1 (2015-04-14)

  • バグ修正: 一部のブラウザで目次の最下部項目がクリックできなかった CSS のバグを修正しました。

バージョン 0.12.0 (2015-04-14)

  • CLI 出力に現在の MkDocs バージョンを表示します。（#258）
  • gh-deploy 使用時に CNAME ファイルを確認します。（#285）
  • すべてのテーマのナビゲーションにホームページを戻しました。（#271）
  • ローカルリンクチェック用の厳密モードを追加しました。（#279）
  • すべてのテーマに Google アナリティクスのサポートを追加しました。（#333）
  • ReadTheDocs および MkDocs テーマの出力にビルド日と MkDocs バージョンを追加しました。（#382）
  • すべてのテーマでハイライト表示を標準化し、不足している言語を追加しました。（#387）
  • ビルドに関する詳細を表示するための verbose フラグ (-v) を追加しました。（#147）
  • GitHub にデプロイする際にリモートブランチを指定するオプションを追加しました。これにより、個人サイトとリポジトリサイトの両方で GitHub Pages にデプロイできます。（#354）
  • ReadTheDocs テーマ HTML に favicon のサポートを追加しました。（#422）
  • ファイルの編集時にブラウザを自動的に更新します。（#163）
  • バグ修正: コードブロック内の URL を再書き込みしないようにしました。（#240）
  • バグ修正: docs_dir からメディアをコピーする際にドットファイルをコピーしないようにしました。（#254）
  • バグ修正: ReadTheDocs テーマでのテーブルのレンダリングを修正しました。（#106）
  • バグ修正: すべてのブートストラップテーマの下部にパディングを追加しました。（#255）
  • バグ修正: ネストされた Markdown ページと自動ページ設定に関する問題を修正しました。（#276）
  • バグ修正: GitHub Enterprise での URL 解析エラーを修正しました。（#284）
  • バグ修正: mkdocs.yml が完全に空の場合にエラーが発生しないようにしました。（#288）
  • バグ修正: 相対 URL と Markdown ファイルに関する多くの問題を修正しました。（#292）
  • バグ修正: ページが見つからない場合にビルドを停止せず、他のページを続行するようにしました。（#150）
  • バグ修正: ページタイトルから site_name を削除しました。これは手動で追加する必要があります。（#299）
  • バグ修正: 目次が Markdown を切り捨ててしまう問題を修正しました。（#294）
  • バグ修正: BitBucket のホスト名を修正しました。（#339）
  • バグ修正: すべてのリンクがスラッシュで終わるようにしました。（#344）
  • バグ修正: readthedocs テーマのリポジトリリンクを修正しました。（#365）
  • バグ修正: MkDocs をオフラインで使用する際の問題を避けるため、jQuery をローカルに含めるようにしました。（#143）
  • バグ修正: docs_dir が site_dir 内、またはその逆にならないようにしました。（#384）
  • バグ修正: ReadTheDocs テーマのインライン CSS を削除しました。（#393）
  • バグ修正: ページ設定の処理順序が原因で発生していた子タイトルの問題を修正しました。（#395）
  • バグ修正: テーマが存在しない場合にライブリロード中にエラーが発生しないようにしました。（#373）
  • バグ修正: Meta 拡張機能が存在しない場合に発生する問題を修正しました。（#398）
  • バグ修正: 長いインラインコードが画面からはみ出さないように折り返すようにしました。（#313）
  • バグ修正: HTML 解析の正規表現を削除し、HTMLParser で解析して、コードを含むタイトルに関する問題を修正しました。（#367）
  • バグ修正: アンカーへのスクロールがナビゲーションの下にタイトルを隠してしまう問題を修正しました。（#7）
  • バグ修正: bootswatch テーマの HTML テーブルに適切な CSS クラスを追加しました。（#295）
  • バグ修正: mkdocs serve で特定のコンフィグファイルを渡す際のエラーを修正しました。（#341）
  • バグ修正: mkdocs new コマンドで index.md ファイルを上書きしないようにしました。（#412）
  • バグ修正: ReadTheDocs テーマのコードから太字と斜体を削除しました。（#411）
  • バグ修正: MkDocs テーマで画像をインラインで表示するようにしました。（#415）
  • バグ修正: ReadTheDocs テーマでの no-highlight の問題を修正しました。（#319）
  • バグ修正: mkdocs build --clean を使用する際に隠しファイルを削除しないようにしました。（#346）
  • バグ修正: Python >= 2.7 で Python-markdown の新しいバージョンをブロックしないようにしました。（#376）
  • バグ修正: プラットフォームをまたいでファイルを開く際のエンコードの問題を修正しました。（#428）

バージョン 0.11.1 (2014-11-20)

  • バグ修正: ReadTheDocs テーマでのコードハイライト表示に関する CSS の折り返し問題を修正しました。（#233）

バージョン 0.11.0 (2014-11-18)

  • 現在のテーマに 404.html ファイルが存在する場合はレンダリングします。（#194）
  • バグ修正: MkDocs および ReadTheDocs テーマでの長いナビゲーションバー、テーブルレンダリング、およびコードハイライト表示を修正しました。（#225）
  • バグ修正: google_analytics コードに関する問題を修正しました。（#219）
  • バグ修正: パッケージ tar から __pycache__ を削除しました。（#196）
  • バグ修正: 現在のページのアンカーに移動する Markdown リンクを修正しました。（#197）
  • バグ修正: すべての HTML に prettyprint well CSS クラスを追加せず、MkDocs テーマでのみ追加するようにしました。（#183）
  • バグ修正: ReadTheDocs テーマでセクションタイトルを表示するようにしました。（#175）
  • バグ修正: inotify を持たないファイルシステムでリビルドが機能するように、watchdog でポーリングオブザーバーを使用するようにしました。（#184）
  • バグ修正: 一般的な設定関連のエラーに関するエラー出力を改善しました。（#176）

バージョン 0.10.0 (2014-10-29)

  • Python 3.3 および 3.4 のサポートを追加しました。（#103）
  • 設定項目 markdown_extensions を使用して、Python-Markdown 拡張機能を設定可能にしました。（#74）
  • レンダリングされたドキュメントを JSON ファイルとして出力する mkdocs json コマンドを追加しました。（#128）
  • 出力ディレクトリから古いファイルを削除するために、build、json、および gh-deploy コマンドに --clean スイッチを追加しました。（#157）
  • 完全なテーマをコピーするのではなく、個々のテンプレートを置き換えることができるように、複数のテーマディレクトリをサポートしました。（#129）
  • バグ修正: readthedocs テーマでの <ul> レンダリングを修正しました。（#171）
  • バグ修正: 小さなディスプレイでの readthedocs テーマを改善しました。（#168）
  • バグ修正: 競合を避けるため、必要な Python パッケージのバージョンを緩和しました。(#104)
  • バグ修正: 特定の設定で目次が正しくレンダリングされない問題を修正しました。(#146)
  • バグ修正: サブページに埋め込まれた画像のパスを修正しました。(#138)
  • バグ修正: use_directory_urls 設定の動作を修正しました。(#63)
  • バグ修正: すべてのテーマで extra_javascript と extra_css をサポートしました。(#90)
  • バグ修正: Windows 環境下でのパス処理を修正しました。(#121)
  • バグ修正: readthedocs テーマでのメニュー生成を修正しました。(#110)
  • バグ修正: Windows 環境下での mkdocs コマンドの作成を修正しました。(#122)
  • バグ修正: 外部の extra_javascript と extra_css を正しく処理するように修正しました。(#92)
  • バグ修正: ファビコンのサポートを修正しました。(#87)