更新情報

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で公開¹
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 was given.」が発生しました。

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が登録されていました。

github.com

エラー解決方法

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:

https://pypi.org/project/mkdocs-static-i18n/#history

つまり、ver1.0.0から機能追加により異なる設定が必要になる。ただし、新機能を必要としない場合はver0.56を明示的に指定すれば良いとのことでした。

具体的な機能追加の詳細は確認できなかったのですが、個人的にはver0.56を使用し続けるのは、バグや機能の観点で避けたいので下記記載のスクリプトを使用することにしました。

ultrabug.github.io

まず、私の環境ではバージョン管理に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とします。²

[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にする必要があるようです。³

ultrabug.github.io

最終的にファイルおよび、コードを以下（一部）のように変更したところ、warningは発生せずに起動できました。

まとめ

MkDocsで「mkdocs gh-deploy --force」を実行時に、「ERROR - Config value 'plugins': Plugin 'i18n' option 'languages': Expected a list of items, but a was given.」が発生し、GitHub Pagesへのデプロイに失敗することについて、エラー内容と解決方法について紹介しました。

正直言えば、今後もバージョンアップにより仕様が変わる可能性はあるため、どこまで参考になるかわかりませんが、どなたかの参考になれば幸いです。もし、参考になれば「はてなスター」を付けてもらえると励みになりますのでよろしくお願いします。

また、今回、GitHub Actionをパッケージのインストール指定をpipから、poetryで実行する形式（参考⁴）に変更することを考えました。ただ、issue観点で公式のpip版のデプロイ手順を使うユーザーが多数いると思うので、しばらくは、pip形式のまま運用することにしました。どこかのタイミングではlocalとremoteの設定を揃えることを再検討するかもしれません。⁵

以上です。

Material for MkDocs公式 / publishing-your-site
squidfunk.github.io
公開手順は下記記事でも紹介しています。
7rikazhexde-techlog.hatenablog.com↩
参考 [tool.poetry.dependencies]のバージョン記載方法 python-poetry.org↩
あくまで個人見解なので、ご注意ください。また、「The folder docs structure」は未確認です。⁶↩
参考までに別プロジェクトのGitHub Actionの例を記載します。このプロジェクトではpytest向けにpoetry installを使用した環境を使用しています。
github.com↩
v0.1.46でGitHub ActionをPoetryで管理する方法に変更しました。github.com↩
「20230923」で記載の通り、「The folder docs structure」でも成功しました。↩