MkDocsでマニュアルを作る #5 多言語とバージョン管理

フレームワーク MkDocs Documentation Static Site
読了 3分

#4でドキュメントをインターネットに上げました。ユーザーが増えると、2つの要求が付いてきます。ひとつは別の言語でも見たいということで、もうひとつは古いバージョンの製品を使う人のために過去のドキュメントも残してほしいということです。この記事は、その2つを扱います。

今回のシリーズはMkDocsでマニュアルを作る全6回です。

  • #1 インストールから最初のドキュメントまで
  • #2 navと検索 — ドキュメントの情報構造を整える
  • #3 コンテンツ作成 — コードブロック、Mermaid、admonition
  • #4 Cloudflare Pagesでデプロイしてドメインをつなぐ
  • #5 多言語とバージョン管理 ← この記事
  • #6 メンテナンス — 検索、アクセシビリティ、ドキュメント文化

この記事では、言語を追加し、翻訳ファイルをつなぎ、バージョンごとのドキュメントを一緒に維持するところまで扱います。

言語を追加する — static-i18n #

多言語はmkdocs-static-i18nプラグインで付けます。まずインストールします。

i18nプラグインのインストール 
pip install mkdocs-static-i18n

mkdocs.ymlに言語を宣言します。ファイル名の後ろに言語コードを付ける方式(suffix)を使います。

mkdocs.yml — 多言語 
plugins:
  - i18n:
      docs_structure: suffix
      languages:
        - locale: ko
          default: true
          name: 한국어
        - locale: en
          name: English

翻訳ファイルを置く #

同じドキュメントの言語別バージョンは、ファイル名の後ろに言語コードを付けて並べて置きます。

翻訳ファイルを置く 
docs/
├─ index.md       # デフォルト言語(韓国語)
└─ index.en.md    # 英語

プラグインが両者を同じ記事の翻訳として認識し、上部に言語切り替えメニューを自動で表示します。翻訳していない記事はデフォルト言語に自動で置き換わるので、一度にすべてを翻訳しなくてもサイトが壊れません。

バージョン管理 — mike #

ここでMkDocsの強みが表れます。Hugo編ではバージョン管理機能がなくフォルダで直接分ける必要がありましたが、MkDocsにはmikeという専用ツールがあります。バージョンごとにドキュメントをスナップショットとして記録しておき、上部にバージョン選択のドロップダウンまで付けてくれます。

mikeでバージョンデプロイ 
pip install mike

# 1.0バージョンをデプロイして 'latest' エイリアスを付けます
mike deploy --push --update-aliases 1.0 latest

# デフォルトで開くバージョンを指定します
mike set-default --push latest

そしてmkdocs.ymlにバージョンプロバイダーをmikeに指定すると、ヘッダーにバージョンセレクターが現れます。

mkdocs.yml — バージョンセレクター 
extra:
  version:
    provider: mike

製品が2.0に上がったら、mike deploy 2.0 latestで新しいスナップショットを登録すればよいです。1.0のドキュメントはそのまま残り、古いバージョンを使うユーザーが引き続き参照できます。

まとめ #

この記事では、static-i18nで言語を追加して翻訳をつなぎ、mikeでバージョンスナップショットとセレクターを付けました。多言語もバージョン管理も、どちらもプラグインできれいに解決できる点がMkDocsエコシステムの長所です。

次回は最終回です。検索、アクセシビリティ、そしてドキュメントを長く生かし続けるメンテナンスの習慣まで、運用の観点を整理してシリーズを締めくくります。

X