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 で管理する。
- 設定などの知見は、Zensical のページにまとめた。
実施した内容¶
- 履歴:
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 にした。- 調べた内容は、Zensical のページに書いた。
- 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で無効にした。
- Hugo のショートコード(
- サイドバーに、新しく作った Markdown が出なかった。サイドバーは起動時に1回だけ作られるためで、追加・削除を検知して設定ファイルを touch する Vite のプラグインで解決した。
- ルート全体が対象なので、ファイル監視が重くなることを指摘された。
vite.server.watch.ignoredで、.gitなどを外した。 .claude/rules/のような、ドットで始まるディレクトリは、buildの出力に含まれない。開発サーバーでは開けるので、ローカルで見る分には足りると判断した。npx vitepress --versionが、バージョンの表示ではなく開発サーバーの起動になっていて、気づかずに2つ目のサーバーを起動してしまった。
感想¶
- 設定を書いた後で、既存の文書のほうに引っかかる(
{{ }}や{...})のは、Markdown が Vue のテンプレートになる VitePress ならではだと思った。