Zensicalに入門する

はじめに

#

Zensicalを使ってサイトのプレビュー表示およびサイトのファイルを生成するまでの手順を備忘録として残します。

ZensicalはMarkdownファイルなどからウェブサイトを構築する静的サイトジェネレータ (SSG) です。 ZensicalはPythonのパッケージとして提供されているため、通常はPythonの仮想環境にインストールして使用します。

また、本記事の実行環境は以下の通りです。 パッケージ管理にはuvを使用します。

• Windows 10 Home 22H2
• uv 0.11.30
• Python 3.14
• Zensical 0.0.54

仮想環境の構築とインストール

#

まず、uvで仮想環境を構築し、Zensicalをインストールします。

uv init --lib
uv add --dev zensical

uv initに--libを付け、src-layoutとします。 また、--devオプションにより、Zensicalを開発用パッケージとしてインストールします。

インストール完了後、以下のコマンドを実行してZensicalのヘルプが表示されることを確認します。

> uv run zensical --help
Usage: zensical [OPTIONS] COMMAND [ARGS]...

  Zensical - A modern static site generator.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  build  Build a project.
  new    Create a new template project in the current or given directory.
  serve  Build and serve a project.

Zensicalの基本的なコマンドは以下の3つとシンプルです。

• build: ウェブサイト公開用のHTMLファイルなどを作成する。
• new: 新しいZensicalプロジェクトを作成する。
• serve: ウェブサイト公開用のHTMLファイルなどを作成し、プレビュー用のHTMLサーバをローカルで起動する。

Zensicalプロジェクトの作成

#

以下のコマンドでZensicalプロジェクトを作成できます。

uv run zensical new [DIRECTORY]

ここでは、リポジトリのルートディレクトリで以下を実行します。

uv run zensical new .

実行後、以下の通りファイルが作成されます。

.
├─ .github/workflows
│  └─ docs.yml
├─ docs/
│  ├─ index.md
│  └─ markdown.md
└─ zensical.toml

docsフォルダの中に、サンプルの記事となるMarkdownファイルが生成されています。 また、zensical.tomlはZensicalの設定ファイルです。

サイトのプレビュー

#

サイトのプレビューを表示するには、リポジトリのルートディレクトリで以下を実行します。

uv run zensical serve

続いて http://localhost:8000 をウェブブラウザで開き、以下のページが表示されることを確認します。

また、ビルドされたHTMLファイルなどは、以下のようにルートディレクトリのsiteフォルダ内に出力されます。 ウェブサイトとして公開する場合、このsiteフォルダをウェブサーバにそのままアップロードします。

site
├─ assets/
├─ markdown/
├─ 404.html
├─ index.html
├─ objects.inv
├─ search.json
└─ sitemap.xml

また、プレビューせずにHTMLファイルなどの生成物だけ欲しい場合、以下のコマンドを実行します。

uv run zensical build