new-spec

name	new-spec
description	Scaffolding a new spec section on spec.gesslar.dev. Consult when the user wants to add a new specification or a new top-level docs section on this Starlight site.

Adding a New Spec to spec.gesslar.dev

This site uses Starlight (Astro). Each spec is a top-level sidebar group whose pages live under src/content/docs/{id}/. The sidebar spec-switcher (src/overrides/Sidebar.astro) auto-discovers specs from the sidebar groups in astro.config.mjs — no override edits are needed.

There is no built-in versioning. If the user wants versioned URLs, surface that as a separate design question before scaffolding.

Information Needed

Before scaffolding, gather from the user:

1. Spec id ({id}) — lowercase identifier used for the directory and URL segment (e.g., lpml, lpcdoc). No spaces. Astro/Starlight lowercases slugs, so a directory named STUPID still routes at /stupid/ — pick the directory name in lowercase to avoid confusion between the on-disk name and the URL. The sidebar label is display text and can be whatever casing the user wants (e.g., "STUPID").
2. Display title ({title}) — human-readable name for the sidebar group and homepage card (e.g., "LPML", "LPCDoc").
3. One-line description ({description}) — shown on the homepage card and used as the subtitle in the auto-generated Open Graph social card (see src/pages/open-graph/[...slug].ts). Every page's frontmatter description feeds its OG card, so require one for each new page, not just the index.
4. Codicon icon ({icon}) — VS Code codicon class for the homepage card (e.g., codicon-file-code, codicon-book). Full list: https://microsoft.github.io/vscode-codicons/dist/codicon.html
5. Sidebar style — autogenerated from the directory (default) or an explicit items: [...] list.
6. (Optional) Syntax grammar — if the spec ships a TextMate grammar package for code highlighting, get the package name and the lang name to register it under.

Files to Create

1. src/content/docs/{id}/index.md

---
title: {title}
description: {description}
---

# {title}

{description}

Add further pages (reference.md, examples.md, etc.) as the user dictates. Each page's frontmatter controls its sidebar label (title) and ordering (sidebar.order). See https://starlight.astro.build/reference/frontmatter/ for the full schema.

Every page must have a description. The Open Graph route at src/pages/open-graph/[...slug].ts generates a social card per page using the frontmatter title and description. A page without a description produces a card with an empty subtitle, which looks broken when pasted into Discord/Slack/etc. Prompt the user for one per page, not just the index.

Files to Edit

2. astro.config.mjs — sidebar group

Append to the sidebar array passed to starlight({...}):

{
  label: '{title}',
  autogenerate: { directory: '{id}' },
},

For manual ordering, use items instead:

{
  label: '{title}',
  items: [
    { label: 'Overview', slug: '{id}' },
    { label: 'Reference', slug: '{id}/reference' },
  ],
},

Slug rules (easy to get wrong):

• Slugs are content-collection paths, not filenames — never include .md or .mdx.
• An index.md collapses to its directory slug. For src/content/docs/{id}/index.md the slug is {id}, not {id}/index and not index.md.
• Slugs and URLs are lowercase. A directory named STUPID/ routes at /stupid/. Homepage card href values must use the lowercase form.

3. src/pages/index.astro — homepage card

Append to the specs array:

{
  title: '{title}',
  description: '{description}',
  href: '/{id}/',
  icon: '{icon}',
},

4. (Optional) astro.config.mjs — syntax grammar

If the spec ships a TextMate grammar, install the package and register it in markdown.shikiConfig.langs:

import myGrammar from '@scope/my-language-tmgrammar-hl'

// ...inside defineConfig:
markdown: {
  shikiConfig: {
    langs: [
      // ...existing
      { ...myGrammar, name: 'my-lang' },
    ],
  },
},

After Scaffolding

1. Run npm run build to verify the site builds without errors.
2. If it succeeds, tell the user the new spec is reachable at /{id}/ and appears both as a homepage card and in the sidebar spec-switcher dropdown.