docs: add Docusaurus docs site with EN/JA i18n and GitHub Pages deploy#25
Merged
docs: add Docusaurus docs site with EN/JA i18n and GitHub Pages deploy#25
Conversation
Sets up a Docusaurus 3 site under website/ with multi-language support (EN default, JA via i18n plugin). Adds mise tasks for local build and serve, and a GitHub Actions workflow to deploy on tag push.
Remove old docs/user-guide.md and docs/user-guide.ja.md now that content lives in website/. Update README links to point to the hosted docs site. Add doc-update reminder to AGENTS.md and PR template checklist.
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (12)
📝 WalkthroughWalkthroughThis PR establishes a Docusaurus-based documentation site in the Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~40 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
This PR migrates project documentation from the previous single-file Markdown guides to a Docusaurus site under website/ with English/Japanese i18n, and adds a GitHub Actions workflow to deploy the built site to GitHub Pages on version tag pushes.
Changes:
- Add a Docusaurus docs site (
website/) with EN docs and JA translations, including Mermaid support and sidebar navigation. - Add a GitHub Actions workflow to build and publish the docs site to
gh-pagesonv*tag pushes. - Update developer tooling and repo docs/links (mise tasks, README links, agent guidance), and remove the legacy
docs/user-guide*files.
Reviewed changes
Copilot reviewed 26 out of 27 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
website/src/css/custom.css |
Adds Docusaurus theme customizations (primary colors, code font size). |
website/sidebars.js |
Defines the docs sidebar structure/order. |
website/package.json |
Adds the docs site package manifest and Docusaurus dependencies. |
website/docusaurus.config.js |
Configures Docusaurus (i18n, baseUrl, Mermaid theme, navbar/footer). |
website/.gitignore |
Ignores Docusaurus build artifacts and node_modules within website/. |
website/docs/index.md |
Adds the English landing page (slug /) and quick start. |
website/docs/installation.md |
Adds English installation/uninstallation documentation. |
website/docs/authentication.md |
Adds English authentication documentation (API key + OAuth). |
website/docs/commands.md |
Reworks the previous combined guide content into the Commands page structure. |
website/docs/configuration.md |
Adds English config/credential storage locations and format. |
website/docs/troubleshooting.md |
Adds English troubleshooting guidance for common auth/keyring issues. |
website/i18n/ja/docusaurus-plugin-content-docs/current/index.md |
Adds Japanese landing page translation. |
website/i18n/ja/docusaurus-plugin-content-docs/current/installation.md |
Adds Japanese installation/uninstallation translation. |
website/i18n/ja/docusaurus-plugin-content-docs/current/authentication.md |
Adds Japanese authentication translation. |
website/i18n/ja/docusaurus-plugin-content-docs/current/commands.md |
Adds Japanese commands reference translation. |
website/i18n/ja/docusaurus-plugin-content-docs/current/configuration.md |
Adds Japanese configuration translation. |
website/i18n/ja/docusaurus-plugin-content-docs/current/troubleshooting.md |
Adds Japanese troubleshooting translation. |
.github/workflows/docs.yml |
Builds and deploys the docs site to GitHub Pages on tag pushes. |
mise.toml |
Adds Node tooling and docs-related mise tasks (docs-install, docs-build, docs-serve). |
README.md |
Updates links from local user guide to hosted documentation site (EN). |
README.ja.md |
Updates links from local user guide to hosted documentation site (JA). |
AGENTS.md |
Updates documentation-update guidance to reference the new Docusaurus paths. |
.github/PULL_REQUEST_TEMPLATE.md |
Updates checklist to remind contributors to update website/ docs. |
.cspell/dicts/project.txt |
Adds peaceiris to project dictionary for workflow spelling checks. |
.cspell.yml |
Ignores pnpm-lock.yaml for spell checking. |
docs/user-guide.ja.md |
Removes legacy Japanese user guide (content moved to website/). |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
website/docs/commands.md (2)
23-29:⚠️ Potential issue | 🟡 Minor
bl space --jsonis undocumented in the mainspacesection.
src/main.rs:47-77defines a top-level--jsonflag forbl space, but the examples here only show the plain command. Add abl space --jsonexample or mention the flag in the description.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@website/docs/commands.md` around lines 23 - 29, The docs for the "bl space" command omit the top-level --json flag; update the "bl space" section to mention the --json option and show an example (e.g., "bl space --json") or add a short sentence stating that a global --json flag (defined in main) can be used to output JSON; edit the `bl space` description in website/docs/commands.md and include the `--json` flag name and a sample invocation so readers know the flag exists and how to use it.
13-21:⚠️ Potential issue | 🟡 MinorAuth command docs are missing implemented entries.
src/main.rs:524-564also exposesbl auth keyring, andbl auth statussupports--json. Those should be listed here so the new command reference stays complete.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@website/docs/commands.md` around lines 13 - 21, The docs table is missing the implemented auth entries: add a row for the `bl auth keyring` command (describing its purpose, e.g., manage or migrate credentials via the system keyring) and update the `bl auth status` entry to mention the `--json` flag (e.g., "Show current auth status and verify credentials; supports `--json` output for machine-readable results"); ensure the exact command names (`bl auth keyring`, `bl auth status --json`) match the CLI implementation so the command reference is complete and discoverable.
🧹 Nitpick comments (3)
.github/PULL_REQUEST_TEMPLATE.md (1)
6-6: IncludeREADME.ja.mdin this checklist item.This PR updates both READMEs, but the checklist only names the English one. Adding
README.ja.mdhere would make localization drift a little harder to miss in future docs-only changes.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/PULL_REQUEST_TEMPLATE.md at line 6, Update the PR checklist item that currently reads "Documentation updated if user-visible behavior changed (`website/docs/`, `website/i18n/ja/`, `README.md`)" to also include `README.ja.md` so localized README changes are explicitly covered; edit the checklist text in .github/PULL_REQUEST_TEMPLATE.md to list `README.ja.md` alongside `README.md` (and keep the existing entries) to prevent missing localized README updates.website/package.json (1)
17-19: Pin the pnpm version inpackageManager.CI enables pnpm via Corepack, but this manifest doesn't declare a
packageManager. Corepack resolves the package manager version from that field; without it, installs fall back to the runner's default Corepack/pnpm selection, so behavior can drift aslts/*moves. Add an exactpnpm@...here to keep local and CI installs reproducible. (nodejs.org)♻️ Suggested change
"engines": { "node": ">=18.0" - } + }, + "packageManager": "pnpm@<exact-version>" }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@website/package.json` around lines 17 - 19, Add a packageManager field to package.json to pin the pnpm version so Corepack resolves a stable installer; update the top-level manifest by adding e.g. "packageManager": "pnpm@8.8.0" (or the exact pnpm version your CI uses) alongside the existing "engines" entry, then commit the change so local and CI installs are reproducible.website/docusaurus.config.js (1)
5-6: Remove commented-out code.The commented line
// title: 'backlog-cli',is redundant since the actual title is set on the next line.🧹 Suggested cleanup
- // title: 'backlog-cli', title: 'Backlog CLI',🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@website/docusaurus.config.js` around lines 5 - 6, Remove the redundant commented-out title line "// title: 'backlog-cli'," from the Docusaurus config so only the active title assignment (title: 'Backlog CLI') remains; locate the title property in docusaurus.config.js and delete the commented duplicate, and ensure no other obsolete commented title entries remain in that config.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/workflows/docs.yml:
- Around line 3-7: The workflow currently only triggers on tag pushes ('on' ->
'push' -> 'tags: - "v*"') and manual dispatch ('workflow_dispatch'), which means
the site won't be deployed for the initial bootstrap and README links on main
will break; update the workflow triggers to also deploy on pushes to the main
branch (add 'push' -> 'branches: - "main"' alongside the existing 'tags' entry)
so the first Pages deployment runs after merge, or alternatively revert README
links until the site is live; ensure you modify the 'on', 'push', 'tags' and
'workflow_dispatch' entries accordingly.
In `@website/docs/authentication.md`:
- Around line 100-111: Update the OAuth example and explanatory text in
authentication.md to match the actual output of the bl auth status command: add
a "Stored in: System keyring" line to the OAuth example block (so the block
includes "Auth method", "Client ID", "Client Secret", "Access token", "Stored
in: System keyring", and "Logged in as"), change the sentence about BL_API_KEY
to say "When API-key auth is being used via BL_API_KEY, Stored in shows
Environment variable" and add a clarifying sentence that stored OAuth tokens for
a space take precedence over BL_API_KEY so the OAuth status will be shown if
present; apply the same wording change to the Japanese translation as well.
In `@website/docs/commands.md`:
- Around line 3-9: The docs incorrectly list `--banner` as a global option;
update the page to remove `--banner` from the "Global options" table and either
(a) create a separate "Top-level flags" or "Global flags (root only)" section
that documents `--banner` as a root-level flag, or (b) rename the current
section to "Common options" and explicitly state which flags are global vs
root-only; ensure `--no-color` and `--space <SPACE_KEY>` remain documented as
global options and that `--banner` is clearly marked as non-global/root-only
(reference the `--banner`, `--no-color`, and `--space` flags to locate the
corresponding entries).
In `@website/docs/installation.md`:
- Around line 81-87: The docs claim the uninstall scripts run "bl auth logout
--all" with --purge but the actual uninstall scripts call "bl auth logout"
(leaving non-current spaces behind); update both uninstall scripts so the purge
flow invokes "bl auth logout --all" (ensure the code path handling the
--purge/--Purge flag calls the CLI with the --all flag), and update the
corresponding Japanese docs page to match the corrected behavior.
- Around line 25-30: The INSTALL_DIR environment variable in the install example
is exported on the curl process, so it won't be visible to the shell that
executes the script; change the example so INSTALL_DIR is applied to the shell
that runs the script (e.g., attach INSTALL_DIR to the sh invocation or export it
before the pipeline) so the installer sees INSTALL_DIR and installs to the
intended location; update the example line that constructs the pipeline (the
curl | sh snippet) to move INSTALL_DIR from the left side of the pipe to the sh
command (or use export) so the installer uses the provided INSTALL_DIR.
In `@website/docs/troubleshooting.md`:
- Around line 3-5: Update the heading and explanatory sentence for the "API key
not found. Run bl auth login to authenticate." section so it no longer assumes
only the keyring; change the text to indicate that "no stored credentials were
found" and instruct the user to run `bl auth login` (or check environment
variables / fallback file) as applicable, ensuring the heading string and the
explanatory line are replaced accordingly.
In `@website/i18n/ja/docusaurus-plugin-content-docs/current/commands.md`:
- Around line 13-21: Add a new table row for the missing subcommand: insert the
row for `bl auth keyring` into the Markdown table in commands.md so it reads: |
`bl auth keyring` | システムキーリングが利用可能かをチェック |; ensure it follows the same table
formatting as the other rows and is placed with the other `bl auth ...` entries
so the table remains valid Markdown and aligned with existing entries like `bl
auth login` and `bl auth logout`.
---
Outside diff comments:
In `@website/docs/commands.md`:
- Around line 23-29: The docs for the "bl space" command omit the top-level
--json flag; update the "bl space" section to mention the --json option and show
an example (e.g., "bl space --json") or add a short sentence stating that a
global --json flag (defined in main) can be used to output JSON; edit the `bl
space` description in website/docs/commands.md and include the `--json` flag
name and a sample invocation so readers know the flag exists and how to use it.
- Around line 13-21: The docs table is missing the implemented auth entries: add
a row for the `bl auth keyring` command (describing its purpose, e.g., manage or
migrate credentials via the system keyring) and update the `bl auth status`
entry to mention the `--json` flag (e.g., "Show current auth status and verify
credentials; supports `--json` output for machine-readable results"); ensure the
exact command names (`bl auth keyring`, `bl auth status --json`) match the CLI
implementation so the command reference is complete and discoverable.
---
Nitpick comments:
In @.github/PULL_REQUEST_TEMPLATE.md:
- Line 6: Update the PR checklist item that currently reads "Documentation
updated if user-visible behavior changed (`website/docs/`, `website/i18n/ja/`,
`README.md`)" to also include `README.ja.md` so localized README changes are
explicitly covered; edit the checklist text in .github/PULL_REQUEST_TEMPLATE.md
to list `README.ja.md` alongside `README.md` (and keep the existing entries) to
prevent missing localized README updates.
In `@website/docusaurus.config.js`:
- Around line 5-6: Remove the redundant commented-out title line "// title:
'backlog-cli'," from the Docusaurus config so only the active title assignment
(title: 'Backlog CLI') remains; locate the title property in
docusaurus.config.js and delete the commented duplicate, and ensure no other
obsolete commented title entries remain in that config.
In `@website/package.json`:
- Around line 17-19: Add a packageManager field to package.json to pin the pnpm
version so Corepack resolves a stable installer; update the top-level manifest
by adding e.g. "packageManager": "pnpm@8.8.0" (or the exact pnpm version your CI
uses) alongside the existing "engines" entry, then commit the change so local
and CI installs are reproducible.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: bfd4993b-e3ba-4e54-a09e-65edb560ebfe
⛔ Files ignored due to path filters (1)
website/pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (26)
.cspell.yml.cspell/dicts/project.txt.github/PULL_REQUEST_TEMPLATE.md.github/workflows/docs.ymlAGENTS.mdREADME.ja.mdREADME.mddocs/user-guide.ja.mdmise.tomlwebsite/.gitignorewebsite/docs/authentication.mdwebsite/docs/commands.mdwebsite/docs/configuration.mdwebsite/docs/index.mdwebsite/docs/installation.mdwebsite/docs/troubleshooting.mdwebsite/docusaurus.config.jswebsite/i18n/ja/docusaurus-plugin-content-docs/current/authentication.mdwebsite/i18n/ja/docusaurus-plugin-content-docs/current/commands.mdwebsite/i18n/ja/docusaurus-plugin-content-docs/current/configuration.mdwebsite/i18n/ja/docusaurus-plugin-content-docs/current/index.mdwebsite/i18n/ja/docusaurus-plugin-content-docs/current/installation.mdwebsite/i18n/ja/docusaurus-plugin-content-docs/current/troubleshooting.mdwebsite/package.jsonwebsite/sidebars.jswebsite/src/css/custom.css
💤 Files with no reviewable changes (1)
- docs/user-guide.ja.md
Replace peaceiris/actions-gh-pages with actions/upload-pages-artifact and actions/deploy-pages to avoid managing a gh-pages branch, which conflicts with tag-based release workflow.
Previously only the current space's credentials were removed. The --purge flag should clear all spaces.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Checklist
mainwebsite/docs/,website/i18n/ja/,README.md)Summary
website/with EN/JA multi-language supportdocs/user-guide.md/docs/user-guide.ja.md(content moved towebsite/)Reason for change
The single-file user guide was hard to navigate and lacked proper i18n support. Docusaurus provides a polished multi-language docs site with sidebar navigation and search.
Changes
website/— Docusaurus 3 site (EN docs + JA i18n translations, Mermaid support).github/workflows/docs.yml— deploy to GitHub Pages onv*tag push usingactions/upload-pages-artifact+actions/deploy-pages(nogh-pagesbranch)mise.toml— addnode,docs-install,docs-serve,docs-buildtasksREADME.md/README.ja.md— link to hosted docs site instead of local markdownAGENTS.md— update doc path references.github/PULL_REQUEST_TEMPLATE.md— add doc-update reminder to checklistdocs/user-guide.*— removed (superseded bywebsite/)Notes
Local preview:
mise run docs-serve(builds all locales and serves athttp://localhost:3000/backlog-cli/)Docs will be live at
https://23prime.github.io/backlog-cli/after the first tagged release. GitHub Pages must be configured to use GitHub Actions as the source (Settings → Pages → Source → GitHub Actions).