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,75 @@
+# Reference-inspired documentation portals
+
+Use this reference when a user selects an existing Docusaurus site as the visual and entry-page model for another documentation portal.
+
+## Selection workflow
+
+1. Inspect the exact URL the user selected; similarly named domains can present different products and layouts (for example, a documentation portal versus a community wiki).
+2. Extract structural principles rather than cloning branded content:
+   - navigation hierarchy;
+   - hero composition;
+   - discovery groups;
+   - card/link density;
+   - typography posture;
+   - palette and surface relationships;
+   - responsive collapse behavior.
+3. Map the target repository's real information architecture into those patterns. Do not invent fake metrics, features, or portfolio content.
+4. Preserve explicit user constraints even when the reference violates them. A selected reference is a direction, not permission to override established design rules.
+5. When presenting alternative references, track prior suggestions and exclusions. If the user requests “new options,” do not repeat any previously proposed option.
+
+## Dedicated homepage pattern
+
+When the docs plugin already owns `/`:
+
+1. Move its introduction to a stable route such as `/overview/`.
+2. Add `src/pages/index.tsx` and a CSS Module for the dedicated landing page.
+3. Keep registry and detail routes unchanged.
+4. Build with broken-link checking enabled and verify both `build/index.html` and `build/overview/index.html`.
+
+## Sharp-rectangle adaptation
+
+For a user who explicitly rejects rounded shapes, enforce the rule at both token and rendered-component levels:
+
+```css
+:root {
+  --ifm-global-radius: 0;
+  --ifm-code-border-radius: 0;
+  --ifm-pre-border-radius: 0;
+  --ifm-alert-border-radius: 0;
+  --ifm-button-border-radius: 0;
+  --ifm-badge-border-radius: 0;
+  --ifm-card-border-radius: 0;
+  --ifm-pagination-nav-border-radius: 0;
+}
+
+*, *::before, *::after {
+  border-radius: 0 !important;
+}
+```
+
+The universal override is intentionally forceful. Use it only when the no-rounding requirement is global. Verify the minified production CSS contains the override, not just the source file.
+
+## IOTA Docs-inspired posture
+
+General principles observed from `https://docs.iota.org/` that transfer well to an original governance or ecosystem portal:
+
+- dark technical canvas with one restrained teal accent;
+- large editorial hero with a concise purpose statement;
+- clear “Discover” groups that route users by task or domain;
+- compact monospace eyebrow labels;
+- bordered grid composition with low-elevation surfaces;
+- content-rich cards whose lower rows act as direct navigation;
+- a secondary section that explains the operating model or platform value;
+- responsive collapse from multi-column grids to one column.
+
+Do not reproduce IOTA names, claims, illustrations, or exact branded layout. Translate the hierarchy and visual posture to the target content.
+
+## Verification
+
+- Typecheck and production build pass.
+- Root and relocated overview routes both exist.
+- Distinctive landing-page markers appear in built HTML.
+- Global shape rule appears in compiled CSS.
+- Responsive grids collapse without horizontal overflow.
+- Real CI completes successfully.
+- Protected Pages deployments are verified through an authorized browser or the internal service proxy, with content markers rather than status alone.