コンテンツにスキップ

2026-11-21

11/21

技術メモのサイトを Hugo から Zensical に移行した

経緯

  • このサイトは、2020年に旧Googleサイトから Hugo + Docsy に移行して作った。
  • 最後の更新は2024年2月。その後は更新が止まり、Hugo のビルドも動かなくなっていた。
  • Docsy は git submodule で、Node.js の依存もある。テーマごと管理するのが面倒だったので、依存が少なく管理が楽なツールに移すことにした。
  • 移行先は Zensical。Material for MkDocs の作者たちによる静的サイトジェネレーターで、Python 製。依存は uv で管理する。

実施した内容

  • 履歴: master が fork 元テンプレートの履歴を引きずっていたので、履歴を引き継がず、新しい main を空のコミットから作って記事をコピーした。旧 master は archive/hugo-doxy として残してある。
  • ビルドと公開: zensical.toml で設定し、GitHub Actions で GitHub Pages にデプロイする。公開元を「GitHub Actions」に切り替えた。
  • 記事の移行: 276ページ。変換は Python のスクリプトで機械的に行った。
  • 移行後の整理: memo/ 直下の日付メモを、年別のフォルダに移した。今後はアーカイブ運用をやめて、各年のフォルダの下に直接メモを作る。

変換で手を掛けたところ

  • ディレクトリ構成: Hugo の content/ja/a/ の a/ を除き、_index.md を index.md にした。記事の URL は変わった(/a/ が消えた)。
  • フロントマターと見出し: Hugo では title が自動で見出しになるが、Zensical ではならない。title を本文先頭の # 見出し に移した。weight、linkTitle などは削除した。
  • サイドバーの並び順: Hugo は weight で並べていたが、Zensical では zensical.toml の nav に全ページを明記する。ラベルは linkTitle を使い、並び順は Hugo の既定(weight、新しい日付の順)を再現して生成した。
  • ページ間リンク: {{< ref "..." >}} が約230箇所あった。Hugo の解決規則(ページからの相対、/ 始まりはルート基準、ファイル名が一意なら名前で解決)に合わせて、.md への相対リンクに変換した。
  • Docsy 固有の記法: {{% alert %}} を admonition(!!! note)に、{{< figure >}} を画像記法に変換した。末尾の「Child Pages」見出しは、Docsy が子ページの一覧を自動で出すための目印だったので、Zensical では不要として削除した。
  • 日本語見出しのアンカー: 既定のスラッグ化は日本語を落としてしまい、見出しへのリンクが壊れた。toc.slugify に pymdownx.slugs.slugify を設定して、日本語を保持するようにした。
  • リストのインデント: 一番手間がかかった。Zensical が使う Python-Markdown は、リストの入れ子に4スペースを要求する。Hugo(CommonMark)向けに2スペースで書いていたので、スクリプトで4スペースに変換した。
    • 段落の直後にリストを書くと、空行がないとリストとして認識されない。空行を補った。
    • 同じ階層で箇条書きと番号付きが続くと、空行を挟んでも1つのリストに連結される。HTML コメント(<!-- -->)を挟んで分けた。
    • 検証は、変換前を CommonMark、変換後を Python-Markdown でレンダリングして、ul/ol/li の構造を比較した。
    • 制約の詳細は、Python-Markdown にまとめた。
  • 元からあったリンク切れ: 変換後のビルドで、アンカーの警告が出た。元の時点で見出しが変わっていたもので、現在の見出しに直すか、対応する見出しがなければアンカーを削除した。

Zensical の設定まわりで試したこと・判断したこと

設定の一般的な情報は、Zensical のページにまとめた。ここには、今回の作業での経過を書く。

  • nav: 省略して、ディレクトリ階層から自動生成させる方法も試した。並び順はファイル名順、セクションのラベルはディレクトリ名(aws/ が Aws)になり、Hugo 時代の weight と linkTitle を再現できなかった。そのため、全ページを nav に明記する方にした。
  • 外部リンクを別タブで開きたくて、privacy プラグインのリンク属性の機能を使った。外部アセットのダウンロード機能は不要なので、無効にした。
  • uv init が書いた requires-python が実行環境のバージョンになっていたので、>=3.11 に直した。
  • zensical serve を起動したまま zensical build --clean を実行したら、キャッシュの競合で失敗した。--clean なしなら通った。

感想

  • 記法の差で一番効いたのは、リストのインデントだった。
  • ビルドが警告を出してくれるので、リンク切れを機械的に洗い出せたのが助かった。

手元のドキュメントをブラウザで閲覧するために VitePress を導入した

経緯

  • Git で管理しているドキュメント群(Markdown)を、ローカルのブラウザで閲覧したかった。対象は docs/ が中心で、スキルの定義や README.md など、docs/ の外にあるものも見られると良い。
  • 候補は VitePress と Zensical。Zensical は docs_dir にルート(.)を指定できず、複数ディレクトリも扱えないようなので、VitePress にした。
  • Node.js の実行環境は、仕事で使っている nodenv に合わせて、anyenv 経由で入れることにした。

実施した内容

  • anyenv と nodenv を導入して、Node.js の LTS(24.22.3)を入れた。バージョンは、リポジトリ直下の .node-version で固定した。
    • シェルの設定は、anyenv init - を評価する記述がすでにあったので、変更しなかった。
    • anyenv install --init が対話式の確認を求めるので、エージェントからは yes | を前置して実行した。
  • npm install -D vitepress して、設定ファイル(.vitepress/config.mts)を書いた。
    • srcDir はリポジトリのルートにして、README.md をトップページにした。作業用のディレクトリと、skills/ へのシンボリックリンクは、srcExclude で除外した。
    • リンク切れは、エラーにしない設定にした。
  • サイドバーを、ディレクトリ階層から自動で作るようにした。
  • 導入の手順と日々の運用の手順を、docs/ に文書化した。

詰まったところ

設定の詳細は、VitePress のページにまとめた。ここには、経過を書く。

  • 最初のビルドが、既存の Markdown で失敗した。
    • Hugo のショートコード({{< ref >}})の説明を書いたページが、Vue の式として解釈された。インラインコードに v-pre を付けて解決した。
    • テンプレートの {プレースホルダ} だけの行が、属性指定として解釈された。markdown.attrs.disable で無効にした。
  • サイドバーに、新しく作った Markdown が出なかった。サイドバーは起動時に1回だけ作られるためで、追加・削除を検知して設定ファイルを touch する Vite のプラグインで解決した。
  • ルート全体が対象なので、ファイル監視が重くなることを指摘された。vite.server.watch.ignored で、.git などを外した。
  • .claude/rules/ のような、ドットで始まるディレクトリは、build の出力に含まれない。開発サーバーでは開けるので、ローカルで見る分には足りると判断した。
  • npx vitepress --version が、バージョンの表示ではなく開発サーバーの起動になっていて、気づかずに2つ目のサーバーを起動してしまった。

感想

  • 設定を書いた後で、既存の文書のほうに引っかかる({{ }} や {...})のは、Markdown が Vue のテンプレートになる VitePress ならではだと思った。