Documentation site

All documentation lives in Docs/, laid out as on the Aspid.FastTools site. The UPM package holds no docs or media: only code, assets, sample scenes and license texts. The repository root keeps README.md and the English CHANGELOG.md, which GitHub and Unity read as they are; its Russian twin is Docs/i18n/ru/CHANGELOG.md. Pages are GitHub Flavored Markdown, so GitHub renders them too; the site adapts to them, never the other way round.

Sections

The navbar (on desktop, the section switcher of the sidebar panel) has five sections, one docs plugin instance each, all configured in Docs/docusaurus.config.js:

The section switcher builds itself from the navbar items. The search index (src/plugins/search/index.js, a label per plugin id) and the search bar (src/theme/SearchBar/index.js, the Russian labels) keep their own section names, so a new section needs an entry in both.

Other files:

Tracked and generated

Every page and translation is tracked where Docusaurus reads it, so the "Edit" links open that file (editUrl + editLocalizedFiles). Only the changelog is generated, before start and build (npm run sync):

Docs/scripts/sync-changelog.mjs (with changelog-page.mjs) turns the root CHANGELOG.md into Docs/changelog/index.md plus a version list Docs/changelog/sidebars.json, and each tracked translation Docs/i18n/<locale>/CHANGELOG.md into Docs/i18n/<locale>/docusaurus-plugin-content-docs-changelog/current/index.md. Relative links to other repository files open them on GitHub; last_update comes from the source file's last commit.

Docs/.gitignore ignores exactly those outputs (changelog/, i18n/*/docusaurus-plugin-content-docs-changelog/current/), plus build/, .docusaurus/, node_modules/ and docfx/projects/. i18n/ru/docusaurus-plugin-content-docs-changelog/current.json is tracked. Edit the English changelog in the repository root and the Russian one in Docs/i18n/ru/CHANGELOG.md, never the generated pages.

Docs/docs/SUMMARY.md is a GitBook leftover kept as the GitHub table of contents; the site excludes it.

Writing rules (so GitHub and the site agree)

• Front matter only where a page needs it (tutorials/index.mdx); a page takes its title from the first # H1, slug and order from the file or folder name.
• Admonitions: GitHub style only (remark-github-admonitions-to-directives converts them).

  > [!NOTE]
  > Text.

  Allowed: NOTE, TIP, IMPORTANT, WARNING, CAUTION. Never :::note.
• One # H1 per file. Extra H1s in the body get no anchor id on the site; use ##.
• Anchors to headings must match a heading that exists; CI fails on stale ones (onBrokenAnchors throws when CI is set, a local build only warns).
• Images are referenced relatively; a -light twin next to an image is shown in the light theme (src/remark/themedImages.js).
• Sample tutorials: keep the sample facts at the top (scene table, files) and the fonts note at the bottom; the tutorial body goes between. The sample's scenes and code stay in Samples~/<Sample>/ in the package.
• Translations mirror the English page under Docs/i18n/ru/<plugin>/current/ with the same path and link the translated targets, so GitHub stays in one language. Shared images are linked from Docs/docs/Images/ (../../../../docs/Images/x.png from a translated doc). A missing translation falls back to the English page.
• Adding a language: add the locale to LOCALES and localeConfigs in docusaurus.config.js, its folders under Docs/i18n/<locale>/, and its section labels in the search bar.

Links between pages and sections

Links are relative paths to the .md file, spaces as %20, so GitHub follows them as files. onBrokenLinks and onBrokenMarkdownLinks are throw: a bad link breaks the build on purpose.

• Inside one section Docusaurus resolves the file link itself: [Greeter](../02.%20Greeter/README.md).
• Docs ↔ Tutorials (and their translations): file links too, [Binders](../../docs/06-binders.md) from a tutorial, [Counter](../tutorials/01.%20Counter/README.md) from a doc. src/remark/crossInstanceLinks.js resolves them against the page's file and rewrites a target in the other instance to its route (no locale prefix; Docusaurus adds it). Translated pages link translated targets: ../../docusaurus-plugin-content-docs-tutorials/current/01.%20Counter/README.md, ../../../docusaurus-plugin-content-docs/current/09-collections.md.
• Migration, Changelog, API: crossInstanceLinks.js knows only Docs and Tutorials, so links into or out of these sections are absolute site URLs, with /ru/ in a translation: https://vpdpersonal.github.io/Aspid.MVVM/changelog#v1-1-0, https://vpdpersonal.github.io/Aspid.MVVM/ru/migration/1.1. The root changelogs link the migration guide the same way.
• Otherwise never link by site URL. The introduction (Docs/docs/README.md) is the exception: introBanner.js turns its absolute site links into routes.

Slugs and ids

samplePrefixParser in docusaurus.config.js turns a tutorial folder name into a slug: 01. Counter → counter (position 1), VirtualizedList → virtualized-list, DynamicViewModel → dynamic-view-model. README.md is the folder's index document, so the route is /tutorials/counter and the doc id in sidebarsTutorials.js is counter/readme. crossInstanceLinks.js has a copy of the same slug rules (tutorialSlug); change both together.

Main docs use the default parser: 03-binding-modes.md → /docs/binding-modes, StarterKit/README.md → /docs/StarterKit, docs/README.md → /docs. Migration guides keep the file name: 1.1.md → id 1.1, route /migration/1.1. The site root / redirects to /docs (Docs/src/pages/index.js).

Adding a main doc page

Drop the file into Docs/docs/ (a numbered prefix NN- orders it), add its id to a category of Docs/sidebars.js (StarterKit pages are autogenerated) and to SUMMARY.md. Optionally add the translation at Docs/i18n/ru/docusaurus-plugin-content-docs/current/<same path>.

Adding a tutorial / sample

1. Create the sample in Samples~/<NN. Name>/ (scenes, scripts, .meta files) and register it in the package package.json → samples.
2. Write the tutorial at Docs/tutorials/<NN. Name>/README.md; optionally its translation at Docs/i18n/ru/docusaurus-plugin-content-docs-tutorials/current/<NN. Name>/README.md.
3. Add <slug>/readme to Docs/sidebarsTutorials.js under Path or Features, and a card to Docs/src/components/SamplesGallery/index.js.

Adding a migration guide

One guide per minor version, written while the version is developed: every removed or changed public member gets a note in the guide of the next version.

1. Create Docs/migration/<major.minor>.md (# Migration Guide: 1.1 → 1.2, no front matter) and its translation at Docs/i18n/ru/docusaurus-plugin-content-docs-migration/current/<major.minor>.md.
2. Add { type: 'doc', id: '<major.minor>', label: '1.1 → 1.2' } at the top of the Versions category in Docs/sidebarsMigration.js: the navbar opens the first doc, so the newest guide goes first.
3. Point the links at the new guide: the Migration item in the introduction (Docs/docs/README.md and its translation) and the version's section in CHANGELOG.md / Docs/i18n/ru/CHANGELOG.md, all absolute site URLs.

Versioning

Cut a version of the main docs when the package version is released:

cd Docs
npm run version 1.1.0          # docusaurus docs:version → Docs/versioned_docs/version-1.1.0

The current docs are labelled with the package version from the working tree (versions.current.label). Tutorials, migration guides and the changelog are not versioned: a tutorial always describes the sample of the package version in the working tree, and each migration guide is its own file. The site has no version dropdown; a docs snapshot keeps its own pages.

Local run / check

cd Docs
npm ci
npm start                # http://localhost:3000/Aspid.MVVM/ (prestart syncs the changelogs)
npm run start:ru         # Russian locale (the dev server serves one locale at a time)
npm test                 # unit tests of the site scripts and remark plugins (CI runs them)
npm run build            # what CI runs; fails on broken links (and anchors when CI is set)
npm run check-selectors  # after a build: hashed Docusaurus classes the CSS selects still exist
Docs/scripts/serve-all.sh  # build + serve detached, one port per checkout (main: 3002)

API reference (/api)

The API tab is generated from the XML doc comments by DocFX, not written by hand. Docs/api/ holds the generated Markdown plus sidebar.js and is committed: DocFX has to compile the assemblies against the local Unity installation, which CI does not have.

dotnet tool install -g docfx        # once
cd Docs && npm run api              # regenerate after public API or XML doc changes

npm run api runs three steps (Docs/scripts/docfx-*.mjs, Docs/docfx/docfx.json):

1. docfx-projects.mjs rewrites the legacy .csproj files Unity generates (Aspid.MVVM, Aspid.MVVM.Unity, Aspid.MVVM.StarterKit) into SDK-style projects under Docs/docfx/projects/ (gitignored, absolute paths) with the same files, references, defines and the source generators as analyzers. Unity must have regenerated the .csproj files and Library/ScriptAssemblies first (open the project once).
2. docfx metadata writes one Markdown page per type into Docs/api/.
3. docfx-postprocess.mjs makes it MDX-safe: <xref> → links (own pages, learn.microsoft.com, Unity Scripting Reference), <pre><code> → fenced code, heading anchors as {#id}, escaped <T/{}, no "Inherited Members", front matter with a short sidebar_label, and toc.yml → sidebar.js (namespace → Classes/Interfaces/… groups).

sidebarsApi.js reshapes api/sidebar.js for navigation (a section per namespace, folder groups, "Global" for types outside a namespace). Never edit files in Docs/api/ by hand; fix the XML comment or the postprocess script and regenerate. Translations are not generated; the ru locale falls back to the English pages.

Design

The site is the Aspid.FastTools site (Aspid.FastTools/Website) with MVVM content: when one of them changes its theme or components, port the change to the other. Theme "Venom": acid green on near-black, light mode is neutral paper; the accent can be switched to red, blue, yellow or mono (Docs/src/accents.js, src/css/accents.css, the logos in Docs/static/img/logo*.png are the package icons from Unity/Editor/Resources/Icons). Fonts: IBM Plex (self-hosted from @fontsource, src/css/fonts.css) and iA Writer Quattro (src/fonts/).

• No navbar on desktop: the doc sidebar is the whole chrome (src/components/NavigationPanel): brand, section switcher, search (src/theme/SearchBar + src/plugins/search, a local index built at build time), the doc list, and a footer with GitHub, Asset Store, language and appearance. Below 997px the same panel is the mobile drawer.
• src/theme/Root: the dot-grid background with its ambient glow, spotlight and click ripples (src/components/Dot*).
• src/theme/DocItem/Layout: the article panel, a floating TOC below 1400px (FloatingToc), the footer inside the article column. src/theme/MDXComponents/Img: zoomable images.
• The introduction (Docs/docs/README.md) is rebuilt by src/remark/introBanner.js: the Images/Aspid.MVVMHeaderImage.png banner becomes the animated IntroBanner (src/intro.js arms its entrance), and, when the README follows the FastTools layout, status-badge-*.svg badges become chips, the install section with a .git#upm… URL the InstallPanel, #### feature headings cards, a [Link](…) — summary list tiles, the help section a SupportPanel and the donation sentence a DonatePanel. Absolute links to the site become routes.
• Other remark plugins shared by Docs, Tutorials and Migration: agentPrompt.js (a ```text prompt block followed by a table becomes one AgentPrompt frame) and liveDiagrams.js (a static SVG, table or ordered list gets its animated site component; the Markdown keeps the static version for GitHub).
• A feature card can play a live preview instead of its README code block: register a component under the doc slug in PREVIEWS of src/components/FeaturePreview (ViewModels, Binding Modes and Commands have one).
• Docs/tutorials/index.mdx is the tutorials overview (/tutorials): a card per sample from src/components/SamplesGallery. Add a new sample there too; a card shows its step until it gets a capture. The captures are dark/light GIF pairs in Docs/static/img/samples/, recorded in a hidden batch-mode Editor by Docs/media/samples-gallery/ (its README has the steps); capture: true on a card shows them.
• src/prism/venom.js: Prism themes in the Ayu palette.
• The site root / redirects to /docs (src/pages/index.js); there is no landing page.

Check both themes after a change: build, npx docusaurus serve, and look at it in a browser (set localStorage.theme = 'light', and localStorage['aspid-accent'] for an accent; defaultMode is dark). Do not run npm run build while a dev server is running from the same folder: they share .docusaurus/, i18n/ and node_modules/.cache, and the dev server starts crashing with Cannot read properties of undefined (reading 'id'). Build a copy of Docs/ (with a real copy of node_modules, not a symlink) instead, or stop the dev server.

Deploy

.github/workflows/docs.yml runs npm ci, npm test and npm run build on every push to main touching Docs/, a root changelog or the workflow, on such PRs (build only, no deploy) and on a manual run; a push or a manual run then deploys Docs/build to GitHub Pages. Pages source must be set to "GitHub Actions" once in the repository settings.