Documentation Site Publication

Engine-owned documentation. This page defines how the FOnline Markdown corpus is previewed, validated, and published through the existing GitHub Pages route.

The layout includes root VERSION through Jekyll’s standard include tag; includes_dir: . makes that single source available in local builds and the ordinary GitHub Pages build alike. No copied version or preparation step is required. Publish /VERSION byte-for-byte with /docs-manifest.json; route and translation reports are sections of that shared index.

Search-result summaries are limited to 224 characters including the ellipsis, with truncation at a word boundary. Full-document search terms and scores are retained; the search-index byte limit remains unchanged.

Purpose

Use this page when changing Docs/Site/_config.yml, the documentation rendering layer, the custom domain, or the documentation jobs in GitHub Actions. It does not authorize a separate documentation application or a second content tree: repository Markdown remains canonical.

Source paths inspected

• Docs/Site/_config.yml
• BuildTools/docs_prepare.py
• BuildTools/docs_site_build.py
• BuildTools/documentation_metadata.py
• BuildTools/tests/test_docs_site_build.py
• .gitignore
• .github/workflows/validate.yml
• Docs/documentation-manifest.json
• BuildTools/docs_ai_delivery.py
• BuildTools/tests/test_docs_ai_delivery.py
• BuildTools/docs_ai_eval.py
• BuildTools/tests/test_docs_ai_eval.py
• BuildTools/SnippetPolicy.json
• BuildTools/docs_snippets.py
• BuildTools/tests/test_docs_snippets.py
• BuildTools/DocumentationDiagrams.json
• BuildTools/docs_diagrams.py
• BuildTools/tests/test_docs_diagrams.py
• BuildTools/DocumentationScreenshots.json
• BuildTools/docs_screenshots.py
• BuildTools/tests/test_docs_screenshots.py
• BuildTools/docs_site.py
• BuildTools/tests/test_docs_site.py
• BuildTools/tests/test_docs_site_layout.py
• BuildTools/docs_site_artifact.py
• BuildTools/tests/test_docs_site_artifact.py
• Docs/Site/Layouts/default.html
• Docs/Site/Assets/css/docs.css
• Docs/Site/Assets/js/docs.js
• Docs/Site/Assets/images/fonline-mark.svg
• Docs/Site/Data/docs-site.json
• Docs/Site/Assets/docs-search.json
• Docs/Site/Assets/docs-search.ru.json
• docs-manifest.json#/routing
• Docs/ai-evaluation.json
• Docs/generated/ai-evaluation-report.json
• Docs/generated/snippets.json
• Docs/generated/diagrams.json
• Docs/assets/diagrams/
• Docs/generated/screenshots.json
• Docs/assets/screenshots/
• llms.txt
• llms-full.txt
• docs-manifest.json
• Docs/en/contributing/decisions/0001-github-pages-markdown-publication.md
• Docs/en/contributing/decisions/0003-manifest-backed-ai-documentation-delivery.md
• Docs/en/contributing/decisions/0004-manifest-backed-site-navigation-search.md
• Docs/en/contributing/decisions/0006-documentation-version-locale-routing.md

Production contract

Before Jekyll, run python BuildTools/docs_prepare.py. The twelve delivery files are ignored build outputs, including both llms endpoints, the shared manifest, navigation/search, and validation catalogs. Public contract models, authored Markdown, reviewed image sources and translations remain versioned. A clean checkout does not need the llms files for agent work: AGENTS.md routes maintainers to source guides.

Production uses the validated artifact from documentation-site, deployed by documentation-publish only on a push to cvet/fonline master, after version and documentation gates pass. Pull requests and release branches produce review artifacts. On 2026-10-09 the owner selected Settings → Pages → Build and deployment → Source → GitHub Actions; the authenticated Pages API confirms build_type: workflow and cname: fonline.ru. The first deployment of the new workflow still needs verification after publication. The former branch build cannot run Python preparation; generated CNAME, domain and public URLs retain their existing meaning.

The publication route is intentionally independent from any embedding game project. Last Frontier, TLA, and public example games may link to this site, but they neither build nor define it.

Website source ownership

The website implementation lives under Docs/Site/: Layouts/ owns the HTML shell, Data/ owns generated navigation, and Assets/ owns styles, scripts, branding, and generated locale search indexes. Docs/Site/_config.yml sets layouts_dir: Docs/Site/Layouts and data_dir: Docs/Site/Data; both source-only directories are excluded from the published tree. The static asset URLs use /Docs/Site/Assets/ and are checked against the same generated manifest.

Jekyll reads canonical Markdown from the repository root with the explicit configuration path. BuildTools/docs_prepare.py generates Gemfile, .ruby-version and CNAME from the source manifest’s dependency pins and domain, alongside llms.txt, llms-full.txt and docs-manifest.json, under ignored Workspace/Documentation/. Bundler settings and Gemfile.lock belong in that directory too. These files have no versioned copies at the repository root. BuildTools/docs_site_build.py prepares the inputs, renders into Workspace/DocumentationSite/ and exports the three public endpoints plus CNAME to the rendered root. Public URLs and logical manifest artifact paths stay unchanged. Repository layout changes must update generators, source provenance, locale mirrors and rendered-site checks together.

GitHub Pages uses jekyll-readme-index, which normally changes a nested README.md route to the directory index. The seven public root/subsystem/example READMEs therefore pin their manifest-owned .html routes in short YAML front matter blocks. Docs/Site/_config.yml excludes local build trees, third-party inputs, private example governance templates, and BuildTools subtrees that do not own public pages while retaining the source files referenced by the docs. Removing a pinned permalink creates a route that the catalog promises but Jekyll does not render and fails source-level plus post-build validation.

Managed bin and obj directories below Source/Scripting/Managed/ are build outputs at any project depth. Exclude them with directory globs without a trailing slash; the artifact audit rejects any published file inside them while retaining authored source files.

Ordinary index.md pages use Jekyll’s canonical directory URL (/path/), while their artifact remains /path/index.html. BuildTools/docs_site.py records the directory form in navigation, search, locale reservations, and the route catalog so canonical tags and published links agree with GitHub Pages.

Manifest document records with visibility: internal and generated artifacts with the same visibility are source-only maintainer evidence. Docs/Site/_config.yml must exclude their canonical paths and any repository pointer paths from GitHub Pages, while BuildTools/docs_ai_delivery.py must omit internal models from the public AI bundle. BuildTools/docs_site_artifact.py fails the rendered artifact when any internal Markdown, JSON, index, or rendered HTML variant is present. Public documentation may point maintainers to these files through a GitHub source URL, but it must not promise a same-domain route for them.

Reader navigation and static search

The public site wraps normal Jekyll-rendered Markdown in Docs/Site/Layouts/default.html. The layout adds a persistent desktop sidebar, mobile navigation, page-local table of contents, source link, code-copy controls, light/dark preference, the Engine CalVer link to the locale’s changelog, and an EN/RU switch for current locale pairs. Its Current label and tooltip retain the rolling master channel identity. Markdown remains complete and readable when opened directly in GitHub; the layout owns no technical prose. Engine versioning defines the VERSION source; generated site/route and AI manifests carry it in their engine object separately from documentation-channel version.

Docs/documentation-manifest.json owns the navigation groups by stable document ID. BuildTools/docs_site.py resolves those IDs to current titles and paths and writes:

Every public current human top-level page must appear exactly once in navigation. Generated detail pages stay out of the sidebar but remain searchable behind their generated index pages. Internal plans, placeholders, and AI-only maintainer routes appear in neither reader surface.

Search uses repository-owned JavaScript and browser APIs only. There is no hosted index, account, analytics dependency, remote script, or server endpoint. The rendered page loads only its active locale index, and result routes remain in that locale. Titles and headings receive more weight than body terms; complete technical identifiers and camel-case components remain searchable. Pure numeric components and terms present in more than 60% of a locale corpus are omitted because they cannot usefully distinguish results. Compact JSON is emitted as UTF-8 instead of expanding non-ASCII text into \\uXXXX escapes, so the Russian budget measures actual text bytes. The source manifest enforces the reviewed 1.78125 MiB (1,867,776-byte) hard limit independently for each generated index. The limit is capacity for the complete bilingual corpus, not permission to omit documents; generation still fails closed when either locale exceeds it.

Regenerate after changing public Markdown membership, titles, paths, lifecycle state, migration targets, version/localization policy, navigation groups, or search policy:

python BuildTools/docs_site.py --write
python BuildTools/docs_site.py --check

When visual, fenced, or delivery layers change, generate diagrams and the screenshot catalog first, the snippet report second, translation status third, site data fourth, the AI evaluation report fifth, and AI delivery last. The evaluation consumes the site search model, while public docs-manifest.json records diagram, screenshot, snippet, machine-model, evaluation, navigation, search, and route-catalog hashes. Never edit generated delivery data by hand. Presentation changes belong in the layout or local assets; navigation/search/routing ownership changes belong in the source manifest. The accepted boundaries are recorded in Documentation Snippet Validation, ADR-0004, ADR-0006, AI Documentation Evaluation, and Translation Workflow.

Search ignores hidden translation comments and empty HTML anchors outside fenced or inline code. Anchor markup remains in the authored page and routes; visible text and stable IDs remain searchable. Literal markup examples are indexed.

Version, locale, and route migration

The unversioned production site is the current channel. It follows rolling master, and the layout labels it Current; it does not claim that master is a stable release. Historical review uses repository revisions and commit-addressable Workspace/DocumentationSite artifacts.

Tagged release snapshots are deliberately deferred. The manifest reserves /versions/{version}/, but no release page is generated until the engine has immutable supported tags, a support matrix, and an approved follow-up decision. VERSION, a branch, or a reachable tag must not silently create a supported documentation line.

The localization policy is also source-owned:

• en is canonical; manifest-owned human pages use their current paths below Docs/en/ or an explicit repository/subsystem README entrypoint;
• ru is a complete mirror; this revision has all required counterparts under fail-closed parity enforcement;
• paths below Docs/en/ mirror directly below Docs/ru/;
• root and subsystem README pages use explicit pairs such as README.md and README.ru.md;
• BuildTools/docs_localization.py computes normalized SHA-256 for every canonical English source and rejects stale or mismatched existing Russian pages;
• docs-manifest.json#/translation_status currently reports exact required/current/missing coverage;
• stable-ID language switching and locale-scoped search are active for every required pair; manifest enforcement is complete.

docs-manifest.json#/routing freezes the migration map before files move. Each public record carries its current route, planned canonical owner/path, locale paths, and redirect requirement. Multiple legacy pages may converge only when exactly one non-replace record owns the destination.

Each current route declares current_locale, including retired Russian pointer pages that have no translation pair. Both artifact and browser checks use that declaration when validating the rendered HTML language. An index.md pointer pins the directory permalink, matching the route catalog.

Former flat Markdown files remain durable pointers to their canonical pages, including links for old heading anchors. This preserves routes in both the GitHub repository UI and Jekyll without generated HTML or an additional redirect plugin. The generated route inventory rejects missing owners, route collisions, and stale pointer records.

AI and machine-readable routes

The static site publishes three generated root endpoints, the route catalog, and the current AI evaluation report alongside normal Jekyll-rendered Markdown:

Docs/documentation-manifest.json owns membership and policy. BuildTools/docs_ai_delivery.py owns deterministic projection only; never edit the three outputs by hand. Every public document record includes a canonical human HTML URL at fonline.ru and a source_ref-pinned clean Markdown URL at GitHub’s raw-content endpoint; llms.txt uses the Markdown route and retains an HTML link. The current GitHub Pages/Jekyll 3.10 pipeline cannot publish same-domain raw aliases without duplicating content or adding a custom plugin, so same-domain Markdown aliases remain a publication-platform task rather than a false route claim. Generated reference detail pages remain available as normal Markdown and JSON, but the full-context bundle carries their index pages rather than duplicating large method/type/property inventories.

Regenerate after any inventoried Markdown or manifest change:

python BuildTools/docs_ai_delivery.py --write
python BuildTools/docs_ai_delivery.py --check

When the search model or AI task set changes, run the complete dependency chain:

python BuildTools/docs_diagrams.py --write
python BuildTools/docs_screenshots.py --write
python BuildTools/docs_snippets.py --write --external
python BuildTools/docs_localization.py --write
python BuildTools/docs_site.py --write
python BuildTools/docs_ai_eval.py --write
python BuildTools/docs_ai_eval.py --check
python BuildTools/docs_ai_delivery.py --write
python BuildTools/docs_ai_delivery.py --check

The generator fails instead of truncating when the context bundle exceeds its declared byte budget. Content hashes use normalized LF text, so the output is byte-identical on Windows and Linux. These routes aid discovery and transport; they do not override the source precedence in the source manifest or promote an internal engine symbol to a public API.

Verified public state

The following was checked on 2026-07-10, rechecked on 2026-07-15 and 2026-08-01 from public state, and verified through the authenticated GitHub Pages API on 2026-08-02:

• The Pages API reports status built, source mode legacy, branch master, and folder /. It reports fonline.ru as the custom domain and HTTPS enforcement as enabled.
• https://fonline.ru/ and the legacy /Docs/ index return HTTP 200. Representative generated /Docs/en/ and /Docs/ru/ routes return 404 because the documentation branch has not reached master.
• The repository CNAME contains fonline.ru. Public IPv4 DNS returns the four GitHub Pages addresses 185.199.108.153 through 185.199.111.153, and www.fonline.ru is a CNAME for fonline.ru.
• The latest Pages build for remote master commit fee50fb636b5bd1e30509aded929df1fc0e95db5 completed successfully. The accompanying legacy validate workflow failed in non-documentation build lanes and does not contain the pending documentation artifact/browser jobs.
• _github-pages-challenge-cvet.fonline.ru has no public TXT record. DNS routing is confirmed, but GitHub domain-ownership verification is recorded as not-observed rather than inferred from a working custom domain.

Docs/documentation-manifest.json records the verified Pages source and the separately unresolved ownership-verification state. Update its audit date and values only from authenticated settings/API evidence plus public DNS, never from the rendered page alone. Do not replace the existing production route or weaken HTTPS while landing the documentation corpus.

DNS account names, registrar credentials, recovery codes, and GitHub credentials do not belong in this public repository. Operational ownership is shared by the repository administrators and the private domain-administration owner. Record the named account owner in the private operations inventory; this repository owns only the public domain contract and its validation.

Compatible environment

The source Docs/documentation-manifest.json owns Ruby 3.3.4, github-pages 232, and the domain. Preparation derives Workspace/Documentation/.ruby-version, Gemfile and CNAME from those values. CI uses ruby/setup-ruby@v1 with working-directory: Workspace/Documentation and Bundler caching, then the same Python build wrapper used locally. No Jekyll plugin is added.

Browser validation uses Node 24.16.0, Playwright 1.62.0 with Chromium 151.0.7922.34, and axe-core 4.12.1, pinned in the manifest and BuildTools/docs-browser/package.json plus its lock file. Before changing a render value, compare the GitHub Pages dependency versions and update the owning manifest. Browser updates require exact lock changes, focused tests and the complete route audit; never use latest in CI.

Workspace/Documentation/Gemfile.lock is ignored, following GitHub’s Pages guidance. The exact github-pages pin defines the compatibility boundary.

Local build and preview

Install the Ruby version declared in the source manifest and Bundler, then run from the engine root:

On Windows, use the RubyInstaller package with Devkit/MSYS2 support. The GitHub Pages bundle contains native gems; a bare Ruby archive can resolve the bundle but cannot compile those dependencies.

python BuildTools/docs_prepare.py --external
python BuildTools/docs_diagrams.py --check
python BuildTools/docs_screenshots.py --check
python BuildTools/docs_site.py --check
bundle install --gemfile Workspace/Documentation/Gemfile
python BuildTools/docs_site_build.py
python BuildTools/docs_site_artifact.py --site-dir Workspace/DocumentationSite
npm ci --prefix BuildTools/docs-browser
npx --prefix BuildTools/docs-browser playwright install chromium
npm --prefix BuildTools/docs-browser run audit

The rendered output is Workspace/DocumentationSite/. It is disposable and ignored by git. A successful build must finish without Jekyll or Liquid errors; Docs/Site/_config.yml enables strict front-matter parsing. Browser validation serves Workspace/DocumentationSite/ only on an ephemeral 127.0.0.1 port and writes Workspace/docs-browser-audit-report.json plus the retained screenshot set under Workspace/docs-browser-screenshots/. It never contacts production or executes documentation snippets.

For an interactive preview:

python -m http.server 4000 --bind 127.0.0.1 --directory Workspace/DocumentationSite

Open http://127.0.0.1:4000/. Stop the server before switching branches or changing the Ruby/Jekyll dependency pin. GitHub’s maintained procedure is Testing your GitHub Pages site locally with Jekyll.

Pull-request artifact

The Build documentation site job in .github/workflows/validate.yml runs after the fast standalone documentation checks. It:

1. checks out the exact pull-request or push revision;
2. runs BuildTools/docs_prepare.py, installs manifest-pinned Ruby/Bundler dependencies with ruby/setup-ruby@v1, then runs BuildTools/docs_site_build.py into Workspace/DocumentationSite/;
3. runs BuildTools/docs_site_artifact.py against the completed tree;
4. installs the manifest-pinned Node, npm lock, Chromium revision, and required Linux browser libraries;
5. runs BuildTools/docs-browser/audit.mjs against the same completed tree;
6. uploads separate static-validation and browser-validation artifacts, including the browser JSON and screenshots;
7. uploads documentation-site-<commit-sha> with actions/upload-artifact@v4 for 14 days.

The static post-build gate requires every current route and every available locale route from docs-manifest.json#/routing, verifies that static AI/search/generated-model endpoints are copied byte-for-byte, and checks canonical URLs, HTML language, one h1, skip/main landmarks, accessible image/button names, unique IDs, search targets, and links to publishable local resources.

The browser gate visits every catalog route in three manifest-owned profiles: desktop at 1440 x 1000 CSS pixels, mobile at 390 x 844 CSS pixels, and zoom-200 at 640 x 512 CSS pixels with device scale factor 2. The last profile models a 1280 x 1024 physical viewport at 200 percent browser zoom and requires the compact navigation/reflow contract without a mobile user agent. Each rendered page must have no selected WCAG 2.2 A/AA axe violation, page/console/request error, undecoded image, clipped reading column, fixed-header/sidebar overlap, or reachable page-level horizontal scroll. Interaction scenarios additionally prove keyboard skip navigation, English technical/prose search, native-dialog Escape, theme persistence, copy feedback, compact/mobile drawer semantics, focus containment and restoration, Russian search, html lang, active-locale state, all explicit README language pairs, exact paired-route switching, architecture/content-showcase rendering, and Russian 200-percent reflow. The retained screenshots include responsive document/navigation states, every Russian README entry point, translated documents, architecture and Content Showcase media for each profile, and zoom-200-russian-documentation.png at an exact 1280 x 1024 physical size without changing the Pages deployment path.

The architecture-diagram interaction waits for content-image decoding before checking dimensions and taking screenshots, using the same barrier as route validation. npm --prefix BuildTools/docs-browser run test:diagram exercises delayed lazy SVG and missing-image responses in desktop, mobile, and zoom-200 profiles; a missing or undecodable image still fails the audit.

Automated axe results cover only machine-detectable criteria. Raw incomplete nodes remain rule-level records with node/route counts and bounded example paths/targets instead of being mislabeled as passes. Axe can return color-contrast as incomplete when text is clipped inside a scroll container; for those exact nodes, the harness computes the effective foreground/background with alpha composition, applies the WCAG relative-luminance formula, and requires 4.5:1 or 3:1 for large text. Any failed or unresolvable fallback fails its route; both raw and resolved counts stay in the report. The zoom-200 profile is deterministic reflow, accessibility, and screenshot evidence for one viewport; it is not proof for every browser, operating-system magnifier, font override, or production rendering difference. A green job still does not prove screen-reader behavior, cognitive accessibility, content clarity, or production equivalence. Release review needs keyboard-only and representative assistive-technology checks on the landed artifact and production domain.

This job validates and previews the production render. On a master push it uploads the same validated tree as a Pages artifact; the dependent documentation-publish job deploys that artifact with pages: write and id-token: write. Neither job writes a source branch or changes DNS. PRs cannot enter the deployment job.

Reviewers should inspect every retained screenshot, including the dedicated Russian 200-percent reflow image, then inspect at least the landing page and changed pages interactively. Check the rolling version indicator, locale switch, page table of contents, code blocks, tables, local assets, keyboard order, and one screen-reader landmark/headings pass. Repeat 200-percent zoom on the landed artifact or production domain before release; the local profile does not replace that environment check. A green source, artifact, or axe check does not by itself prove that the rendered page is readable by every user.

The three route profiles run concurrently in separate browser contexts. Each keeps its own page, error listeners, and accessibility counters; results retain the manifest profile order. Progress reports completed routes every 50 pages. Interaction scenarios run after all route profiles complete.

Long unbroken prose tokens wrap within the reading column. Preformatted code keeps its own horizontal scrolling. The layout probe uses instant scrolling so the site’s smooth-scroll preference cannot hide reachable horizontal overflow from the check.

Production verification

After a documentation change reaches the configured Pages source:

1. Confirm Validate documentation and Build documentation site, including the browser audit, are green for the published commit.
2. Inspect both validation reports, every browser screenshot, and the commit-addressable site artifact before attributing a production difference to Pages.
3. Open https://fonline.ru/ and the English, Russian, and legacy routes for at least one migrated document.
4. Confirm sidebar navigation highlights the current page and remains usable at a mobile width.
5. Search for Game.Sync and a prose topic such as map baking in English, then игровой клиент in Russian; confirm results stay on canonical routes in the active locale.
6. Confirm HTTPS is valid and the browser remains on fonline.ru.
7. Confirm CNAME still contains exactly fonline.ru.
8. Resolve the domain and confirm it still targets GitHub Pages.

PowerShell DNS check:

Resolve-DnsName fonline.ru -Type A

POSIX DNS check:

dig +short fonline.ru A

Escalate a mismatch to both repository and domain administrators. Do not work around a Pages or DNS problem by committing generated HTML, changing the canonical domain, or adding an alternate deployment workflow.

Validation checklist

1. Markdown remains the canonical authored content.
2. CNAME, Docs/Site/_config.yml, Gemfile, .ruby-version, the manifest, and CI agree on the publication contract.
3. python BuildTools/tests/test_docs_validate.py passes.
4. python BuildTools/tests/test_docs_snippets.py and python BuildTools/docs_snippets.py --check --external pass without executing commands.
5. python BuildTools/tests/test_docs_diagrams.py, python BuildTools/docs_diagrams.py --check, python BuildTools/tests/test_docs_screenshots.py, python BuildTools/docs_screenshots.py --check, python BuildTools/tests/test_docs_site.py, python BuildTools/tests/test_docs_site_layout.py, and python BuildTools/docs_site.py --check pass, including visual ownership/freshness and version/locale/route collision coverage.
6. python BuildTools/tests/test_docs_ai_eval.py and python BuildTools/docs_ai_eval.py --check pass against that search model.
7. python BuildTools/tests/test_docs_ai_delivery.py and python BuildTools/docs_ai_delivery.py --check pass.
8. python BuildTools/tests/test_docs_localization.py and python BuildTools/docs_localization.py --check pass; production bilingual launch also uses --enforce-complete.
9. python BuildTools/docs_validate.py passes.
10. A local or CI Jekyll build produces Workspace/DocumentationSite/ without errors and contains the AI routes, evaluation/snippet reports, generated navigation, both locale search indexes, route catalog, layout, and local assets.
11. python BuildTools/tests/test_docs_site_artifact.py and python BuildTools/docs_site_artifact.py --site-dir Workspace/DocumentationSite pass against that rendered tree.
12. python BuildTools/tests/test_docs_browser.py passes, the pinned npm dependencies are installed from the lock file, and npm --prefix BuildTools/docs-browser run audit passes every route in all three manifest profiles plus every interaction scenario.
13. Desktop, mobile, and 200-percent reflow navigation, search, table of contents, source link, theme preference, page overflow, focus containment, and screenshots are exercised in the rendered artifact.
14. The dedicated Russian 200-percent screenshot is reviewed; manual keyboard, production-domain 200-percent zoom, and representative screen-reader checks are recorded for a release candidate; axe incomplete nodes are reviewed rather than silently ignored.
15. The site, static report, browser report, and screenshot artifacts are attached to the exact reviewed commit.
16. Production source settings and DNS were not changed unless the change explicitly required administrator review.