Documentation site

The documentation is a Docusaurus 3 application under Docs. Use Node.js 22 and npm.

Run locally

cd Docs
npm ci
npm run dev

Open the local documentation. Development and GitHub Pages use the same /Hyprism/docs base path.

Content and languages

English pages live under content/en, Russian under content/ru. Both trees must contain the same routes. The selected language changes content at the same public URL and is saved in the browser.

plugins/localized-docs discovers MDX pages, extracts search text, reads navigation metadata, and rejects missing translations. src/i18n.ts contains the site interface strings.

Use explicit, matching heading IDs in both languages when another page links to that section.

## Downloads {/* #downloads */}

Internal documentation links use route paths such as /getting-started/...; the MDX theme link applies the deployment base path. Write source links relative to the MDX file, for example ../../../../Sources/Hyprism.Core/Models/Config.cs. The repository-link plugin verifies each target and converts it to a GitHub source link when building.

Navigation and icons

Each directory's _meta.ts defines page order and labels. Its icon field describes that category, not its child categories.

export default {
  icon: 'code-blocks',
  building: 'Building',
  testing: 'Testing',
  packaging: 'Packaging and releases'
}

The five top-level categories use local SVG paths from Google's Material Symbols Rounded. MaterialSymbol.tsx owns the icon set, which is bundled without a remote font request.

Brand and theme

src/css/custom.css owns the dark Hyprism Launcher visual system for the navbar, documentation frame, home page, code examples, responsive layout, and footer. The theme uses the local Google Sans and JetBrains Mono files under static/fonts and the launcher mark at static/img/hyprism-logo.svg.

src/theme/Footer/index.tsx owns the large team-site call to action and the links below it. Keep its English and Russian labels in src/i18n.ts when the footer changes.

DocsSidebar.tsx renders the category tree in the left column on wide screens. At compact widths Navbar/MobileSidebar/index.tsx renders the search field and the same tree in a full-viewport panel below the existing navbar. The panel follows the language switcher interaction pattern, closes on outside click, Escape, or navigation, and does not render a second header.

Examples and prose

Follow AGENTS.md: user guides describe actions and results, while technical pages describe responsibilities, contracts, and maintenance constraints.

Every code fence needs a language. Use bash, powershell, csharp, json, xml, typescript, or text as appropriate. Explain prerequisites and results outside the example.

LocalizedDocPage wraps content with the Docusaurus MDXContent provider. This enables the theme's headings, links, admonitions, and highlighted code blocks. Prism grammars are configured in docusaurus.config.ts.

Screenshots

Documentation captures render the actual Avalonia views with deterministic sample profiles, instances, and service responses. They demonstrate the interface, not a live game session or current external news.

From the repository root:

HYPRISM_DOCS_SCREENSHOTS="$PWD/Docs/static/img/user" \
  dotnet test Tests/Hyprism.Desktop.Tests/Hyprism.Desktop.Tests.csproj \
  --filter FullyQualifiedName~DocumentationScreenshotTests

The test writes English and Russian PNGs under Docs/static/img/user/en and ru. It runs only when the output variable is set. The actual views are rendered at 2× pixel density into PNG, without enlarging an existing bitmap. Dialog captures render only the relevant real control.

The run refreshes bilingual images of the first-run download warning, instance and profile managers, instance creation wizard, news feed and article, download, general, Java, and GPU settings, Java argument dialog, and selection controls. The first-run guide, settings guide, news guide, and desktop UI reference use these captures.

Use the matching language image, write useful alternative text, and link to the original image for full-size inspection. Crop dialogs or pickers only when the surrounding window is irrelevant. Review every updated capture for missing data, clipped controls, and unfinished transitions.

Validate and export

cd Docs
npm ci
npm run check
PAGES_BASE_PATH=/Hyprism/docs npm run build

npm run check validates prose, language parity, code fences, local images, internal routes, explicit bilingual anchors, repository links, and Core contract documentation, then runs TypeScript checks. The static export goes to Docs/out/docs. GitHub Pages adds the project path /Hyprism, so the published site is available at /Hyprism/docs/.

Check highlighted C#, shell, JSON, and XML examples in the rendered site, plus language switching, section links, sidebar icons, and narrow-window layout.

Publishing

docs-pages.yml validates and publishes the static export. In repository Settings → Pages, the source must be GitHub Actions.

The published entry point is the Hyprism documentation site. Do not commit out, .docusaurus, node_modules, or obsolete .next build products.

Source: AGENTS.md, DocumentationScreenshotTests.