ドキュメントを更新する
このサイトは英語がデフォルトです。英語の本文はリポジトリ直下の docs/、日本語訳は apps/docs/i18n/ja/docusaurus-plugin-content-docs/current/ にあります。Docusaurusが両方を直接読み込みます。
起動と確認
npm ci
npm run dev:docs
http://localhost:3001 で英語版を開きます。APIやDBは不要です。開発サーバーは一度に1言語だけを起動します。日本語版を確認する場合は、サーバーを止めてから次を実行します。
npm run dev:docs -- --locale ja
# http://localhost:3001/ja/
言語切り替えと全文検索を確認する場合は、開発サーバーを止めてから両言語をビルドします。
npm run build:docs
npm run preview:docs
英語版は /、日本語版は /ja/ です。ヘッダーの言語メニューから、同じページの翻訳へ切り替えられます。
内容の置き場所
| 読者がしたいこと | 各言語の本文ディレクトリ内の場所 |
|---|---|
| 初めて動かす・最初の変更をする | getting-started/ |
| 用語や仕組みを理解する | concepts/ |
| 特定の作業を進める | guides/ |
| 設計の細部を調べる | architecture/、database/、design/、requirements/ |
| 用語を引く | reference/ |
新しいページは英語・日本語の両方に同じ相対パスで作成し、文書IDとslugを揃えます。apps/docs/sidebars.ts に読んでほしい順番で登録し、関連するページからもリンクします。
ナビゲーションやサイドバーの日本語訳は apps/docs/i18n/ja/ 配下のJSONファイルにあります。設定の英語ラベルと日本語訳を一緒に更新してください。手順を変更した場合も両言語の本文を更新します。
初めて読む人が迷わない書き方
- 冒頭で「何ができるようになるか」と前提条件を説明します。
- コマンドの実行場所を明記し、実行後に何を見れば成功と分かるかを書きます。
- 新しい略語は最初に説明します。コードの名前はそのまま示し、意味を日本語で添えます。
- 図は1つの問いに絞ります。図の前後に、どこから読んで何が重要かを書きます。
- 現在動いている仕様、検証の記録、今後の構想を区別します。
- 最後に、次の作業や関連する詳細資料へのリンクを置きます。
Honoのような「短い説明 → 小さな例 → 試す手順 → 次に読むページ」を参考にしています。見出しや見た目だけでなく、読者が行動できる内容を揃えます。参考: Hono Getting Started
リンクと図
文書同士は相対パスの .md リンク、サイト外のコードはGitHubのリンクを使います。通常は .md、Reactを埋め込む必要がある場合だけ .mdx を使います。
Mermaidの図はコードブロックで書けますが、本文のリンクと違ってビルド成功だけでは描画の正しさを保証しません。ブラウザでも確認してください。
ビルドでは両言語の文書間リンクと見出しへのリンクを検査します。設定の詳細は apps/docs/README.mdを参照してください。