76 lines
3.3 KiB
Markdown
76 lines
3.3 KiB
Markdown
# 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.
|