Site Maintainer

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

Non-Negotiables

• •Public-facing: Everything in /site/ published at https://domainlang.net
• •Documentation accompanies code: Grammar/SDK/CLI changes MUST include /site/ updates
• •Sentence casing: All headings use sentence casing (## Getting started, not ## Getting Started)
• •Single source of truth: All user docs in /site/ only

Your Role

• •Create/maintain user documentation pages
• •Configure VitePress site and navigation
• •Ensure consistent style and formatting
• •Add code examples with syntax highlighting
• •Maintain site deployment

Related skill: .github/skills/technical-writer/SKILL.md (writing style)

Skill Pairing

• •This skill first: Information architecture, navigation, public quality
• •Technical-writer second: Writing style, clarity, technical correctness

Site Architecture

Rule: Guide teaches, Reference defines, Examples prove.

Page Structure Template

# Page Title

One-sentence description of what this page covers.

## Basic Syntax

Show simplest example first.

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

## Properties / Options

Table or list of available options.

## Examples

Real-world examples with context.

## Best Practices

::: tip
Actionable advice
:::

## See Also

Links to related pages.

VitePress Configuration

Key Settings (/site/.vitepress/config.mts)

export default defineConfig({
  title: 'DomainLang',
  base: '/',           // CRITICAL: Use '/' for domainlang.net
  cleanUrls: true,     // No .html extensions
  lastUpdated: true,
})

Syntax Highlighting

Always use dlang for code blocks:

```dlang
Domain Sales { vision: "Sell products" }
```

Custom TextMate grammar registered in config.mts.

Navigation

themeConfig: {
  nav: [
    { text: 'Guide', link: '/guide/getting-started' },
    { text: 'Reference', link: '/reference/language' },
  ],
  sidebar: {
    '/guide/': [
      { text: 'Introduction', items: [...] },
      { text: 'Core Concepts', items: [...] },
    ]
  }
}

VitePress Containers

::: info
Neutral information
:::

::: tip
Helpful advice
:::

::: warning
Be careful about this
:::

::: danger
Critical warning
:::

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

Writing Style

Voice

• •User-focused: DDD practitioners learning DSL
• •Action-oriented: Use imperatives ("Create a domain", "Add a context")
• •Concise: Short sentences, scannable
• •Welcoming: Assume readers new to DomainLang

Links

<!-- Internal (relative, no .md) -->
See [Bounded Contexts](/guide/bounded-contexts) for details.

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

Feature Documentation Sync

When implementing grammar/SDK/CLI changes:

• • Guide page updated or created
• • Reference page updated (syntax changes)
• • Quick reference updated (common patterns)
• • Getting started updated (onboarding affected)
• • Examples updated (new patterns)
• • Sidebar navigation wired

Deployment

GitHub Actions workflow:

• •Trigger: Push to main with site/ changes
• •Fast Path: Site-only changes skip quality gates, require manual approval
• •Deploy: GitHub Pages → domainlang.net

Local development:

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

Adding New Pages

1. •Create markdown file: site/guide/new-feature.md
2. •Add frontmatter (optional):
   markdown

   ---
   title: Custom Title
   description: SEO description
   ---
   

3. •Update navigation in config.mts
4. •Cross-link from related pages

Quality Checklist

• • Content accurate vs current grammar/CLI
• • Sentence casing on all headings
• • Page in correct area (guide/reference/examples)
• • Navigation updated in config.mts
• • Code blocks use dlang
• • Links correct (relative internal)
• • Cross-references to prerequisite/related pages
• • No internal notes or TODOs
• • Tested locally

Commit Messages

# Site changes (no version bump)
docs(site): add migration guide for v2.0.0
docs(site): improve getting started tutorial
docs(site): fix broken links in context map guide

# Configuration
chore(site): update VitePress to v1.5.0

Microsoft TechDocs Standards

• •Lead with value: Answer "what will reader learn?"
• •Progressive disclosure: Simple → complex, link for depth
• •Cross-reference liberally: Link prerequisites and related
• •Consistent terminology: Same term for same concept
• •Introduce new concepts clearly: Define terms on first use. Link to reference for details.
• •Scannable: Tables, lists, callouts
• •Code before prose: Show example, then explain
• •One idea per paragraph: Split if multiple ideas

Brand Colors

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