Refactor docs structure: fix title/sidebar mismatches, complete English translation#56
Merged
Merged
Conversation
Captures the current-state audit (URL contract, title/H1 mismatches, translation gaps, broken links/anchors) and the phased plan to fix folder structure, sidebar/title consistency, and English translation without changing any published URL.
Adds three checks wired into `pnpm run check`: - check-url-inventory.mjs: diffs the built site's routes against a committed baseline (scripts/url-inventory.txt), generated from the current build. This is the mechanical guarantee that later refactor phases don't change any published URL. - check-i18n-parity.mjs: reports zh-Hans docs missing an English mirror and vice versa (warn-only via scripts/check-config.json until the translation backlog in Phase 5 is cleared). - check-frontmatter.mjs: reports missing titles, leftover id:/ sidebar_position: overrides, number-prefixed filenames, and stray body H1s (warn-only until Phase 4 normalizes titles). Also adds a Gitea Actions CI workflow that runs build + check on PRs, and inserts `pnpm run check` into the deploy workflow so a bad merge can't ship. .DS_Store was already gitignored and untracked, so no cleanup was needed there.
… (Phase 1)
- Migrate onBrokenMarkdownLinks to markdown.hooks.onBrokenMarkdownLinks
(deprecated top-level option, removed in Docusaurus v4) and flip
onBrokenLinks/onBrokenAnchors to "throw" now that the build is clean.
- Fix the 2 broken links and 7 broken anchors the previous "warn"
setting let ship:
- dev/agent/skill-install.md linked to non-existent ./agent-skill
and ./agent-skill-dev paths instead of the actual sibling
filenames ./skill.md and ./skill-dev.md.
- use/6.vscode.md (zh + en) and the footer "使用指南" link pointed at
/docs/use/, which has never resolved (the quick-start doc lives at
/docs/use/use/) — pointed them at the real path.
- change/README.md's historical changelog entry linked to a
non-existent dev/meta.md#console anchor; retargeted to
dev/background.md#日志, the section it was actually describing.
- dev/README.md, dev/api.md, dev/meta.md referenced heading anchors
using the raw Chinese heading text, which doesn't match
Docusaurus's generated slugs once backticks/parens/emoji are
stripped (e.g. #定时脚本 -> #定时脚本crontab, #storagename-🧪 ->
#storagename-, #gm_cookie -> #gm_cookie-).
- Add @docusaurus/plugin-client-redirects with a single redirect,
/docs/use/ -> /docs/use/use/, as a safety net for old bookmarks/search
engines (the broken-link checker doesn't recognize plugin-generated
redirect targets, so in-content links were fixed directly instead).
- editUrl now sets editLocalizedFiles: true so "Edit this page" on
/en/ docs opens the English source instead of the zh one.
- Add blog: false to the classic preset: bumping @docusaurus/core to
the already-pinned ^3.10.1 (previously resolved to a stale 3.9.2 in
the lockfile) caused the default-enabled, content-less blog plugin
to start emitting empty /blog/ and /en/blog/ routes that never
existed on the site; disabling it restores the original route set.
- Ran update-browserslist-db (caniuse-lite was 13-15 months stale).
scripts/url-inventory.txt gains exactly 2 routes (/docs/use/index.html,
/en/docs/use/index.html) for the new redirect; no existing route
changed, verified by `pnpm run check`.
Renames every doc so its file path matches its doc id/URL verbatim,
then deletes the id:/sidebar_position: frontmatter overrides that
existed only to paper over the mismatch:
- docs/use/N.foo.md -> docs/use/foo.md (numbered-prefix files); the
numeric prefix was already being stripped from the id/URL by
Docusaurus, so this is a pure rename with no id override needed.
- docs/use/4.from-other/ -> docs/use/from-other/,
docs/use/99.policy/ -> docs/use/policy/ (same reasoning for dirs).
- docs/dev/agent/{conversation,dom,skill,skill-dev,skill-install,
task,model,opfs,mcp,builtin-tools}.md -> agent-*.md, matching the
id: overrides they previously needed (dev/agent/agent-conversation
etc.) so the override can be deleted instead of the filename staying
arbitrary.
- docs/dev/README.md -> docs/dev/index.md, docs/change/README.md ->
docs/change/index.md, docs/about/README.md -> docs/about/index.md:
README-as-index needed an explicit id: override before; index.md is
Docusaurus's native landing-page convention, no override needed.
- docs/change/beta.md -> docs/change/beta-changelog.md to match its
id: beta-changelog override (now deleted).
- docs/use/1.README.md -> docs/use/use.md keeps a `slug: /use/use`
frontmatter override — Docusaurus auto-collapses a doc whose
filename matches its enclosing folder name (here "use/use.md") to
the parent path, which would have silently changed the published
URL from /docs/use/use/ to /docs/use/; the explicit slug pins it.
- Deleted the two _category_.json files; their labels move into
sidebars.js as explicit category items.
- sidebars.js is now fully explicit for all three sidebars (use, dev,
change), replacing autogeneration (which had a real ordering
collision between the two files both prefixed "2.") and the
descending sidebar_position: 9995..10000 changelog-ordering hack.
- Updated the two internal cross-references that pointed at renamed
files by relative path (change/index.md <-> beta-changelog.md,
dev/agent/agent-skill-install.md -> agent-skill.md/agent-skill-dev.md),
and updated the two navbar docId references (dev/dev -> dev/index,
change/change -> change/index) to match.
Every file was moved in both docs/ and its i18n/en mirror (where a
mirror exists) so ids stay aligned across locales.
Verified via `pnpm run check`: the URL inventory is still exactly the
94 routes from Phase 1 (zero drift from ~35 file renames), and the
build has zero broken links/anchors under the "throw" settings from
Phase 1.
Migrates every img/*.assets/ nested folder to a plain sibling
<doc-name>.assets/ directory next to its .md file, matching the
convention already used by dev/background.assets, dev/cloudcat.assets,
dev/config.assets, and change/v1.3.assets:
- docs/use/img/README.assets/ split by actual consumer: the 5 images
used by use/use.md moved to use/use.assets/, the 4 images used by
use/open-dev.md merged into use/open-dev.assets/ alongside the 6
images that were already in use/img/5.open-dev.assets/.
- docs/use/from-other/img/{migrate-from-tampermonkey,
migrate-from-violentmonkey}/ -> sibling
migrate-from-tampermonkey.assets/ and migrate-from-violentmonkey.assets/.
Two screenshots of the ScriptCat import step are genuinely shared
between both migration guides; they stay in
migrate-from-tampermonkey.assets/ and migrate-from-violentmonkey.md
references them cross-folder rather than duplicating the files.
- docs/change/img/{README,v0.16}.assets/ (3 + 1 images, both only ever
referenced from v0.16.md) merged into docs/change/v0.16.assets/;
img/v0.17.assets/ and img/v1.2.assets/ promoted to plain siblings.
- Same treatment for the i18n/en mirror tree (README.assets/ ->
use.assets/, 5.open-dev.assets/ -> open-dev.assets/, etc.); the en
from-other assets were already correctly split per-doc, just needed
the folder rename.
- All docs/**/img/ directories are now gone; every remaining image
reference is a relative path to a same-directory *.assets/ folder.
Verified via `pnpm run check`: URL inventory still exactly the 94
routes from Phase 1/2, and a clean rebuild confirms every image
(including the two shared migration-guide screenshots) still resolves
in both locales.
Moves every doc's body H1 into frontmatter `title` and removes the H1
line, so Docusaurus renders the page heading from `title` alone —
making a sidebar/title/H1 mismatch impossible by construction instead
of by convention:
- 42 docs (zh + en) had no frontmatter title at all; a mechanical pass
lifted their existing H1 text into `title` and deleted the H1 line.
- 6 docs had a title that didn't match their H1 (the actual bugs this
refactor targets, including the reported "VSCode 扩展开发脚本" vs
"使用 VSCode 开发脚本" mismatch):
- use/vscode.md (zh + en): title replaced with the H1 text so the
sidebar now shows what the page actually says.
- use/policy/{disclaimer,privacy,privacy_website}.md (zh) and
policy/disclaimer.md (en): title replaced with the fuller H1 text,
with the previous short title preserved as `sidebar_label` so the
sidebar entry stays uncluttered while the page title is accurate.
- use/policy/privacy.md and privacy_website.md (en) already had no
body H1, so were left untouched.
- use/install_comple.md keeps its `hide_title: true` exemption (its
decorative "🎉 欢迎使用脚本猫" H1 is intentional).
Fixed a false positive in check-frontmatter.mjs: it was flagging
example "# Heading" lines inside fenced ```markdown code samples
(dev/agent/agent-skill-dev.md's SKILL.cat.md examples) as real H1s.
The check now strips fenced code blocks before scanning.
With zero real violations left, scripts/check-config.json flips
frontmatterStrict to true, so this class of mismatch fails CI instead
of just warning.
Verified via `pnpm run check`: URL inventory still the same 94 routes,
build is clean, and the frontmatter check now passes in strict mode.
…(Phase 5)
Translates the 25 zh-Hans docs that had no English mirror:
- about/index.md
- change/{v0.16,v0.17,v1.1,v1.2,v1.4}.md
- dev/{index,api,background,cat-api,cloudcat,config,meta,subscribe}.md
- dev/agent/{index,agent-conversation,agent-dom,agent-mcp,agent-model,
agent-opfs,agent-skill,agent-skill-dev,agent-skill-install,
agent-task,agent-builtin-tools}.md
Cross-reference anchors were translated to match the actual heading
slugs Docusaurus generates for the English headings (e.g.
background.md's "## Scheduled Script (`@crontab`)" produces
#scheduled-script-crontab, not the zh slug) — verified by rebuilding
with onBrokenAnchors: throw.
Screenshots referenced by the newly translated change/v0.16.md,
v0.17.md, v1.2.md, and dev/background.md, cloudcat.md, config.md are
genuinely language-neutral UI screenshots; rather than duplicating the
binary files into the en tree, these six docs reference the existing
zh screenshots via @site/docs/... absolute paths.
scripts/check-config.json flips i18nParityStrict to true now that the
translation backlog is cleared, so a doc added to one locale without
its mirror will fail CI going forward.
Verified via `pnpm run check`: URL inventory still the same 94 routes,
i18n parity passes (41/41 docs translated), frontmatter check passes,
and the build is clean with zero broken links/anchors/images in both
locales.
Documents the one-convention-per-concern rules from REFACTOR_PROPOSAL.md (file path = URL, title-only frontmatter, sidebar ordering, asset folders, i18n mirroring) plus the load-bearing URLs that must never change and the zh/en terminology glossary, so future contributors and agents don't need to rediscover these rules from the proposal doc or git history.
The "dev" sidebar's "Agent 智能助手" category had no i18n string, so the English site was falling back to the raw Chinese label in the sidebar and breadcrumbs. Adds sidebar.dev.category.Agent 智能助手 -> "Agent" to i18n/en/docusaurus-plugin-content-docs/current.json, verified in the browser preview (breadcrumb now reads "Agent > Installing and Using Skills" instead of "Agent 智能助手 > ...").
Collaborator
Author
|
This is full refactoring & translation by AI. merge this first. the detail translation will be covered by #30 |
CodFrm
reviewed
Jul 8, 2026
| run: | | ||
| pnpm install --frozen-lockfile | ||
| pnpm run build | ||
| pnpm run check |
Member
There was a problem hiding this comment.
check应该在build前面
原来需要check构建后的产物
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
2 participants
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.
Summary
Implements the plan in REFACTOR_PROPOSAL.md, addressing two problems raised about this repo:
docs//i18n/folder structure was messy (numbered-prefix filenames,README.md-as-index files needingid:frontmatter overrides, three different URL-derivation mechanisms).No published URL changes except one intentional addition (
/docs/use/now redirects to the existing/docs/use/use/, fixing a pre-existing dead link in the footer and in-page content). This is enforced by a committed URL inventory (scripts/url-inventory.txt) diffed in CI on every build.pnpm run check(URL inventory / i18n parity / frontmatter lint scripts) and a Gitea Actions CI workflow that runs it on every PR.onBrokenLinks: "warn"had let ship; flipped to"throw".id:/sidebar_position:frontmatter overrides that existed only to work around mismatched filenames, and made all three sidebars (use/dev/change) fully explicit insidebars.js.<doc-name>.assets/sibling directory (matching the convention already used bydev/background.assets/etc.), splitting/merging folders that had been shared across multiple docs.title(the only title source now; sidebar/browser-title/H1 mismatches are impossible by construction) and fixed the specific mismatches, including the VSCode one reported.dev/including the whole Agent section, plusabout/and 5 changelog entries), so the English site no longer silently falls back to Chinese content.Also added
CONTRIBUTING.mddocumenting these conventions for future contributors/agents.Test plan
pnpm run build— clean build, zero broken links/anchors/images, both locales (onBrokenLinks/onBrokenAnchors:throw)pnpm run check— URL inventory (94/94 routes match baseline), i18n parity (41/41 docs translated), frontmatter lint — all pass in strict modegit mv+ rebuild that renames introduced zero URL drift, including one non-obvious case (use/use.md's slug auto-collapsing when the filename matches its parent directory name — pinned with an explicitslug:override)🤖 Generated with Claude Code