Update the documentation
English is the default language. English pages live in the repository's docs/ directory; Japanese translations live in apps/docs/i18n/ja/docusaurus-plugin-content-docs/current/. Docusaurus reads both locations directly.
Start and preview
npm ci
npm run dev:docs
Open http://localhost:3001 for English. The API and database are not required. The development server runs one language at a time. Stop it before starting Japanese:
npm run dev:docs -- --locale ja
# http://localhost:3001/ja/
To check the language switcher and full-text search, stop the development server and build both languages:
npm run build:docs
npm run preview:docs
English is served at / and Japanese at /ja/. Use the language menu in the header to switch between translations of the current page.
Where content belongs
| Reader's goal | Directory within each language's content root |
|---|---|
| Run the app or make a first change | getting-started/ |
| Understand terms and mechanisms | concepts/ |
| Complete a specific task | guides/ |
| Explore design details | architecture/, database/, design/, requirements/ |
| Look up terminology | reference/ |
When adding a page, create the English page and its Japanese counterpart at the same relative path. Keep document IDs and slugs aligned so switching languages stays on the same page. Register it in reading order in apps/docs/sidebars.ts and link to it from related pages.
Navigation and sidebar translations are in the JSON files under apps/docs/i18n/ja/. Update the English labels in the configuration and their Japanese translations together. Keep both language versions current when changing instructions.
Write for first-time readers
- Begin with what the reader will be able to do and any prerequisites.
- State where to run commands and what successful output looks like.
- Explain new abbreviations on first use. Preserve code identifiers and explain their meaning in the page's language.
- Keep each diagram focused on one question. Explain where to start reading and what matters.
- Distinguish current behavior, verification records, and future plans.
- End with links to the next task or relevant reference material.
Follow the pattern “short explanation → small example → steps to try → next page,” as in Hono's documentation. Make the content actionable, not just visually similar. Reference: Hono Getting Started
Links and diagrams
Use relative .md links between documents and GitHub links for source code outside the site. Use .md by default; use .mdx only when embedding React components.
Write Mermaid diagrams in fenced code blocks. A successful build checks document links but does not guarantee that diagrams render correctly, so inspect them in a browser too.
The build checks document links and heading anchors for both languages. See apps/docs/README.md for configuration details.