feat: add sidebar validation and update API docs structure - #1229
Conversation
The API sidebar in sidebars.js is maintained by hand while the docs under docs/latest are synced from electron/electron, so new API pages were regularly landing with no sidebar entry (25 at the time of this change). - Generate the "API Structures" category from docs/latest/api/structures with an `autogenerated` sidebar item, sorted by doc id via a `sidebarItemsGenerator` so `certificate` still precedes `certificate-principal`. - Add `scripts/check-sidebars.ts` (run as `lint:sidebars` from `lint`) which fails when an API doc has no sidebar entry or a sidebar entry points to a missing doc. - Add the unlisted ClipboardItem, IpcMainServiceWorker and WebSocket classes and the `-electron-corner-smoothing` CSS rule, renaming "Custom DOM Elements" to "Custom Web Features" to match upstream. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMfdywBDQap5GoK4NkEFTE
erickzhao
changed the title
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
I reviewed this PR and didn't find any bugs. Because docusaurus.config.ts, package.json, and sidebars.js fall outside docs/ and are covered by the @ electron/wg-ecosystem CODEOWNERS entry, a human review from that team is still worthwhile.
What was reviewed:
- Cross-checked all 76 top-level API docs against the sidebars.js
apisection: full coverage, no missing or orphaned entries. - Confirmed the new
autogenerateditem forlatest/api/structurescovers all 102 structure docs on disk, several of which were absent from the old hand-maintained list. - Verified the "Custom DOM Elements" -> "Custom Web Features" rename is applied consistently in sidebars.js and the i18n label in current.json.
- Checked the check-sidebars.ts doc-id collection/validation logic and the new sidebarItemsGenerator sort key in docusaurus.config.ts for correctness.
Extended reasoning...
The change adds scripts/check-sidebars.ts (a new lint step wired into npm run lint) plus edits to docusaurus.config.ts, package.json, sidebars.js and one i18n label file, touching no auth/crypto/permission code and no injection or data-exposure surface. I manually cross-referenced every file under docs/latest/api and docs/latest/api/structures against the new sidebars.js and confirmed full, exact coverage with no gaps or leftovers, and confirmed the category rename was applied everywhere. The repo's CODEOWNERS wildcard (* @ electron/wg-ecosystem, with only /docs/ carved out) covers all five changed files here, which is the deciding factor for deferring rather than approving outright, since this is not a change docusaurus/website-only automation is meant to bypass human sign-off on.
| 'latest/api/structures/shared-dictionary-info', | ||
| 'latest/api/structures/shared-dictionary-usage-info', | ||
| ], | ||
| items: [{ type: 'autogenerated', dirName: 'latest/api/structures' }], |
3 participants
Description of Change
This PR adds automated validation for the sidebar configuration and makes several updates to the API documentation structure:
New Features:
scripts/check-sidebars.ts- a validation script that ensures:docs/latest/apihas a corresponding sidebar entry (directly or viaautogenerateddirectives)sidebars.jspoints to an existing file on disknpm run lint:sidebarsSidebar Updates:
clipboard-item,ipc-main-service-worker,web-socketcorner-smoothing-cssto the Custom Web Features categoryautogenerateddirective forlatest/api/structures/directoryConfiguration Improvements:
docusaurus.config.tsto customize the sidebar item generator for autogenerated items, ensuring they sort by doc ID rather than file path (socertificate.mdappears beforecertificate-principal.md)Checklist
https://claude.ai/code/session_01XMfdywBDQap5GoK4NkEFTE