authoring

執筆

Jotdown を使うプロジェクトのドキュメントの書き方です。プロジェクトはコンテンツと 1 つの設定ファイルで構成され、エージェントがコードとあわせて読むコンテキストです。それをコンパイルするフレームワーク、編集するスタジオ、読者に提供するサイトは別の場所にあり、ここではそれらに手を加える必要はありません。

コンテンツプロジェクト

<repository>/
├── .jotdown/                   ← Jotdown's own folder, committed
│   ├── config.json             ← title, repository, content, logo, theme
│   └── vercel.json             ← a host's files, when the docs are published
└── <content>/                  ← the repository root itself when content is unset
    ├── docs/                   ← all pages
    │   ├── index.mdx           ← landing page, served at /
    │   ├── meta.json           ← the main section's title, blurb and order
    │   ├── moved.json          ← forwarding record for moved pages
    │   ├── _uploads/           ← images, files, whiteboards, fonts
    │   └── <section>/
    │       ├── meta.json       ← the section's label, description and order
    │       ├── index.mdx       ← section landing page
    │       └── <document>.mdx  ← documents

プロジェクトは 1 つのリポジトリで、設定ファイルは常に .jotdown/config.json にあります。.jotdown/ は Jotdown のフォルダーで、.github/ と同じようにコミットします。ここには設定ファイルと、ドキュメントを公開する際のホスト用ファイルが置かれます。これらが、アプリ独自のルートにある vercel.json と競合することはありません。ページはリポジトリのルート、または "content": "handbook" のように content で指定したフォルダーに置きます。1 つのリポジトリに保持できるプロジェクトは 1 つです。

スタジオでは owner/repo の下にプロジェクトが表示されるため、/you/notes/guides/sections は you/notes の docs/guides/sections.mdx ページを指し、そのリンクを開くと、リポジトリを閲覧できる人なら誰でも同じページが表示されます。/ はスタジオのウェルカムページです。公開サイトでは同じページが /guides/sections に表示されるため、ページ同士はサイトのルートを基準にリンクでき、スタジオがそのリンクをプロジェクトの下に移動します。詳しくはADR 0017をご覧ください。

.jotdown/config.json はプレーンデータなので、プロジェクト内でコードが実行されることはありません。

{
  "version": 1,
  "title": "Engineering handbook",
  "description": "How our team builds and operates software",
  "repository": "https://github.com/your-org/handbook",
  "url": "https://handbook.your-org.com/docs",
  "branch": "main",
  "content": "apps/docs",
  "logo": { "alt": "Handbook", "src": "/uploads/logo.svg" },
  "favicon": "/uploads/favicon.png",
  "theme": {
    "light": { "background": "#ffffff", "foreground": "#1c1a33", "primary": "#433a86" },
    "dark": { "background": "#0d0c1b", "foreground": "#ecebf5", "primary": "#b9acff" },
    "sections": { "orders-api": "chart-2" },
    "fonts": { "sans": { "family": "Geist", "src": "/uploads/fonts/geist.woff2" } }
  }
}

すべてのフィールドは省略可能ですが、ファイルが存在する場合に限り、スタジオの切り替えメニューにリポジトリが表示されます。設定ファイルがないプロジェクトでは、リポジトリ名がタイトルになります。content は docs/ を含むフォルダーです。uploads を指定すると、アップロードファイルの保存先が content の別のフォルダーに変更されます。未指定の場合は docs/_uploads です。branch はスタジオでの編集内容の反映先です。未指定の場合はデフォルトブランチになります。url は読者向けに公開サイトをホストする場所で、ドメインとベースパスを指定します。これにより、スタジオからページの読者向けリンクを共有できます。favicon は公開サイトとローカルプレビューのタブアイコンです。スタジオでは常に独自のアイコンが表示されます。

theme はプロジェクトの色を、shadcn 独自のトークン名でモードごとに指定します。background、foreground、primary、destructive、chart-1 から chart-5 を選んでください。これらを指定すると、それ以外の shadcn トークンは自動的に決まりますが、必要に応じて個別に設定することもできます。必須の色を省略した場合はデフォルトが使われます。sections はトークン名を指定してセクションの色を設定します。また、ウィンドウ下部のストライプには chart-1 から chart-3 が使われます。詳しくはブランディングをご覧ください。fonts には sans、serif、mono のフォントを指定します。それぞれ、ファミリー名と、読み込み元となるアップロード済みのフォントファイルを指定します。プロジェクトの外観は theme だけで決まり、別途スタイルシートを置く必要はありません。

アップロードファイルは、関連するページのそばにある docs/_uploads/ に保存されます。名前が _ で始まる docs/ 内のフォルダーにはページを置けないため、サイドバーには表示されません。スタジオからアップロードしたファイルはそこに保存されます。ページからリンクする際は、フォルダー名を含まない公開アドレスを使います。手動で配置したファイルも含め、アドレスは /img/docs/<file>、/files/docs/<file>、/whiteboards/<file>、または /uploads/<file> です。

moved.json は自動的に更新されます。サイドバーの並べ替え機能では、移動または削除のたびにエントリーが追加されます。スタジオでは古いアドレスからページの新しいアドレスにリダイレクトされ、公開サイトでは古いアドレスに転送用ページが生成されます。ただし、git での名前変更には対応しません。

• エントリーは追加しないでください。古い URL は無効になりますが、それで問題ありません。
• docs/ 内にある、旧パスを参照していたリンクを修正してください。旧パスを grep で検索すれば見つかります。
• 古い URL が誰かと共有されていた場合は、まず確認してください。依頼されていないエントリーは決して追加しないでください。

ページに含められるもの

ページは Markdown と、フレームワークが提供する固定コンポーネントで構成されます。コールアウト、<VideoEmbed />、<LinkEmbed />、<FileAttachment />、<Whiteboard />、レイアウトコンポーネント、インライン SVG 図などがあり、ほかのコンポーネントは blocks スキルに記載されています。スタイルのルールも同スキルに記載されているため、Markdown より複雑なものを追加する前に読んでください。このリストはフレームワークに属するもので、プロジェクトから追加することはできません。

コンポーネントの props に指定できるのは、文字列、数値、ブール値、それらの配列やオブジェクトなどのリテラル値です。コードを実行するものは、コンパイル前にページの処理を失敗させます。

• import と export の行。
• {new Date().getFullYear()} や {props.title} のような式。
• <script>、<iframe>、<object>、<embed>、<meta>、<link>、 <base>、<include> タグ。
• on* イベントハンドラーと dangerouslySetInnerHTML。

ドキュメントの追加

1. 適切なセクションフォルダーに、すべて小文字でハイフン区切りの名前を付けて .mdx ファイルを作成します（code-review.mdx）。手書きで作成するページはすべて .mdx にします。.md ファイルはプレーンな Markdown としてコンパイルされるため、その中の <VideoEmbed /> や図は何も表示されず、説明もされません。.md として追加されるのは、ジェネレーターが作成したページと変更履歴の 2 種類です。詳しくは後述します。
2. フロントマターを追加します。

 ---
 title: Code review
 icon: GitPullRequest
 description: One sentence. Shows up in search results and on section cards.
 ---

title と description は必須です。icon は省略可能で、ページのサイドバーとタイトルの横に表示される Lucide のコンポーネント名です。ページ上のそのアイコンをクリックすると、Lucide のアイコンセットを検索でき、選択したアイコンはこの同じフィールドに設定されます。アイコンがないページでは、タイトルの横の余白にアイコンが表示されます。ページを端的に視覚化できる場合に使い、単に余白を埋めるためだけに使わないでください。ページの URL は docs/ 以下のパスで、サイドバーのラベルは title です。そのため、slug、sidebar_label、sidebar_position は何も行いません。 3. 拡張子を除いたファイル名を、表示したい位置にあるフォルダーの meta.json の "pages" 配列に追加します。追加しなくても、すべての pages 配列の末尾に "..." があるため、ページは名前付きページの後にアルファベット順で表示されます。 4. editorial-illustration スキルを使って専用の SVG ファイルに描いたエディトリアルイラストを最初に配置し、Markdown 画像として表示してから、本文を書きます。標準的な Markdown に加え、コールアウト（:::note、:::warning、:::tip）と blocks スキルに記載されたブロックを使えます。ジェネレーターが作成したページと変更履歴には、イラストを付けません。 5. ほかのドキュメントへのリンクには相対ファイルパス（./commit-signing.mdx、../architecture/index.mdx）を使います。/security-and-compliance/commit-signing のようなサイト絶対パスも使用できます。別のページを指す名詞句は、各セクションで最初に登場するときにリンクし、リンクは積極的に追加してください。ページの途中から読み始めた読者も、説明されている内容にたどり着けるようにします。リンクをバッククォートで囲んではいけません。 `[text](./foo.mdx)` はリンクではなくコードとして表示されます。リンク先が存在しなくても、執筆時にエラーにはなりません。読者がクリックすると 404 になるため、リンク先のファイルが存在することを確認してください。

セクションの追加

1. docs/ の下に、小文字とハイフンで名前を付けたフォルダーを作成します。
2. サイドバーのラベル、1 文の説明、フォルダー内の項目の順序を記した meta.json を追加します。

 {
   "title": "Observability",
   "icon": "Activity",
   "description": "How we know what production is doing, and who gets woken up.",
   "pages": ["alerting", "dashboards", "..."]
 }

説明は、上のページに表示されるセクションカードの文言になります。省略すると、そのセクションが読者の目的に合っているかどうか、カードからは分かりません。pages には拡張子を除いたファイル名とサブフォルダー名を指定します。末尾の "..." があることで、リストに記載されていないページも表示できます。必ず残してください。"index" は含めないでください。フォルダーの index.mdx はすでにフォルダー行自体のページになっているため、リストに含めると、そのページが行から外れて子ページとして追加されます。独自のサイドバーを持つセクションだけは、これをリストに含めます。他のフォルダーとの間でセクション自体を配置する位置は、docs/meta.json の pages 配列に記載するフォルダー名で決まります。 3. セクションに紹介文やカードグリッドが必要な場合は、index.mdx を追加します。フロントマター、紹介文の順に記述し、その後に <DocCardList /> を配置します。description はページタイトルの下に自動表示されるため、導入段落で繰り返さないでください。 4. 既存ページの下にページを配置するには、name.mdx を name/index.mdx に移動し、その隣にページを配置します。ページのアドレスと配置場所は変わらないため、moved.json のエントリーを追加する必要はありません。また、ページ自身の相対リンクを 1 階層下に合わせて修正します。 5. 関連する内容は、既存のセクションにまとめることを優先してください。セクションの数が少ないほうが、多い場合よりもナビゲーションしやすくなります。

独自のサイドバーを持つセクション

サイドバーツリーの上にある切り替え機能を使うと、読者はセクション間を移動できます。セクションは、meta.json に "root": true を持つフォルダーです。セクション内のサイドバーには、そのセクションだけが表示されます。また、最初の行は常に概要ページになります。意思決定記録や自動生成されたリファレンスなど、独自の読者を持つ一連の資料がある場合は、セクションを作成します。読者が同じ閲覧中にそのセクションと隣接するセクションを行き来する場合は、通常のフォルダーにしてください。セクションを作成すると、隣接するセクションが表示されなくなるためです。セクションを追加する前にセクションと切り替え機能を確認してください。特に重要なルールは次のとおりです。

• フォルダー名は title に記載した名前に合わせ、小文字とハイフンを使います。
• セクションの meta.json にある title、icon、description が、切り替え機能の行に表示されます。説明は省略記号で切り詰められるため、約 30 文字に収めてください。説明がラベルとして使われるのはここだけです。
• pages の先頭には "index" を指定し、その隣に Overview というタイトルの index.mdx を配置します。ルートフォルダーは自動的にランディングページを取得しません。また、"pagesIndex": "index" を指定するとそのページが非表示になるため、どちらの方法も使わないでください。
• docs/meta.json の !<folder> は、そのフォルダーをメインツリーから除外します。また、切り替え機能には、これらの行の順序どおりにセクションが表示されます。! を付けずに記載すると、ページが両方のサイドバーに表示されます。
• プロジェクトのテーマの sections に "<folder>": "chart-2" を 1 行追加すると、どちらのモードでもセクションに色が付きます。メインツリーには primary が使われます。
• サイドバーの配置ツールに表示されるのは、そのツールを使っているセクションだけです。そのため、ページをセクション間でドラッグすることはできません。ファイルを移動し、両方の meta.json を手動で修正してください。

フォルダーを使わずにページに見出しを付ける

サイドバーの複数のページの上に見出しを表示するには、それらの meta.json の pages 配列で、該当ページの直前に "---Runbooks---" のような区切りを追加します。この区切りは、次の区切りまで、その後に続くすべてのページの上にラベルを表示します。ファイルの移動はないため、アドレスも変わりません。Lucide アイコンを付けるには、前に角括弧を追加します（"---[BookOpen]Runbooks---"）。サイドバーの配置ツールを使って、追加、名前の変更、ドラッグ、削除ができます。ランディングページで内容を説明する場合は、ランディングページを持つフォルダーとしてセクションを作成します。ラベルを繰り返すだけになる場合は、区切りを使ってください。

サイドバーからリンクする

pages 配列の行にはリンクを指定できます。"[Next.js docs](https://nextjs.org/docs)" のように記述し、前に角括弧で囲んだ Lucide アイコンを任意で追加できます。"[Rocket][Next.js docs](…)" のように記述します。リンクにはファイルがないため、検索インデックスにも llms.txt にも含まれません。 サイドバーにリンクを追加するを参照してください。

ホワイトボード

スタジオで /whiteboard を挿入すると、Excalidraw の描画を追加できます。ページには <Whiteboard src="/whiteboards/<hash>.excalidraw" preview="/whiteboards/<hash>.png" /> が保存され、どちらのファイルも docs/_uploads/whiteboards/ に格納されます。シーンの JSON には埋め込み画像が含まれます。ファイルはコンテンツアドレス方式で管理されるため、参照するページと一緒にコミットする必要があります。編集方法とサイズ制限については、ホワイトボードを参照してください。

生成されるページ

コードから生成したリファレンス（この用途のために構築した TypeDoc の出力が該当します）は、.mdx ではなく .md として格納されます。TypeDoc は Array<string> や Promise<{ … }> を本文に出力し、MDX ではそれらがコンポーネントとして解釈されるためです。コードを管理するリポジトリで生成し、出力を docs/ にコミットしてください。各ページには title と description のフロントマターが必要で、これは typedoc-plugin-frontmatter が書き込みます。また、フォルダーには meta.json が必要です。リファレンス全体に独立したセクションを割り当てるため、"root": true を指定し、ジェネレーターの出力先をそのフォルダーにします。これにより、書き込まれる index.md がセクションの概要になります。スタジオで編集しても、上流の JSDoc も変更しない限り、次回の生成時に上書きされます。ページのコンパイル時に、フレームワークが TypeDoc の [Form](Form.md) リンクに ./ を書き加えます。

変更履歴ページ

フロントマターに changelog: true を含むページは変更履歴であり、手書きのページの中で .mdx ではなく .md を使用する唯一のページです。リリースツールが行を出力し、Promise<void> や {foo} を含むコミットの件名は MDX では JSX として解釈され、ビルドに失敗するためです。プロジェクトの CHANGELOG.md をフロントマターの下に貼り付ければ、それでファイル全体が完成します。閲覧者には、検索ボックス、日付範囲、リリースへのジャンプ用ピッカー、各リリースに点が付いた目盛りが表示されます。

---
title: Changelog
description: Every release of the website, newest first.
changelog: true
---

## [2.15.6](https://github.com/o/r/compare/v2.15.5...v2.15.6) (2026-09-04)

### Bug Fixes

* **infra:** stop null query condition killing redirects ([ae6ab07](https://github.com/o/r/commit/ae6ab07))

これがコンテンツモデルのすべてです。ファイルのみで、複製もジェネレーターもありません。 同じフロントマターの下に新しいコピーを貼り付ければ、ページを更新できます。スクリプト、複製用フォルダー、リリースごとのページは追加しないでください。これらはどれも一度作られましたが、再び削除されています。リリースツールがリリースのたびに書き換えるコンテンツを複製してしまうためです。

フレームワークによるファイルの処理方法は次のとおりです。

• リリースは ## [2.15.6](…) (2026-09-04) のような見出しです。リンクなしの同じ形式も使用できます。バージョンは1〜3個の数字で構成され、プレリリースのサフィックスや先頭の v を付けられます。次の同形式の見出しまでのすべてが、そのリリースの本文となり、文章、リスト、表、画像などが含まれます。
• リリース見出しは読み込まれ、コンポーネントが独自の見出しを描画します。リリース内の ### 見出しは目次の項目ではなくセクションになります。
• その下に何もないバージョンアップも、リリースとして扱われ、点が表示されます。
• 最初のリリース見出しより上にあるものは、通常の Markdown としてそのまま残ります。貼り付けた # Changelog 見出しを削除してください。そうしないと、ページにタイトルが2つ表示されます。

リリース履歴が何年分もあるプロジェクトは、メジャーバージョンごとにページを設けたフォルダーに分割してください。v2.md、v1.md のようにし、index.mdx は作成せず、フォルダーの meta.json では新しい順に並べます。各ページには該当するリリースだけが表示されます。また、長いページはコンテンツの約2倍の量をハイドレーションデータとして保持するため、リリースが100件前後になったら分割してください。ChangelogTimeline、ChangelogRelease、ChangelogSection を手入力することはありません。

トーン

これは技術ドキュメントのライブラリです。技術に詳しい読者を対象にしつつ、やさしく導き、教える雰囲気を大切にします。優れたサイエンスコミュニケーターや、『Head First Design Patterns』のような楽しいエンジニアリング書籍の語り口を参考にしてください。具体的でありながら簡潔な例や図解を使うスタイルです。

人とAIに向けて書く

私たちの使命は、認知的な負荷を下げることです。ページを、無味乾燥な法律文書や技術文書のようにしてはいけません。何が変わったのかを、先輩が後輩に教えるように、親しみやすく概念的に説明します。ページ全体が、ホワイトボードの前でPRについて説明するときに著者が話す内容になるようにしてください。声に出して言わないようなことは、書く必要はありません。

すべてのページは、読者が実際に知りたくて訪れた問いに答えます。 ページを書く前に、その問いを読者の言葉で書き出してください。「これをサイトとして公開するには？」「ページのコンパイルに失敗したのはなぜ？」「図を表示するには何を入力すればいい？」といった問いです。問いによって、タイトルや章立て、削る内容、読者が答えを得て読み終える箇所が決まります。あるトピックについて知っていることをすべて並べたページは、ただのメモです。本来こちらが行うべき情報の整理を、読者に押しつけることになります。

目指すのは、優れたSaaSやオープンソースのマニュアルです。すべてのページが、誰かの具体的なタスクに応えるものです。

• タイトルは、技術の名前ではなく、その答えにします。「DockerとVercel」ではなく、「サイトとして公開する」。
• 章は、そのタスクの手順を読者が実行する順に並べます。別の問いに答える内容は、別のページにします。
• 作業中に得た知見そのものがページの主役ではありません。測定結果や行き詰まった点、つまずきやすい箇所は残す価値がありますが、該当する章の最後にある<Accordions>にまとめます。そうすればページは簡潔になり、同じ失敗をしそうな人にも必要な情報が届きます。
• モノレポや任意のブロックなど、一部の読者だけが選ぶ手順は、一般的なケースの下にあるサブセクションにします。ページの主軸にはしません。

ADR、会議議事録、変更履歴、システム全体の構成図などは、答えではなく記録です。こうしたページは例外です。それ以外はすべて、マニュアルのページです。

• 読者には「あなた」と呼びかけてください（例：「第3章でまたこの問題にぶつかります」）。
• 初心者が実際に口に出して尋ねる疑問に答えてください（「ちょっと待って、なぜこれがワーカーにあるの？」など）。
• 最初に概要を書いてください。人の注意力が最も鋭い一方で、意図についての知識が最も少ないのがこの段階です。専門知識のない人にもわかるよう、実例を交えて、結論、修正した内容とその理由、方法を示してください。
• 概要のあとに、2段落で少し掘り下げ、全体を俯瞰したアプローチを説明し、関連リンクを列挙してください。
• すべてのページは、フロントマターのすぐ下、概要の前に編集イラストを置いて始めてください。雑誌の記事の冒頭のように、ページの中心となる考えをひと目で伝える絵画風の場面を描きます。編集イラストのスキルを使って、:::wide 内の uploads に SVG ファイルとして配置してください。ページ内に直接埋め込んではいけません。イラストは雰囲気と比喩を伝えるもので、説明はしません。説明を担う図やチャートは、引き続き各章に置いてください。
• 章のタイトルは簡潔で短く、問題を直接表すものにしてください（例：「検索リクエストがキー入力のたびに実行されていた」）。
• 各章は、詳細に入る前に問題と解決アプローチを示すところから始めてください。次に理由を述べ、そのあとに詳細を説明します。読者が最初の段落で答えを得られるようにしてください。
• 章の段落、コード、図は織り交ぜてください。
• 認知負荷を下げるために図を活用してください。人は視覚的に学ぶため、視覚資料で認知負荷を下げることを最重要の指標とします。章には必要に応じて図やチャートを追加してください。
• これから述べる内容を繰り返したり、予告したりせず、本題に入ってください。

  bad:  "In this chapter we'll walk through how the validation logic was restructured."
  good: "The 2-character minimum was moved from the zod schema without any actual changes to the rule."
  

• 読者は技術に詳しいものの、プロジェクト、コードベース、ドメインについてはまったく知らないものと想定してください。
• ビジネス用語、ドメイン用語、参照先は、平易な言葉で簡潔に説明するホバーツールチップを付けてください。<abbr title="平易な説明">用語</abbr> を使います。
• 水増し表現、em ダッシュ、下手な対比表現など、AI の文章によくある特徴を書き換えてください。
• 抽象的なトレードオフの議論よりも、「Y だから X を使う」のような具体的な指針を優先してください。
• 用語を初めて使うときは、同じ文の中で意味を説明してください。
• 元に戻すコストが高い選択を記録する文書を書く場合は、docs/decision-records/ に ADR も作成してください。
• ツールの名前を挙げる際は、古くなった案内がわかるように、バージョンと日付も記載してください。
• 短い段落と、内容が明確な見出しを使ってください。検索インデックスと目次は、どちらも見出しから作られます。

コミット前のページのレビュー

作業コピーを読んだり編集したりするには、プロジェクトのフォルダーを Jotdown スタジオで開いてください。コミットされていないファイルや、Git の無視対象になっているフォルダーも含め、ページはディスクから読み込まれます。また、ファイルが変更されると、開いているページが更新されます。 保存してもファイルが書き込まれるだけで、コミットはされません。そのため、ほかの変更と同じように git diff で差分を確認してください。エディターのユーザーは、そのマシンで Git が指定しているユーザーです。

誰かのためにページを書くときは、コミット前に結果を読めるよう、Jotdown でフォルダーを開くことを提案してください。

コミットする前に

• 変更したページで jotdown check を実行し、報告されたエラーをすべて修正してください。 また、自分で作成したページにある警告も修正してください。
• シークレット、認証情報、API トークン、秘密鍵、接続文字列、個人データは含めないでください。これはドキュメントであり、保管庫ではありません。
• 内部向け URL やステージング用 URL は問題ありません。ホスト名はシークレットではありません。 argocd.mgmt.example.net や *.staging.* の管理者用 URL は、そのシステムについてのページであれば記載できます。ここに絶対に載せてはいけないのは、そのシステムにアクセスするためのものです。公開されたドキュメント自体にパスワードはないため、非公開のドキュメントにはホスト側でアクセス制御を設定してください。