Site maintainer

You maintain the public documentation website at https://domainlang.net (source: /site/).

Markdown rules, sentence casing, and writing voice live in .github/instructions/documentation.instructions.md and .github/skills/technical-writer/SKILL.md. This skill owns information architecture, VitePress, and deploy.

Non-negotiables

• Everything in /site/ is published — no internal notes, TODOs, or repo paths.
• Grammar / SDK / CLI changes must include /site/ updates in the same PR.
• Sentence casing for all headings.
• Single source of truth: user-facing docs live only in /site/.

Skill pairing

1. This skill first — IA, navigation, page placement, public quality.
2. technical-writer second — voice, clarity, factual accuracy.

Site architecture

Rule: Guide teaches, Reference defines, Examples prove.

Page template

# Page title

One-sentence description of what this page covers.

## Basic syntax

\`\`\`dlang
// Minimal working example
\`\`\`

## Properties / options

| Property | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | Unique identifier |

## Examples

Real-world examples with context.

## Best practices

::: tip
Actionable advice.
:::

## See also

- [Related page](/guide/related)

VitePress essentials

// /site/.vitepress/config.mts
export default defineConfig({
    title: 'DomainLang',
    base: '/',           // CRITICAL for domainlang.net
    cleanUrls: true,     // no .html extensions
    lastUpdated: true,
    themeConfig: {
        nav: [
            { text: 'Guide', link: '/guide/getting-started' },
            { text: 'Reference', link: '/reference/language' },
        ],
        sidebar: { '/guide/': [ /* ... */ ] },
    },
});

Always use `dlang for DSL code blocks (custom TextMate grammar registered in config.mts).

VitePress containers

::: info / tip / warning / danger
Single-line callout body.
:::

::: details Click to expand
Hidden content.
:::

Links

<!-- internal: relative, no .md, no anchors unless needed -->
See [Bounded contexts](/guide/bounded-contexts).

<!-- external: full URL -->
[VS Code Extension](https://marketplace.visualstudio.com/items?itemName=...)

Deployment

• GitHub Actions, triggered on push to main with /site/ changes.
• Site-only changes skip the language quality gate but require manual approval.
• Deploys to GitHub Pages → domainlang.net.

cd site
npm run dev      # http://localhost:5173
npm run build    # Production build
npm run preview  # Preview build locally

Adding a new page

1. Create site/guide/new-feature.md (or reference/, examples/).
2. Optional frontmatter for SEO / custom title.
3. Wire into the sidebar in config.mts.
4. Cross-link from related pages (prerequisites + follow-ons).
5. Verify with npm run dev.

Feature documentation sync checklist

When grammar / SDK / CLI changes ship:

• Guide page updated or added.
• Reference page updated for syntax changes.
• /site/reference/quick-reference.md updated for common patterns.
• /site/guide/getting-started.md updated if onboarding changed.
• Examples updated for new patterns.
• Sidebar wired in config.mts.
• Public agent skill (skills/domainlang/SKILL.md + references/SYNTAX.md) in sync.

Public quality checklist

• Content matches current grammar / CLI behavior.
• Sentence casing on all headings.
• Page in correct area (guide vs reference vs examples).
• All code blocks use dlang.
• All links work; internal links use relative paths.
• Cross-references to prerequisites + related pages.
• No internal notes, TODOs, or repo paths.
• Tested locally with npm run dev.

Microsoft TechDocs principles applied

• Lead with value — answer "what will the reader learn?" in the first sentence.
• Progressive disclosure — simple → complex; link to depth.
• Cross-reference liberally — link prerequisites and related concepts.
• Consistent terminology — same term for the same concept everywhere.
• Define on first use — link to reference for full detail.
• Scannable — tables, lists, callouts; one idea per paragraph.
• Code before prose — show the example, then explain.

Brand colors

Custom variables in /site/.vitepress/theme/style.css.