Docs Site Setup

Each lexicon can include a documentation site built with Astro Starlight. The docs site lives in lexicons/<name>/docs/.

Quick Setup

Create the docs directory structure:

mkdir -p lexicons/my-lexicon/docs/src/content/docs

astro.config.mjs

// @ts-check
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  base: '/chant/lexicons/my-lexicon/',
  integrations: [
    starlight({
      title: 'My Lexicon',
      sidebar: [
        { label: '← chant docs', link: '../../' },
        { label: 'Overview', slug: 'index' },
        { label: 'Getting Started', slug: 'getting-started' },
        // ... add more pages
      ],
    }),
  ],
});

package.json

{
  "name": "@intentius/chant-lexicon-my-lexicon-docs",
  "type": "module",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
  "dependencies": {
    "@astrojs/starlight": "^0.37.6",
    "astro": "^5.6.1",
    "sharp": "^0.34.2"
  }
}

tsconfig.json

{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"]
}

Recommended Page Structure

A comprehensive docs site should have these pages (as MDX files in docs/src/content/docs/):

Page	File	Description
Overview	index.mdx	Installation, quick start, feature list
Getting Started	getting-started.mdx	First project walkthrough
Resources	resources.mdx	Resource types, resource-level fields
Intrinsics	intrinsics.mdx	Template functions (if applicable)
Pseudo-Parameters	pseudo-parameters.mdx	Deployment-time parameters
Composites	composites.mdx	All composites with examples
Parameters & Outputs	parameters-outputs.mdx	Template parameters and outputs
Lint Rules	lint-rules.mdx	All pre-synth and post-synth checks
Importing	importing.mdx	Import existing templates
Advanced Patterns	linked-templates.mdx	Advanced usage patterns
Examples	examples.mdx	Walkthrough of example projects

Building the Docs

# Development server
cd lexicons/my-lexicon/docs
npm install
npm run dev

# Production build
npm run build

Wiring into Package Scripts

Add a docs script to your lexicon’s package.json:

{
  "scripts": {
    "docs": "npx tsx src/codegen/docs-cli.ts",
    "docs:dev": "cd docs && npm run dev",
    "docs:build": "cd docs && npm run build"
  }
}

Page Frontmatter

Each MDX page requires YAML frontmatter:

---
title: "Page Title"
description: "Brief description for SEO and sidebar"
---

Content goes here...

Cross-Site Links

The 13 docs sites (main + 12 lexicons) build independently and stitch into a single tree at .docs-dist/chant/. Astro’s base: '/chant' only prefixes its own sidebar/slug entries — root-relative links written in MDX body content don’t get prefixed automatically.

A shared rehype-base-url plugin (packages/core/src/codegen/rehype-base-url.mjs) closes the gap: it walks the HAST tree and prepends the site’s base to <a href> values that start with /. The lexicon codegen wires this into every generated astro.config.mjs, so new lexicons get it for free.

Two gotchas:

• Linking across namespaces from a lexicon page. A lexicon site’s base is /chant/lexicons/<name>, so [guide](/guide/composite-resources/) in lexicons/aws/... would get prefixed to /chant/lexicons/aws/guide/composite-resources/ (wrong). Write the full project path — /chant/guide/composite-resources/ — and the plugin’s idempotency check (projectBase: '/chant') leaves it alone.
• Sibling pages in MDX. [foo](./foo) from aks-composites.mdx resolves to aks-composites/foo (child), not the sibling foo page. Use ../foo/ (or the absolute /chant/... form).

just docs-check-links runs lychee against the built .docs-dist/chant/ tree and catches both classes of breakage.

Reference

• K8s docs: lexicons/k8s/docs/ — 11 pages with full sidebar navigation
• Azure docs: lexicons/azure/docs/ — 11 pages covering ARM templates