ドキュメントを更新する
このサイトは英語がデフォルトです。英語の本文はリポジトリ直下の docs/、日本語訳は apps/docs/i18n/ja/docusaurus-plugin-content-docs/current/ にあります。Docusaurusは apps/docs/public-content.json に明示されたページだけを公開します。
英語版を原本として先に更新し、同じ変更で日本語訳も更新します。前提条件、コマンド、オプション名、標準値、制約、次に読むページのリンクが一致するか確認してください。翻訳ファイルが存在することと、ビルドが成功することだけでは、本文の対応は保証できません。
リポジトリの標準のMarkdownは英語で書きます。README、開発参加者向けガイド、運用手順、PRテンプレートも対象です。日本語版サイトの翻訳は apps/docs/i18n/ja/ に置きます。著作権・ライセンスの原文表記は維持し、引用した識別子や多言語対応の例で必要な日本語も残します。その周囲の標準ドキュメントの説明は英語で書いてください。
起動と確認
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/public-content.json に追加し、apps/docs/sidebars.ts に読んでほしい順番で登録して、関連するページからもリンクします。
ナビゲーションやサイドバーの日本語訳は apps/docs/i18n/ja/ 配下のJSONファイルにあります。設定の英語ラベルと日本語訳を一緒に更新してください。手順を変更した場合も両言語の本文を更新します。
公開前に情報を確認する
このサイトとGitHubリポジトリは公開されています。開発の説明や一般的な手順を置き、機密の運用記録はリポジトリ外のアクセス制限された場所で管理します。サイトから除外したページも、リポジトリでは閲覧できます。
docs/operations/ の本番手順書は意図的に public-content.json へ含めていないため、日本語訳とサイドバーの項目はありません。公開ページからはGitHubのURLでリンクしてください。
管理画面は汎用URLを使い、設定例は例示用の値にします。実アカウントID、連絡先メールアドレス、認証情報、署名付きURL、顧客データ、本番ログを記載しないでください。画像やダウンロード用ファイルも確認します。apps/docs/static/ のファイルは、public-content.json の staticAssets に別途登録が必要です。
ビルド時に日英の元文書と全生成ファイルを検査します。検索索引やJavaScriptも対象とし、代表的な機密情報の形式、公開ページの経路、翻訳の不足を確認します。検査の成功だけで内容の安全性は保証されません。公開済みの値を削除しても、Git履歴や第三者が取得済みのコピーからは消えません。
初めて読む人が迷わない書き方
- 冒頭で「何ができるようになるか」と前提条件を説明します。
- コマンドの実行場所を明記し、実行後に何を見れば成功と分かるかを書きます。
- 新しい略語は最初に説明します。コードの名前はそのまま示し、意味を日本語で添えます。
- 図は1つの問いに絞ります。図の前後に、どこから読んで何が重要かを書きます。
- 現在動いている仕様、検証の記録、今後の構想を区別します。
- 最後に、次の作業や関連する詳細資料へのリンクを置きます。
Honoのような「短い説明 → 小さな例 → 試す手順 → 次に読むページ」を参考にしています。見出しや見た目だけでなく、読者が行動できる内容を揃えます。参考: Hono Getting Started
リンクと図
文書同士は相対パスの .md リンク、サイト外のコードはGitHubのリンクを使います。公開ページは .md を使います。Reactを埋め込む .mdx に対応する場合は、公開ルールと埋め込み内容の確認が必要です。現在の許可リストでは .mdx を受け付けません。
Mermaidの図はコードブロックで書けますが、本文のリンクと違ってビルド成功だけでは描画の正しさを保証しません。ブラウザでも確認してください。
ビルドでは両言語の文書間リンクと見出しへのリンクを検査します。設定の詳細は apps/docs/README.mdを参照してください。