This page documents the conventions for writing pages on the G# documentation site. It exists so that contributors — human or automated — can add or edit pages consistently.
The site is built with Docusaurus and lives entirely under the website/ directory. Public-facing pages are written fresh there. The implementation-oriented documents under docs/ remain the authoritative source of design intent.
cd website
npm ci
npm start # local dev server with hot reload
npm run build # production build; fails on broken links
npm run serve # production preview, including the generated search index
npm run typecheck
npm run test:contentThe production build (npm run build) runs with onBrokenLinks: 'throw', so a broken internal link fails the build and the CI check. Always run it before opening a pull request.
Every page starts with YAML front matter. Always quote the title because many G# titles contain a colon:
---
title: "Tutorial: Control flow"
sidebar_position: 4
---Use sentence case for headings. Start each page with a single # H1 that matches the title, then use ##/### for sections. Keep one concept per page where practical.
Write an intentional description in front matter: one concise sentence about what the reader will learn or accomplish. Lead with the user-facing concept or task before implementation history.
Do not hard-wrap continuous prose. Let the renderer handle line wrapping; only insert line breaks between paragraphs and list items. This keeps diffs small and readable.
Use the gsharp language tag (aliases gs and g#) for G# code so it gets the custom syntax highlighting defined in website/src/theme/prism-include-languages.ts:
```gsharp title="hello.gs"
package Hello
import System
Console.WriteLine("Hello, world!")
```Use csharp, go, bash, and json for other languages. When showing program output, follow the code block with a plain ```text block.
Whenever possible, G# code shown in the docs should come from a real, compiling program checked in under the repository's samples/ directory (each samples/NAME.gs may have a sibling samples/NAME.golden capturing its expected stdout). This guarantees the examples actually compile and run, because SampleConformanceTests builds every sample with gsc, runs it, and diffs stdout against the golden file.
When you add a new example to the docs:
- First check whether an existing sample demonstrates the feature.
- If you need a new example, add it under
samples/(with a.goldenif it produces output) so it is covered by conformance tests, then mirror it in the docs. - Keep the docs copy faithful to the checked-in source; if you must trim it for brevity, keep it syntactically valid.
For expected-output blocks in tutorials and the Tour, copy the text from the sample's .golden file.
The homepage imports the complete samples/Website*.gs fixtures and their .golden output directly. Run python3 website/tests/verify-examples.py from the repository root when changing them or the advertised release. It checks the published template and SDK in an isolated workspace; a pass with a development compiler alone does not establish compatibility with the release.
Use python instead of python3 on Windows if the latter is a Store alias. The equivalent website commands are python scripts/prepare-showcase.py && npx --no-install tsc and python scripts/prepare-showcase.py && npx --no-install docusaurus build && npx --no-install pagefind --site build.
Run python3 website/tests/verify-trail.py, python3 website/tests/verify-concurrency-patterns.py --race, and python3 -m unittest discover -s website/tests -p 'test_*.py' for download changes. The preparation script canonicalizes packaged text to LF before hashing; historical archives remain untouched. The line-ending test compares LF and CRLF checkouts byte for byte. Go's race detector is unavailable on Windows ARM64; run without --race there and record that limitation. On Windows, suppress OS crash dialogs for the intentional negative subprocesses with python -c "import ctypes, runpy; ctypes.windll.kernel32.SetErrorMode(2); runpy.run_path(r'website\tests\verify-concurrency-patterns.py', run_name='__main__')".
For worktree-local verification, set TEMP and TMP to a named directory under that worktree. Put empty <Project /> files named Directory.Build.props and Directory.Build.targets in its parent so downloaded projects do not inherit the compiler repository's build customization. Keep its ancestor NuGet source configuration available. Do not change the repository pin or lock files to bypass a restore failure.
The site content is grounded in two research artifacts produced while planning the site, plus the in-repo references:
- The language and tooling snapshot (lexical structure, full grammar, type system, concurrency, interop, tooling) — see the implementation sources under
src/Core/CodeAnalysis/and the curated docs underdocs/. - Design records explain why features work the way they do. End-user pages should not cite or link individual records; the single Design decisions page is the only index for them.
docs/diagnostics.mdis authoritative for diagnostic IDs (GSxxxx); the Diagnostics reference page must preserve those IDs exactly.
Use relative Markdown links between documentation pages, including the .md or .mdx extension. They retain the selected documentation version. A root-relative /docs/... link inside Next instead sends the reader to the released snapshot.
From React marketing pages, use Docusaurus Link with site-relative paths. The homepage deliberately links to the release; an explicit Next link must be labeled as preview or as a current project snapshot.
Do not hard-code the deployed /gsharp/ prefix in internal links. Preserve document IDs and existing anchors when changing headings; add a legacy anchor at the corresponding section when a rename is necessary.
website/docs is development documentation at /docs/next. The first entry in versions.json is the default released snapshot at /docs; older snapshots retain their versioned paths.
When refreshing a release, use the source from its actual Git tag, not a wholesale copy of unreleased main. The 0.5 snapshot is based on v0.5.212 (242d8777c778db4272103c9dcefd6d63609e10ee, published October 22, 2026 at 01:07:10 UTC), with reviewed editorial corrections. The 0.4 snapshot remains based on v0.4.591. Update the advertised package in src/data/release.json, the matching installation instructions, and the public-installation checks together. Historical versions must retain their own syntax and commands.
The original Trail editor captures remain historical 0.4.591 evidence. Preserve the image bytes and provenance; distinguish the extension version, application SDK and .NET SDK. Verify new downloads independently with the published SDK instead of relabeling screenshots.
Reuse the semantic tokens in src/css/custom.css, CSS Modules for page-specific layout, and native Docusaurus components. Keep code selectable, diagrams lightweight, and keyboard focus visible. Check narrow layouts, both themes, and reduced motion.
Pagefind indexes the production HTML after npm run build. Use npm run serve to check search; the hot-reload server does not generate an index. Search failure should be reported, not hidden.
Keep source and license information for font and image assets. Reference-site screenshots are design research, not artwork to redistribute in the website.