更新情報
20230902
下記手順を確認したところ、プロジェクト直下のindex.en.mdを取得できず(デフォルトは日本語)に
404エラーになる現象を確認しています。
直下以下のフォルダ内のファイルの言語変更は問題なく動作します。
同様の現象が発生している場合は、バージョン固定(ver0.56)で対応するのが良いと思います。
20230923
mkdocs-material 9.1.16に更新したところ以下のWARNINGが表示されました。
WARNING - Language en is not supported by mkdocs-material==None, not setting the 'theme.language' option WARNING - Language ja is not supported by mkdocs-material==None, not setting the 'theme.language' option
mkdocs.ymlでtheme.languageで設定していましたが、pluginsでi18nを設定しても言語セレクタが表示されなくなりました。
theme: language: ja
具体的には、option-docs_structure記載の通り、docs_structure: folderにしてドキュメント記載のフォルダ構成にする必要があります。
plugins: - i18n: docs_structure: folder
結論から言えば、mkdocs-static-i18n 1.0.6で後述する1.0.0以降のi18nのプラグイン記述に変更すれば機能します。
the-folder-docs-structureでフォルダ構成にすれば機能しました。GitHub Pagesへのデプロイも問題ありませんでした。
the-suffix-structureでもlocalでのビルドでは問題ありませんでした。ただし、デプロイは未確認です。
概要
私は以下の仕様で、Material for MkDocsで作成したドキュメントをGitHub Actionsを使用してGitHub Pagesへデプロイ、および、Webサイト(Dev Insights Tips)として公開しています。
- MkDocsで多言語対応（日/英）として、mkdocs-static-i18n使用
- サイトはGitHub Pagesで公開1
- GitHub Actionsを使用してGitHub Pagesへのデプロイを自動化
しかし、2023/09/01にデプロイしたところ、mkdocs gh-deploy --forceで表題のエラーになりました。調べるとmkdocs-static-i18nの仕様とのことで、解決方法が公開されていました。
本記事ではエラーと解決方法について紹介します。
GitHub Actionの実行結果とエラー内容
使用中のYAMLファイル
# GitHub Actions to automate deployment of project documentation # Reference: https://squidfunk.github.io/mkdocs-material/publishing-your-site/?h=git+hub#github-pages name: ci on: push: branches: - main env: cache_id: "" permissions: contents: write jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/setup-python@v4 with: python-version: 3.x - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV - uses: actions/cache@v3 with: key: mkdocs-material-${{ env.cache_id }} path: .cache restore-keys: | mkdocs-material- - run: pip install mkdocs-material mkdocs-static-i18n pygments plantuml-markdown - run: mkdocs gh-deploy --force
Runアクション(pip install)
mkdocs-static-i18nは2023/09/01時点で最新のver1.0.2がインストールされていました。
# 省略 Successfully built paginate readtime Installing collected packages: paginate, watchdog, urllib3, soupsieve, six, regex, pyyaml, pygments, platformdirs, pathspec, packaging, mkdocs-material-extensions, mergedeep, MarkupSafe, markdown2, markdown, lxml, idna, cssselect, colorama, click, charset-normalizer, certifi, babel, requests, pyyaml-env-tag, python-dateutil, pyquery, pymdown-extensions, jinja2, beautifulsoup4, readtime, plantuml-markdown, ghp-import, mkdocs, mkdocs-static-i18n, mkdocs-material Successfully installed MarkupSafe-2.1.3 babel-2.12.1 beautifulsoup4-4.12.2 certifi-2023.7.22 charset-normalizer-3.2.0 click-8.1.7 colorama-0.4.6 cssselect-1.2.0 ghp-import-2.1.0 idna-3.4 jinja2-3.1.2 lxml-4.9.3 markdown-3.4.4 markdown2-2.4.10 mergedeep-1.3.4 mkdocs-1.5.2 mkdocs-material-9.2.6 mkdocs-material-extensions-1.1.1 mkdocs-static-i18n-1.0.2 packaging-23.1 paginate-0.5.6 pathspec-0.11.2 plantuml-markdown-3.9.2 platformdirs-3.10.0 pygments-2.16.1 pymdown-extensions-10.2.1 pyquery-2.0.0 python-dateutil-2.8.2 pyyaml-6.0.1 pyyaml-env-tag-0.1 readtime-3.0.0 regex-2023.8.8 requests-2.31.0 six-1.16.0 soupsieve-2.4.1 urllib3-2.0.4 watchdog-3.0.0 Notice: A new release of pip is available: 23.1.2 -> 23.2.1 Notice: To update, run: pip install --upgrade pip
Runアクション(mkdocs gh-deploy --force)
以下ログの通り、「ERROR - Config value 'plugins': Plugin 'i18n' option 'languages': Expected a list of items, but a
Run mkdocs gh-deploy --force
mkdocs gh-deploy --force
shell: /usr/bin/bash -e {0}
env:
cache_id: 35
pythonLocation: /opt/hostedtoolcache/Python/3.11.4/x64
PKG_CONFIG_PATH: /opt/hostedtoolcache/Python/3.11.4/x64/lib/pkgconfig
Python_ROOT_DIR: /opt/hostedtoolcache/Python/3.11.4/x64
Python2_ROOT_DIR: /opt/hostedtoolcache/Python/3.11.4/x64
Python3_ROOT_DIR: /opt/hostedtoolcache/Python/3.11.4/x64
LD_LIBRARY_PATH: /opt/hostedtoolcache/Python/3.11.4/x64/lib
ERROR - Config value 'plugins': Plugin 'i18n' option 'languages': Expected a list of items, but a <class 'dict'> was given.
Aborted with 1 configuration errors!
Error: Process completed with exit code 1.
エラー内容
エラーとして、ERROR - Config value 'plugins': Plugin 'i18n' option 'languages': Expected a list of items, but a <class 'dict'> was given.が出力されています。
調べると同様のエラーは発生しており、下記issueが登録されていました。
エラー解決方法
Contributerからの回答は以下の通りです。
The new version 1.0.0 of the plugin requires a different configuration setup. There is a migration tool provided:
https://ultrabug.github.io/mkdocs-static-i18n/setup/upgrading-to-1/
You can also modify your ci.yml to stick to the older version for now if you don't require new features:
Change mkdocs-static-i18n \ to mkdocs-static-i18n==0.56 \ as per the version history:
つまり、ver1.0.0から機能追加により異なる設定が必要になる。ただし、新機能を必要としない場合はver0.56を明示的に指定すれば良いとのことでした。
具体的な機能追加の詳細は確認できなかったのですが、個人的にはver0.56を使用し続けるのは、バグや機能の観点で避けたいので下記記載のスクリプトを使用することにしました。
まず、私の環境ではバージョン管理にPoetryを使用していますが、mkdocs-static-i18nのバージョンはver0.56だったので更新しました。
変更前のpyproject.toml
[tool.poetry.dependencies] mdformat = "^0.7.16" mkdocs-material = "^9.1.16" mkdocs-static-i18n = "^0.56" plantuml-markdown = "^3.9.2" pre-commit = "^3.3.3" pygments = "^2.16.1" python = "^3.10" tomlkit = "^0.11.8"
パッケージのバージョン確認(poetry show)
$ poetry show mergedeep 1.3.4 A deep merge function for 🐍. mkdocs 1.5.2 Project documentation with Markdown. mkdocs-material 9.2.6 Documentation that simply works mkdocs-material-extensions 1.1.1 Extension pack for Python Markdown and MkDocs Material. mkdocs-static-i18n 0.56 MkDocs i18n plugin using static translation markdown files mypy 1.5.1 Optional static typing for Python
変更後のpyproject.toml
mkdocs-static-i18nのバージョンを1.0.0以上にするため^1.0.0とします。2
[tool.poetry.dependencies] mdformat = "^0.7.16" mkdocs-material = "^9.1.16" mkdocs-static-i18n = "^1.0.0" # 変更 plantuml-markdown = "^3.9.2" pre-commit = "^3.3.3" pygments = "^2.16.1" python = "^3.10" tomlkit = "^0.11.8"
mkdocs-static-i18nの更新
$ poetry update mkdocs-static-i18n Updating dependencies Resolving dependencies... (1.2s) Package operations: 0 installs, 1 update, 0 removals • Updating mkdocs-static-i18n (0.56 -> 1.0.2) Writing lock file
更新後のビルド確認
バージョン更新後の動作確認のためビルドコマンドを実行します。 実行するとビルドコマンドでもエラーになることを確認しました。
$ poetry run mkdocs build -c
ERROR - Config value 'plugins': Plugin 'i18n' option 'languages': Expected a list of items, but a
<class 'dict'> was given.
mkdocs.ymlの更新
config_update_to_v1.pyを使用してmkdocs.yamlを更新します。
まずはファイルをプロジェクト直下に移動してスクリプトを実行します。
実行すると私の環境では以下の内容が出力されました。
$ poetry run python config_update_to_v1.py ./mkdocs.yml
please update your mkdocs plugins.i18n configuration to:
----------
i18n:
docs_structure: suffix
fallback_to_default: true
languages:
- build: true
default: false
locale: en
name: English
nav_translations:
Home: Home
- build: true
default: true
locale: ja
name: 日本語
reconfigure_material: true
reconfigure_search: true
記載の通り、上記内容をi18n configurationに反映し、以下のように変更しました。
再ビルドでWARNING
再度、poetry run mkdocs build -c実行するとを実行すると以下のWARNING(一部)が表示されました。
WARNING - A relative path to 'application/index.ja.md' is included in the 'nav' configuration, which is not found in the
documentation files.
これは、navにdocs以下に格納されるja.mdで指定されたパスのファイルがないということですが、ファイルは存在し、そもそも、ver0.56では動作していました。
調べると、記法は以下の公式ドキュメントに記載がありますが、「The suffix docs structure (default)」と「The folder docs structure」の2種類があります。
私は「The suffix docs structure (default)」を使用していましたが、結論から言えば、ver1.0.0以降ではdefault指定の言語は.<language>を付けない、つまり、index.jp.mdではなく、index.mdにする必要があるようです。3
最終的にファイルおよび、コードを以下（一部）のように変更したところ、warningは発生せずに起動できました。
まとめ
MkDocsで「mkdocs gh-deploy --force」を実行時に、「ERROR - Config value 'plugins': Plugin 'i18n' option 'languages': Expected a list of items, but a
正直言えば、今後もバージョンアップにより仕様が変わる可能性はあるため、どこまで参考になるかわかりませんが、どなたかの参考になれば幸いです。 もし、参考になれば「はてなスター」を付けてもらえると励みになりますのでよろしくお願いします。
また、今回、GitHub Actionをパッケージのインストール指定をpipから、poetryで実行する形式（参考4）に変更することを考えました。
ただ、issue観点で公式のpip版のデプロイ手順を使うユーザーが多数いると思うので、しばらくは、pip形式のまま運用することにしました。どこかのタイミングではlocalとremoteの設定を揃えることを再検討するかもしれません。5
以上です。
-
Material for MkDocs公式 / publishing-your-site
squidfunk.github.io
公開手順は下記記事でも紹介しています。
7rikazhexde-techlog.hatenablog.com↩ - 参考 [tool.poetry.dependencies]のバージョン記載方法 python-poetry.org↩
- あくまで個人見解なので、ご注意ください。また、「The folder docs structure」は未確認です。6↩
-
参考までに別プロジェクトのGitHub Actionの例を記載します。このプロジェクトでは
pytest向けにpoetry installを使用した環境を使用しています。
github.com↩ - v0.1.46でGitHub ActionをPoetryで管理する方法に変更しました。github.com↩
- 「20230923」で記載の通り、「The folder docs structure」でも成功しました。↩
