Zensical のバージョンアップで確認することを整理して実際にベータ版 0.1.0 にアップグレードし 追加機能も取り入れてみた

Zensical のバージョンアップで確認することを整理して実際にベータ版 0.1.0 にアップグレードし 追加機能も取り入れてみた

Zensical のベータ版リリースを機に、Zensical のバージョン更新手順と検証方法を整理しました。リグレッションテスト、影響調査、新機能の活用までを体系化した運用改善の工夫をご紹介します。
2026.11.16

こんにちは。クラウド事業本部コンサルティング部の桑野です。

以前の記事では、Zensical への移行に向けた取り組みとして執筆者とサイト管理者の関心を分離するテンプレートをご紹介しました。

https://dev.classmethod.jp/articles/zensical-workspace-separation-template/

その後、弊社で運営しているナレッジサイト「Classmethod Cloud Guidebook(以下 CCG)」は、2026年11月9日に静的サイトジェネレーターを MkDocs から Zensical に正式に移行しました。

移行が終わり、今度は Zensical を使ったサイトを継続的に運用していく段階に入りました。
今回は Zensical のバージョンアップにあたって個人的に確認したい点と、更新前後を比較する手順をご紹介します。

Zensical がベータ版になったのでバージョンを上げたい

2026年11月6日(日本時間)に Zensical 0.1.0 がリリースされました。このリリースでアルファ版からベータ版へ移行しています。

公式のリリースノートによると、広く使われているプラグインへの対応も含めて MkDocs との互換性に残っていた主要な差分が解消されたそうです。開発チームは本番環境でも安定した動作を期待できる段階と位置付けています。ベータ期間は利用者のフィードバックを集めながら残る問題や API を改善していく方針です。

https://github.com/zensical/zensical/releases/tag/v0.1.0

CCG は MkDocs から移行したサイトなので、互換性の改善は今後の運用にも関わります。移行時のアルファ版から更新して不具合の修正を取り込みたいと思いました。

Zensical のロードマップには検索やナビゲーションの拡充など、今後の開発の方向性も示されています。

https://zensical.org/roadmap/

こうした展望に向けて Zensical が発展していくことにも期待しています。CCG の運用でもその進化を取り込んでいけるように継続的に更新していきたいと考え、今回のベータ版への移行をその機会としました。

今回整理したバージョンアップの手順と確認ポイント

今回の更新では既存のサイトを引き続き使えることを確かめたいと考えました。新しく使える機能の活用も含めて、気になった点と確認することを次のように整理しました。

# 気になった点 確認すること・そのための準備
1 今の設定やカスタマイズが新しいバージョンでも使えるか 対象リリースの変更内容をサイトの設定・実装と照らし合わせて修正が必要な箇所を洗い出す
2 更新後に見つけた違いが今回の更新によるものか判断できるか リグレッションテストの比較対象として更新前のビルド出力・画面・検索結果・警告を保存する
更新時には依存ファイルへの反映と実際のバージョンも確かめる
3 既存ページを閲覧できるか
検索やカスタマイズした機能が引き続き使えるか
更新後のビルド出力を比較する
画面表示・検索結果・独自の動作も確認する
4 何を確認できたか共有したい
更新で使えるようになった機能も知りたい
確認結果と注意点を PR に記録する
新機能の活用案もまとめる

今回は前回の記事で紹介したテンプレートを使って Zensical 0.0.46 から 0.1.0 への更新手順を整理しました。Docker コンテナ内で Zensical を動かしているため、依存パッケージの更新やビルドもコンテナ内で行う手順にしています。

1. リリースノートとサイトの実装を照らし合わせて影響を調べる

今回のように複数のリリースをまたいで更新する場合、目標バージョンのリリースノートだけでは途中のリリースで加わった変更を把握できません。更新範囲の変更を見落とさないように、現在のバージョンから目標バージョンまでのリリースノートを確認する必要があると考えました。

https://github.com/zensical/zensical/releases

リリースノートに変更が書かれていても、自分のサイトで対応が必要かは使っている設定やカスタマイズによって異なります。特に独自のカスタマイズは Zensical 本体の変更と噛み合わずに壊れてしまわないか気になります。画面の構造が変われば追加した CSS が意図した箇所に適用されなくなる可能性もあります。そのため変更内容とサイトの実装を照らし合わせて、更新後に確認する箇所を決めたいと考えました。

リリースノートで見るもの サイト側で照らし合わせるもの
Python の対応バージョンや配布形式 コンテナの実行環境
UI・テーマの更新 テンプレートのオーバーライドや追加した CSS
ページの読み込みや切り替えに関する変更 追加した JavaScript が動作するタイミング
ナビゲーションやタイトル解決の変更 サイドバーの表示名の決め方
設定の検証や Markdown 拡張の変更 利用中の設定や本文の記法

レビューする人が対応の要否を判断できるように、各変更が Zensical で構築した静的サイトにどう影響するかと判断の理由を調査結果に残す方針にしました。利用していない機能の変更など、対応が不要と判断したものについても理由を記載します。

調査結果は次のような情報を Issue にまとめることにしました。

更新対象
- 現在のバージョン → 目標バージョン

変更点ごとの影響
- 変更が入ったバージョンと変更内容
- 関係する設定やカスタマイズ
- 対応の要否と判断した理由
- 更新後に確認したい箇所

2. リグレッションテストの準備をしてからバージョンを上げる

Zensical の更新後も静的サイトの表示や既存の機能が正常に動くかを確認するため、リグレッションテストを行うことにしました。更新による影響を判断するには比較対象が必要だと考え、更新前のビルド出力や動作の確認結果を残しておく方針にしました。

テストでは同じ条件で更新前後を比較できるように準備します。本文の修正や新機能の導入も同時に行うと原因を判断しづらいと考え、テストが終わるまでは変更を分けることにしました。

  • 更新前のビルド出力・主要ページのスクリーンショット・検索結果を保存する
    ビルド時に警告が出た場合は内容を控える
  • 更新前後で比較するページ・表示条件・検索語を揃える
  • 本文の修正や新機能の導入は更新前後の比較を終えてから行う

スキルの手順と確認用スクリプトでは次の情報を保存するようにしています。ページの画像と検索結果はスクリプトで保存し、ビルド時の警告は発生した場合に作業者が内容を控える手順です。

記録するもの 保存する内容
ビルド出力 生成された HTML やアセットをディレクトリごとコピー
ページの表示 トップページ・表・コードブロックをライト/ダークそれぞれで撮影した画像
検索結果 同じ検索語で検索した画面の画像と、検索語ごとの件数・表示文言の抜粋を記録した JSON
ビルド時の警告 更新前から出ている警告の内容を控えたメモ

この準備を終えてから Zensical を目標のバージョンに更新します。今回は Docker コンテナ内で uv を使って依存パッケージを管理しているため、更新もコンテナ内で行います。最後にビルドに使う Zensical が目標のバージョンになっていることを確かめ、更新後の比較に進む手順にしました。

3. リグレッションテストで表示や既存の機能への影響を確認する

ビルドが成功しても利用者が問題なく読めるとは限りません。HTML が生成されていても表示が崩れる可能性があります。検索や追加した JavaScript の動作もビルド結果だけでは判断できません。

CCG は必要な情報を探して読むためのサイトです。ページの生成だけでなく検索やページ内の操作まで確かめたいと考え、出力とブラウザ上の動作を分けて確認する方針にしました。

# 確認項目 確認の方法
3-1 ビルド出力を比較する ページの追加・削除やサイドバーの表示名を比較する
本文などの HTML の差分も調べる
3-2 画面の表示を比較する 同じページのライト/ダークのスクリーンショットを見比べる
3-3 検索結果を比較する 同じ検索語の件数や検索結果を見比べる
3-4 カスタマイズした機能を確認する 直接表示とリンクからの移動の両方でテーブルソートの動作を確認する

3-1. ビルド出力を比較する

ビルド出力をそのまま比較するとアセット名のハッシュやバージョン表記も差分に含まれます。それらに埋もれて本文への影響を見落とさないように、正規化して比較する Python スクリプトを用意しました。多数のページに共通する差分と一部のページだけに出る差分を分けて見ることで、詳しく調べる箇所を絞る手掛かりにしています。

https://github.com/k-kuwan0/zensical-workspace-separation-template/blob/feature/zensical-0.1.0/ssg/scripts/compare_build.py

当時の実行ログの一部です。ページ数とサイドバーの項目数は変わらず、HTML には全9ページで差分が出ていました。この結果から差分の内容を調べていきます。

## 1. ファイル一覧
ページ数: 9 -> 9
  削除: objects.inv

## 2. サイドバーの表示名
項目数: 13 -> 13
  差分なし

## 3. HTML 差分(正規化後)
差分のあるページ: 9 / 9

スクリプトは差分を集計しますが、その変更がサイトに影響するかは内容を読んで判断します。また HTML の行の並び順だけが変わった場合は検出できないため、表示順への影響が気になる箇所はブラウザでも確認する方針にしました。

3-2. 画面の表示を比較する

画面と検索結果は JavaScript で作成したスクリプトからヘッドレス Chrome を操作して記録します。独自の CSS が片方の表示モードでだけ崩れることも考えられるため、同じページをライト/ダークで見比べる手順にしました。

https://github.com/k-kuwan0/zensical-workspace-separation-template/blob/feature/zensical-0.1.0/ssg/scripts/browser_check.mjs

トップページのスクリーンショットです。更新前の 0.0.46 と更新後の 0.1.0 を並べてヘッダーやサイドバー、本文の配置を見比べます。

更新前:0.0.46 更新後:0.1.0

このスクリプトは撮影までを行い、表示崩れの有無は自動判定しません。保存した画像を見比べて文字の重なりや表のはみ出しなどを確認します。

3-3. 検索結果を比較する

検索では同じ語を使って結果を比較することにしました。検索の改善によって件数が増える場合もあるため、件数の増減だけで判断するのは難しいと考えました。スクリプトで記録した件数と検索画面を見比べ、検索語に関連する内容が表示されているかも確認する方針です。

検索語にサイドバーを指定した場合は、更新前の1件から更新後は5件に増えていました。検索結果の画像も保存することで件数だけでなく表示された内容を確認できます。

更新前:0.0.46 更新後:0.1.0

現在は画面の確認結果を文章で PR にまとめています。撮影した画像も PR から参照できるように保存・共有する仕組みは検討中です。レビューする人も実際の画面を見ながら確認できる形にしたいと考えています。

3-4. カスタマイズした機能を確認する

毎回すべての画面や操作を確認するのは負担が大きいと考え、今回は独自にカスタマイズした機能を中心に確認することにしました。リリースノートからほかの箇所への影響が分かった場合は確認対象を追加します。

たとえばテーブルソートは、表示した表に対してソート機能を有効にする処理が必要です。サイト内の移動でページ全体を読み直さない場合、移動先の表にその処理が実行されずソートが使えなくなる可能性があります。そのため URL を直接開く場合に加えて、サイト内のリンクから移動した後もソートできるか確かめたいと考えました。

確認する場面 期待する動作
URL から直接表示した場合 指定した列の値に従って行が並び替わる
サイドバーのリンクから移動した場合 直接表示した場合と同じように行が並び替わる

現在のスクリプトではソート後に並び順を示す情報が HTML に付くかを確認しています。実際の行の並びについてはスクリーンショットを目視で確認して補うことにしました。代表として設定ページの表を一つ選び、行が並び替わっていることを確認できれば十分ではないかと考えています。

次の画像は項目列でソートした後の画面です。赤枠のソートアイコンと、項目名の昇順に並んだ行を確認できます。

4. 確認結果と新しく使える機能をまとめる

確認を終えた後は結果を PR にまとめます。レビューする人にも Zensical の更新を取り込んでよいか判断してもらうため、確認した内容と結果を具体的に残したいと考えました。画面や検索結果に違いがあれば、その違いを許容できると判断した理由も記載する方針です。

PR には次の情報がまとまっているとレビューしやすいと考えました。

変更内容
- 更新前後のバージョン
- 更新に伴って変更した設定や実装

確認結果
- 確認した項目と結果
- 更新前後で変わった点と影響の判断
- 未確認の項目

注意点
- 残っている問題や運用上の注意

新機能の活用案
- 新しく使える機能
- サイトの運用にどう役立つか

確認結果にはスクリプトで確認できた範囲や目視で確認した内容も含めます。未確認の項目を残しておけば、レビュー時に追加の確認が必要かを相談しやすいと考えました。

新機能についても影響調査で得た情報を今後の改善に役立てたいと思いました。機能名を並べるだけでは導入の判断が難しいので、Zensical で構築した静的サイトの運用にどう使えるかまで整理しています。たとえば下書きを本番出力から除外する機能なら、執筆途中のページを誤って公開することを防ぐ用途が考えられます。

新機能の活用案は更新と同じ PR で共有し、導入は別の変更として検討する形にしました。更新自体の影響を確認してから導入することで、不具合があった際も原因を判断しやすくしたいと考えています。

確認手順を Claude Code のスキルにまとめる

Zensical のバージョンアップは今後も継続的に繰り返す作業です。毎回確認手順を組み立て直す負担を減らすために今回整理した手順を次回以降も使いたいと考えました。そこで一連の手順を zensical-upgrade という Claude Code のスキルにまとめました。

/zensical-upgrade 0.1.0

目標バージョンを指定すると Claude Code が影響調査や更新前後の比較を進めます。その結果を PR 本文にまとめるところまで手順に含めています。影響調査後や Issue・PR の作成前には確認を挟むようにしています。

ファイル 役割
.claude/skills/zensical-upgrade/SKILL.md 調査・更新・比較・記録の手順と判断の観点
Python スクリプト 更新前後のビルド出力の比較
JavaScript で作成したスクリプト 画面・検索・追加した JavaScript の確認材料の記録
ssg/scripts/browser_check.config.json 確認するページや検索語の指定

比較結果には確認できた範囲と未確認の項目を残すようにしています。今後カスタマイズを追加した際には確認対象も見直していくと良いと考えています。

このスキルを使ったバージョンアップで実際に作成した Issue と PR です。Issue には事前の影響調査を、PR には更新内容や確認結果と新機能の活用案をまとめています。

影響調査をまとめた Issue
https://github.com/k-kuwan0/zensical-workspace-separation-template/issues/1

更新内容と確認結果をまとめた PR
https://github.com/k-kuwan0/zensical-workspace-separation-template/pull/2

PR で紹介された機能を実際に導入してみた

PR にまとめられた新機能の候補を見て、下書きを本番サイトの出力から除外できる draft_docs が気になりました。執筆途中のページをリポジトリで共有しながら公開を防ぐ用途に使えそうな機能だと感じました。

そこで前回紹介したテンプレートに draft_docs を導入しました。下書きへのリンクが残ったまま公開されることも防ぐために strict をあわせて設定しています。執筆時点ではマージ予定の変更です。

下書きを本番のビルドから外す — Issue
https://github.com/k-kuwan0/zensical-workspace-separation-template/issues/3

draft_docs は 0.0.70 で追加された機能です。設定ファイルからの strict の指定は 0.0.53 で追加されています。今回の 0.0.46 から 0.1.0 への更新で両方を利用できるようになりました。

設定の追加とあわせて公開時の手順も整理しました。

# 見直したこと 対応
1 下書きの公開範囲を分ける draft_docs でプレビューには表示しながら本番出力から除外する
2 下書きへのリンクが残ったままの公開を防ぐ strict で警告が出たビルドを失敗させる
3 下書きを公開する手順を揃える ファイルの移動と目次への追加を執筆者向けに案内する

1. 下書きの公開範囲を分ける

draft_docs を使うと下書きをプレビューで確認しながら本番用のビルドから除外することができます。
今回は docs/drafts/ 以下のページを対象にしました。

ssg/zensical.toml に追加した設定です。strict は次の項目で説明するリンク切れへの対策として設定しています。

[project]
draft_docs = """
/drafts/
"""

strict = true

この設定では zensical serve で起動したプレビューに docs/drafts/ 以下のページが含まれます。ページには DRAFT バッジも表示されます。

今回の構成では下書きをサイドバーに載せていないため URL を直接指定して開きます。たとえば docs/drafts/sample.md は http://localhost:8001/drafts/sample/ で確認できます。

次の画像は下書きのサンプルをプレビューした画面です。ページタイトルの上に DRAFT バッジが表示されています。

zensical build では下書きの HTML は生成されず、検索インデックスや sitemap.xml にも含まれません。ローカルで実行した場合も zensical build の出力からは除外されます。

draft_docs を設定しない場合は目次に載せていないページも本番出力に含まれます。確認用のページでも HTML や検索インデックスが生成されていました。目次から外すだけでは検索や URL の直接入力で閲覧できるため、下書きの公開を防ぐには draft_docs の設定が必要だと考えました。

https://zensical.org/docs/setup/basics/#draft_docs

なお下書きのファイルはリポジトリに残るため、リポジトリの閲覧者とは共有される運用です。

2. 下書きへのリンクが残ったままの公開を防ぐ

draft_docs で下書きを本番出力から除外しても、目次や本文に書いた下書きへのリンクは残ります。たとえば公開用の場所へ移す前に下書きを目次へ追加すると、サイドバーにはリンクがあるのにリンク先のページは出力されない状態になります。

strict を有効にする前の検証では警告が出てもビルドは成功しました。サイドバーには none という項目が表示されてリンク先は 404 になりました。ビルドの成功だけを見て公開してしまうと、この問題に気づきにくいと感じました。

そこで警告が残っている場合はビルドを失敗させる strict = true を設定しました。下書きへのリンクを検出したときの違いは次のとおりです。

設定 警告が出た場合のビルド結果
strict 無効 警告を表示してもビルドは成功する
strict 有効 警告を表示してビルドを失敗させる

設定後にビルドが止まることも確かめたかったので、docs/sitemap.md のガイド欄に下書きへのリンクを残した状態で試しました。Zensical 0.1.0 で zensical build を実行した際のログを抜粋します。

Build started
Warning: page does not exist
    ╭─[ sitemap.md:24:15 ]
    │
 24 │ - [サンプル(下書き)](drafts/sample.md)
    │                        ────────┬───────
    │                                ╰───────── page does not exist
────╯
1 issue found
Traceback (most recent call last):
…(途中省略)
RuntimeError: Aborted because --strict flag is set

本番出力に含まれない drafts/sample.md へのリンクが警告の対象になりました。今回は目次本文のリンクに対する警告が1件出ており、サイドバーの設定からは警告が出ていません。

strict が有効な状態ではログの最後に中断のメッセージが表示されました。終了コードも 1 となり、警告だけで終わらずビルドが失敗することを確認できました。

この結果を CI でも公開前の確認に使いたいと考えました。ビルドの成功を公開の条件にしておけば、ログの警告を見落とした場合もリンク切れを残したまま公開することを防げます。

strict は実行時のオプションでも指定できます。今回はプロジェクトの設定ファイルに記載したため、ローカルと CI の両方で通常のビルド時に適用されます。

https://zensical.org/docs/setup/validation/#strict-mode

ただし strict は下書きへのリンク専用の設定ではありません。ほかの警告もビルド失敗の対象になるため、導入時には既存の警告も確認する方針にしました。警告が出た場合は対象のファイルを確認し、リンクの修正や公開先へのファイル移動で原因を解消してから再度ビルドする流れです。

3. 下書きを公開する手順を揃える

設定を変えるだけでは執筆者がどの順番で公開すればよいか迷うと思いました。下書きのまま目次へ追加するとビルドが失敗するため、公開時には次の順序で変更するよう案内しています。

  1. 下書きを docs/drafts/ から docs/guides/ などの公開用の場所へ移す
  2. 移動先のページを目次の docs/sitemap.md に追加する

この手順と下書きの書き方を docs/drafts/README.md にまとめました。執筆者が確認できるサンプルページも用意しています。

次の画像は README をプレビューで表示したものです。下書きの作成から公開までの手順を確認できます。

今回の更新では新機能を使って下書きの出力を制御するだけでなく、執筆から公開までの手順も整理できました。

Classmethod Cloud Guidebook とデモサイトのご紹介

今回の取り組みの背景となった CCG はクラスメソッドメンバーズのお客様向けに無償で提供しているナレッジサイトです。AWS 利用ガイドラインのサンプルやマルチアカウント管理、セキュリティなどの知見を体系的にまとめています。

クラスメソッドメンバーズをご利用の方はメンバーズポータルの「Cloud Guidebook」からアクセスできます。詳しい使い方は以下の記事でご紹介しています。

https://dev.classmethod.jp/articles/how-to-use-ccg/

メンバーズ未加入の方も公開デモサイトで一部のコンテンツをご覧いただけます。CCG で提供している情報や構成を知りたい方はぜひご覧ください。

https://demo.guidebook.classmethod.net/

最後に

Zensical のバージョンアップにあたって確認したい点と更新前後を比較する手順を整理しました。既存の表示や機能への影響を調べるだけでなく、新しく使える機能を運用改善につなげるところまで考える機会になりました。

バージョンアップは今後も繰り返す作業なので今回の手順を Claude Code のスキルにまとめました。今後もサイトの構成やカスタマイズに合わせて確認項目を見直しながら使っていきたいと考えています。

Zensical をはじめとする静的サイトの更新手順を考える際の参考になれば嬉しいです。

最後までご覧いただきありがとうございました。

この記事をシェアする

関連記事