Skip to main content

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 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 /docs/...; 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

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

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

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 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

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

Edit this page on GitHub