Documentation

This page is for people who want to make changes to the Tazuna documentation site (the site you are reading now). The site is self-contained under docs/, built with mdBook + mdbook-i18n-helpers (gettext / PO files).

The sources are written in Japanese, and the English edition is derived via translation in po/en.po.

Directory Layout

docs/
├── book.toml            # mdBook の設定
├── src/                 # ドキュメント本体（日本語ソース）
│   ├── SUMMARY.md
│   ├── introduction.md
│   ├── concepts/
│   ├── getting-started/
│   ├── guides/
│   ├── operations/
│   ├── reference/
│   └── contributing/
├── po/
│   └── en.po            # 英語訳
├── theme/
│   └── fonts.css        # Google Fonts (M PLUS U) の上書き
├── static/
│   └── index.html       # /en/ と /ja/ をリンクする landing
└── THIRDPARTY.md        # フォント等のサードパーティ資産

docs/src/SUMMARY.md is the table of contents itself. When adding a new page, you also need to add one line here (mdBook builds even if the entry is missing, but the page will not appear on the site).

Required Tools

cargo install mdbook --locked
cargo install mdbook-i18n-helpers --locked

msgmerge (bundled with gettext) is used when updating the PO. On macOS, brew install gettext.

Preview Locally

Japanese (source language):

cd docs
mdbook serve --open

English:

cd docs
MDBOOK_BOOK__LANGUAGE=en mdbook serve --open

It rebuilds and reloads the browser on every file save.

Build Locally

cd docs
mdbook build -d book/ja
MDBOOK_BOOK__LANGUAGE=en mdbook build -d book/en
cp static/index.html book/index.html

Open book/index.html in your browser to switch between /ja/ and /en/ via links.

Updating the English Translation

After editing text under docs/src/, regenerate the PO template and merge into en.po.

cd docs
MDBOOK_OUTPUT__XGETTEXT__POT_FILE=messages.pot \
  mdbook build -d po --no-create-missing
msgmerge --update po/en.po po/messages.pot

Then open po/en.po and fill in msgstr for the added msgids. If the correspondence between the source (Japanese) and English translation breaks, blanks or missing items appear on the site, so the basic flow is to update en.po in the same PR as the source change.

Deployment

.github/workflows/docs.yaml handles publishing.

• Push to main: build the site and publish to GitHub Pages (actions/upload-pages-artifact + actions/deploy-pages).
• PR: build only. The output can be downloaded as a workflow-run artifact named github-pages. The recommended review process is to extract it locally and look at it.

Since GitHub Pages allows only one deployment per site, per-PR live preview URLs are intentionally not provided.

Third-party Assets

The site loads M PLUS U from Google Fonts at runtime. When adding new external assets such as fonts / icons / images, add license and attribution to docs/THIRDPARTY.md.

Documentation-side Conventions

The conventions that existing pages follow are noted here for reference.

• Tonal split: concepts are mostly prose (concepts/), guides are “purpose → prerequisites → procedure,” reference is field tables and code fragments.
• Anchor links: links into glossary or other references include the #anchor. Example: [Manifest type](../concepts/glossary.md#manifest-type).
• Code and identifiers: tazuna.yaml field names, CLI flags, and Go type names are wrapped in backticks.
• Language policy: sources are written in Japanese. Comments in code can be Japanese, but logs / error messages / CLI output are consistently in English (a project-wide policy).