feat: merge Docusaurus and Gitea documentation skills

2026-08-14 12:32:08 +00:00
parent cfb006d7ea
commit b08614dc90
28 changed files with 4202 additions and 1 deletions
@@ -0,0 +1,65 @@
+# Behavioral acceptance for Docusaurus documentation portals
+
+Use this gate when a request includes interactive behavior such as theme switching, section navigation, or local search. A successful build and Actions run prove compilation/publication only; they do not prove the requested behavior works.
+
+## Requirement-to-proof matrix
+
+Write the matrix before implementation and require one direct proof per request:
+
+| Requirement | Source/config proof | Built-artifact proof | Browser proof |
+|---|---|---|---|
+| Light/dark mode | `disableSwitch: false`; separate light/dark tokens | both selectors present in compiled CSS | click toggle; verify `data-theme`, persisted theme, and computed colors all change |
+| Dedicated section sidebars | separate docs-plugin instances, sidebar files, and `docSidebar` navbar items | each section route renders its own sidebar labels | open every top-menu section and inspect `Docs sidebar`; ensure unrelated section labels are absent |
+| Local search | local-search dependency/theme configured; no hosted provider | generated search index contains representative terms from every docs instance | type a query, wait for loading to end, confirm a visible result, and open it |
+
+Do not report completion until every requested row has a browser proof or an explicitly stated blocker.
+
+## Multi-section sidebars
+
+A differently named category inside one shared sidebar is not a dedicated sidebar. For top-level menu areas that must own navigation:
+
+1. Keep one default docs instance for overview/global theme compatibility.
+2. Add one `@docusaurus/plugin-content-docs` instance per section with a unique `id`, content `path`, `routeBasePath`, and `sidebarPath`.
+3. Give each sidebar an independently named root, such as `projectsSidebar`.
+4. Configure each navbar entry as `type: 'docSidebar'`, with both `docsPluginId` and `sidebarId`.
+5. Give each section index `slug: /` relative to its plugin route.
+6. Build and inspect every top-level route, not only the source configuration.
+
+## Static local-search verification
+
+Use `@easyops-cn/docusaurus-search-local` as a theme and include every docs route base in `docsRouteBasePath`. Search must remain static/browser-local, with no Algolia or hosted crawler credentials.
+
+Prefer `hashed: 'filename'` on static hosting that redirects requests carrying query strings. With `hashed: true`, the theme fetches `search-index.json?_=HASH`; a host that redirects query-string asset requests can leave the search field indefinitely loading even though `search-index.json` exists. Filename hashing emits and fetches `search-index-HASH.json` directly.
+
+Verification:
+
+1. Assert exactly one `search-index*.json` exists in `build/`.
+2. Inspect it for representative terms from overview and every docs plugin.
+3. Serve the production build under the real configured `baseUrl`.
+4. Type a representative query in the navbar.
+5. Confirm loading ends and a visible result appears.
+6. Open the result and verify its route.
+7. After deployment, fetch the exact generated hashed index from the Pages backend and repeat term checks.
+
+## Theme debugging
+
+If the toggle exists but the appearance does not change, inspect hard-coded colors before changing Docusaurus configuration. Typical root causes are:
+
+- `html, body` fixed to the dark background;
+- navbar/sidebar/footer colors fixed with `!important`;
+- custom homepage CSS modules defining only dark values;
+- light and dark Prism themes configured identically.
+
+Move component colors behind semantic variables. Define a complete light palette in `:root, [data-theme='light']` and dark overrides in `[data-theme='dark']`. For CSS modules, use `:global([data-theme='light']) .page` to override page-level tokens. Browser verification must compare computed colors, not only the `data-theme` attribute.
+
+## Reporting discipline
+
+Do not substitute these for behavioral acceptance:
+
+- local TypeScript success;
+- production-build success;
+- successful CI;
+- a deployed HTML marker;
+- presence of the toggle/search input/sidebar container.
+
+Those are supporting checks. Report the pipeline only after matching it to the intended commit SHA, and report the feature only after exercising it.