Zensical

技術ドキュメント向けのスケーラブルなオープンソース静的サイトジェネレーター

Zensical とは

Zensical は、Material for MkDocs の作者によって開発された次世代の静的サイトジェネレーターです。 プロジェクトドキュメントの作成を効率化し、執筆作業に集中できる環境を提供します。

「Batteries included, easy to use, with powerful customization options」 ――すぐに使える充実した機能、簡単な操作性、そして強力なカスタマイズ性を兼ね備えています。

主な特徴

Markdown ベース

Markdown でドキュメントを記述し、美しい静的サイトとしてビルドします。コードブロック、数式、図表などの拡張記法にも対応しています。

多言語対応

60 以上の言語をサポート。日本語を含む多言語ドキュメントサイトを容易に構築できます。

テーマ & カラースキーム

ライトモード・ダークモードの切替に対応。カラーパレットやフォントも柔軟にカスタマイズできます。

高度なナビゲーション

インスタントナビゲーション、タブ、セクション、パンくずリスト、目次など豊富なナビゲーション機能を搭載しています。

全文検索

ビルトインの検索機能により、ドキュメント全体から素早く情報を見つけることができます。検索結果のハイライト表示にも対応しています。

拡張性

プラグインや Markdown 拡張により機能を追加可能。Mermaid 図表、コードアノテーション、コンテンツタブなど多彩な表現が可能です。

セットアップ

前提条件

pip でインストール

# 仮想環境を作成・有効化
python -m venv .venv
source .venv/bin/activate

# Zensical をインストール
pip install zensical

uv でインストール

# 開発依存としてインストール
uv add --dev zensical
Docker: Docker を使用したインストールも可能です。詳細は 公式ドキュメントを参照してください。

設定ファイル（zensical.toml）

プロジェクトのルートに zensical.toml を配置し、サイト名・ナビゲーション・テーマなどを TOML 形式で定義します。 

[project]
site_name = "My Documentation"
site_url  = "https://example.com/"

[project.theme]
language = "ja"
features = [
    "navigation.tabs",
    "navigation.instant",
    "search.highlight",
    "content.code.copy",
]

[[project.theme.palette]]
scheme = "default"

[[project.theme.palette]]
scheme = "slate"

主な機能一覧

カテゴリ 機能 説明
ナビゲーション インスタントナビゲーション ページ遷移を XHR で処理し、高速に切り替え
ナビゲーション タブ & セクション トップレベルセクションをタブ形式で表示
コンテンツ コードアノテーション コードブロックに注釈アイコンとツールチップを追加
コンテンツ コピーボタン コードブロックにワンクリックコピー機能を追加
コンテンツ コンテンツタブ 複数言語のサンプルをタブで切替表示
コンテンツ Mermaid 図表 テキストからフローチャートやシーケンス図を生成
テーマ ダークモード ライト / ダークの切替をユーザーに提供
検索 ハイライト検索 検索結果のキーワードをページ上でハイライト表示

Material for MkDocs との関係

Zensical は Material for MkDocs の作者が手がけたプロジェクトであり、同じ設計哲学を継承しています。 Material for MkDocs で培われたテーマ・機能を基盤としつつ、よりスケーラブルで柔軟なアーキテクチャへと進化しています。

関連リンク