はじめに #
Zensicalのサイト内検索やオフライン配布に関する設定について、備忘録として残します。
本記事の実行環境は以下の通りです。 パッケージ管理にはuvを使用します。
- Windows 10 Home 22H2
- uv 0.11.30
- Python 3.14
- Zensical 0.0.54
以下のコマンドでZensicalのインストールやプロジェクト作成をするものとします。
uv init --lib
uv add --dev zensical
uv run zensical new .詳細は以下のページを参照してください。
Zensicalに入門する
サイト名 #
ウェブサイトのタイトルは、zensical.tomlのproject.site_nameで設定します。
[project]
site_name = "Documentation"言語の設定 #
zensical.tomlのproject.theme.languageで言語を設定できます。
デフォルトは"en" （英語）です。
日本語にするには"ja"とします。
[project.theme]
language = "ja"日本語にすると、以下のようにウェブサイトの見た目などが変更されます。
- 検索ウィンドウの"Search"が「検索」になる
- ページ右側にある目次の"On this page"が「目次」になる
- HTMLファイルの言語設定 (lang) が"en"から"ja"になる
なお、言語設定を英語にした状態では日本語を検索できません。 日本語で記事を書く場合には、言語設定も日本語にした方がよいでしょう。
ファビコン #
サイトのファビコンを変更する場合、まず、ファビコンをdocsフォルダ内に置きます。
次に、zensical.tomlのproject.theme.faviconでパスを指定します。
[project.theme]
favicon = "images/favicon.png"サイトのオフライン配布 #
Zensicalで作成したウェブサイトを、ウェブサーバ経由で共有するのではなく、オフラインで配布する場合を考えます。
リンクの設定 #
デフォルトの設定では、サイト内のリンクから他のページをうまく開けません。
例えば、markdown.mdというファイルはビルドされるとmarkdown/index.htmlになります。
一方、他のHTMLファイルからのリンクはmarkdown/であるため、オフライン環境では正しく開けません。
そこで、zensical.tomlの[project]にuse_directory_urls = falseを追加します。
[project]
use_directory_urls = falseこの設定では、markdown.mdはビルドされるとmarkdown.htmlとなります。
また、他のHTMLファイルからのリンクもmarkdown.htmlになるため、ローカル環境でもうまく開けます。
なお、デフォルト設定で.htmlをリンクを含めないようにしているのは、将来的に拡張子が変わっても対応できるようにする近年のサイト設計思想（URL正規化）に基づくと思われます。
オフライン検索の有効化 #
デフォルトの設定では、ビルドしたHTMLファイルをオフラインで開くと、サイト内検索が無効になっています。
オフライン環境におけるサイト内検索を有効にするには、zensical.tomlに以下の設定を追加します。
[project.plugins.offline]
enabled = trueなお、この設定をすると、サイト内のリンクや生成されるHTMLファイル名についてもuse_directory_urls = falseとしたのと同じ効果が得られます。
フッターの設定 #
ソーシャルリンクの追加 #
フッターにSNSのリンクを追加する場合、zensical.tomlのproject.extra.socialに設定します。
iconにはアイコンの種類、linkにはリンク先を設定します。
X (旧Twitter) の場合、以下のようになります。
[[project.extra.social]]
icon = "fontawesome/brands/x-twitter"
link = "https://x.com/Helve64"アイコンにはGitHubやFacebookなども設定できます。 詳細は以下の公式リファレンスを参照してください。
Footer - Zensical Documentation
コピーライトの表示 #
フッターにコピーライトを表示するには、zensical.tomlのproject.copyrightに設定します。
[project]
copyright = "Copyright © 2026 Your name"Zensicalクレジットの非表示 #
フッターにある"Made with Zensical"を非表示にするには、zensical.tomlに以下の設定を追加します。
[project.extra]
generator = false
