使い方#

このページの内容は英語版と同じです。ここに出てくるオプションは、既定値つきでオプションに一覧があります。

はじめる#

npx tsumugu dev docs

docs/ ディレクトリを localhost で配信し、URL を表示します。設定ファイルは存在せず、必要もありません。ルートは指定したディレクトリ（慣例では ./docs）で、それ以外はすべてファイルから導かれます。

最初の実行で知っておく価値のあるフラグが 1 つだけあります。Tsumugu に渡したドキュメントはコードではなく内容として扱われるので、スクリプトは動かず、MDX のコンポーネントはソースとして表示されます。そのディレクトリが自分のもので、動かしたい場合は --trust を付けます。

npx tsumugu dev docs --trust

信頼に関する設定はこのフラグだけです。何が対象になるかはこのあとで説明します。

書く#

ルーティングはファイルシステムをそのまま写し、3 つの形式が同じパイプラインを通ります。

docs/
├── index.md          →  /            見出しがサイト名になります
├── guide/
│   ├── index.md      →  /guide       セクション自身のページ
│   └── setup.md      →  /guide/setup
├── api.html          →  /api         HTML は出力ではなく入力です
├── notes.mdx         →  /notes       MDX はパースし、--trust で実行します
└── images/x.svg      →  文書の隣からそのまま配信

文書ごとの設定は front matter がすべてです。

---
title: セットアップ # 省略時は最初の見出し、次にファイル名
description: 一文の説明。 # 一覧・llms.txt・検索に表示
order: 2 # 兄弟間での並び順
hidden: true # どこにも載せないが、配信はされる
---

hiden のようなタイプミスには「もしかして hidden?」という警告が出ます。MDX の式やコンポーネントは実行されず、書かれたとおりに表示され、HTML の <script> は取り除かれます。この扱いを選んだ理由は、 ADR 6 に記録されています。 Tsumugu に渡した内容はコードではないので、実行しません。

ロケールを分ける#

1 つのサイトに翻訳したドキュメントを置く場合は、ロケールのディレクトリを明示します。

npx tsumugu dev docs --locales ja,en-US

docs/
├── greeting.md       →  /greeting    共通スコープ
├── ja/
│   └── guide.md      →  /ja/guide    日本語スコープ
└── en-US/
    └── guide.md      →  /en-US/guide 米国英語スコープ

/ のナビゲーションと検索には greeting.md が含まれ、ja/ と en-US/ 以下は含まれません。/ja には ja/ 以下だけ、/en-US には en-US/ 以下だけが含まれます。documents.json、llms.txt、search.json もスコープごとに生成され、ルートの sitemap.xml はサイト全体を含みます。

ロケール名には Unicode のロケール識別子を使います。Tsumugu は名前を正規化するため、en-us は en-US というディレクトリを選びます。指定したディレクトリが存在しない場合や、正規化後に同じロケールになる名前を重複して指定した場合は、配信やビルドを始める前に停止します。--lang fr は共通スコープの HTML 言語を設定します。ロケールのスコープでは、そのロケール自身が使われます。--locales を付けなければ、従来どおりすべてのディレクトリを通常のルートとして扱います。

言語の切り替えは、自分で書くリンクです。どのページがどのページの対訳なのかを知っているのは書いた人だけだからです。このサイトは --locales en,ja でビルドしています。いま読んでいるガイドが docs/ja/、その対訳が docs/en/ で、各ページの冒頭に相手へのリンクがあり、/ の共通スコープには片方の言語しかない設計資料が置かれています。

図を描く#

```mermaid と書いたコードブロックは、ページを組み立てる間に図になります。読者に届くのは SVG だけでスクリプトはなく、図はページの明暗に合わせて色を変え、図の中の文字は選択も検索もできます。

Tsumugu は Mermaid を動かすのではなく自分で描くので、読める記法は部分集合です。どこまで描けるかを書いていない部分集合は当てもの遊びになるため、明記します。

図	対応している記法
`graph`, `flowchart`	向きは `TD`、`TB`、`LR`、`RL`、`BT`。形は `A[四角]`、`A(角丸)`、`A{判断}`、`A((円))`。線は `-->`、`---`、`-.->`、`==>` で、いずれも `\|ラベル\|` を付けられます。
`sequenceDiagram`	`participant` と `actor`（`as` で別名）。メッセージは `->>`、`-->>`、`->`、`-->`、`-x`、`-)`。`Note over` / `left of` / `right of`。自分宛のメッセージ。

これ以外——class、state、gantt、pie、ER、journey、mindmap などの図種と、 subgraph、classDef、style、click、%%{init}%%——はコードブロックのまま残り、何を描けなかったかを名指しした警告が出ます。描けない図がページごと巻き添えにすることはなく、黙って半分だけ描かれることもありません。

2 行だけ書く価値があります。accTitle が図の名前、accDescr が図の説明で、どちらもスクリーンリーダーの読者に届きます。

graph LR
  accTitle: 文書がページになるまで
  accDescr: 走査からレンダラーへ、最後にテーマが来ます。
  A[走査] --> B[レンダラー]

書かなければ、Tsumugu が図の向きと線のつながりから説明を組み立てます。嘘はつきませんが、自分で書いた一文よりは伝わりません。

そう決めた理由と、サーバー側で Mermaid を動かす道を捨てた実測は ADR 9（英語）にあります。

API 記述を配信する#

OpenAPI の記述は HTTP インターフェースの原本なので、Tsumugu はそれをリンク先のファイルではなく文書として扱います。名前を付ければページになります。

docs/
├── api.openapi.yaml   →  /api        記述がそのままページになる
├── openapi.yaml       →  /openapi    この名前でもよい
├── config.json        →  これまでどおりファイルとして配信
└── data.yaml          →  これまでどおりファイルとして配信

オプトインは名前です。ページになるのは *.openapi.json、*.openapi.yaml、 *.openapi.yml と openapi.* という名前だけなので、lock ファイルもフィクスチャも設定ファイルも、これまでのままです。

ページの構造は記述自身の構造です。info.title がページ、tag が節、operation はメソッドとパスを見出しにした小節になります。つまり operation ごとにアンカーがあり、サイドバーに載り、検索・documents.json・llms.txt にも出てきます。

# Pet Store              info.title
## Pets                  tag
### GET /pets            operation。アンカーが付く
#### Parameters          表: 名前・場所・型・必須・説明
#### Responses           表: ステータス・説明・content type
## Other operations      tag が付いていない operation

読めるのは OpenAPI 3.0 と 3.1 です。記述の中の $ref は使われている場所で解決するので、共有スキーマは参照ではなく中身が出ます。自分自身を参照するスキーマは一度だけ展開し、その先は名前を表示します。外部ファイルへの参照、存在しない参照、 Swagger 2.0 の記述は、それぞれどうすればよいかを言う警告を出し、それでもページは描かれます。

このために読者へ送るものは何もありません。ビューアもスクリプトもネットワークアクセスもなしです。意図的に無いのは「試してみる」コンソールで、これは両方を必要とします。理由は ADR 10（英語）にあります。

中身が自分のものであるとき#

ドキュメント自体がコードであることもあります。<canvas> のデモ、動く実例、コンポーネントで組み立てた MDX。--trust を渡すと、 Tsumugu はそれを実行します。

tsumugu dev docs --trust

このフラグは「このディレクトリは自分のものだ」という宣言です。有効な間は、Tsumugu が意味を持てないマークアップは書かれたままページに出て、スクリプトは動き — インラインはハッシュで、ファイルは 'self' で許可され、外部オリジンは決して許可されません — .mdx はページを組み立てる間に実行されます。出力は静的な HTML なので、検索も各種エクスポートもそのまま読めます。実行できなかったファイルはその旨をページに表示し、ソース表示に戻ります。壊れた 1 ファイルがサイト全体を巻き込むことはありません。

自分で書いたものでない内容には、このフラグを付けないでください。理由は ADR 7 にあります。

この使い方で知っておくべきことが 2 つあります。.mdx の中に直接書いた <script> は動きません。MDX は script の中身をコードではなく文書の内容として読むためです。文書の隣にファイルを置き、<script src="./demo.js"> で読み込んでください。また、再ビルドの単位は文書なので、import しているコンポーネントを編集した場合は今のところ再起動が必要です。

Tsumugu 自身のアーキテクチャのページがこの書き方です。図は本文が説明しているのと同じリストから計算されています。動く例として、リポジトリの docs/designs/architecture/index.mdx と docs/.components/ を見てください。ドットで始まるディレクトリにしてあるのは意図的で、Tsumugu はドットファイルを配信しないため、そこに置いたビルド入力が文書の隣に公開されることはありません。

書いている間#

watch モードは既定で有効です。保存すると変更分だけが再ビルドされ、開いているページは自動で再読み込みされます。問題はそれが属するページの上に表示されます。壊れた内部リンク、存在しないアンカー、パースできない front matter には、ファイルと行番号が付きます。再ビルド全体が失敗しても、最後に成功した版を配信し続けます。

読者には、入力に応じてセクション単位でランキングされる検索、コードブロックのコピーボタン、見出しアンカー、読んでいる位置に追従する目次が提供されます。すべて段階的です。JavaScript がなければ検索フォームは本物のページに送信され、それ以外は最初からサーバーレンダリングです。

公開する#

npx tsumugu build docs --out dist --origin https://docs.example.com

dist/ はクリーン URL の静的サイトです。たとえば /guide/setup は guide/setup/index.html になります。ページと同じ文書から生成された documents.json、llms.txt、search.json、sitemap.xml も含まれます。ファイルを配れる場所ならどこでもホストできます。build でも dev と同じ --locales と --lang を使えます。

GitHub Pages#

プロジェクトサイトは /リポジトリ名/ 配下で配信されるため、--base を渡します。

npx tsumugu build docs --out dist \
  --origin https://your-name.github.io --base /your-repo

ワークフローで自動化できます。このリポジトリ自身のドキュメントが、まさにこの形（.github/workflows/pages.yml）で公開されています。設定は一度だけ: Settings → Pages → Source → GitHub Actions。

構成を変える#

CLI は、差し替え可能なレンダラー、トランスフォーマー、テーマを組み合わせています。差し替える場合は、CLI と同じ API を使う小さなスクリプトです。Composition（英語）を参照してください。