gleam-reference-docs

name	gleam-reference-docs
description	Use this skill when a user wants to add generated API/reference docs to a Gleam project from Gleam's package-interface.json metadata. Trigger for requests about Gleam docs JSON, package-interface.json, reference docs, Starlight or Astro docs sites, HexDocs-like pages, just recipes, pnpm/node scripts, or replicating the Gluegun docs recipe. This skill helps wire the generator script, package scripts, just tasks, sidebar entries, tests, and validation so the workflow is repeatable.
compatibility	Gleam projects with Node-based docs sites; optimized for Astro/Starlight, pnpm, and just, but adaptable to npm/yarn and other static docs generators.

Gleam reference docs generator

Help the agent add a repeatable workflow that turns Gleam's docs metadata into website reference pages.

The target pattern is:

1. gleam docs build writes build/dev/docs/<package-name>/package-interface.json.
2. A Node script reads that JSON and writes Markdown pages under the docs website.
3. package.json exposes a generate:reference script.
4. just tasks make website checks/builds depend on reference generation.
5. The website sidebar links to the generated reference pages.

Start by discovering the project shape

Inspect before editing:

• gleam.toml for package name, target, and whether docs are already configured.
• justfile for existing docs/site recipes and command naming conventions.
• Website directory, commonly website/, docs/, or site/.
• Website package manager and scripts: package.json, lockfiles, Astro/Starlight config.
• Existing generated or hand-written reference docs.
• Existing tests for docs scripts.

If the project has no docs website yet, ask whether to add only the generator scaffolding or also create a website. This skill covers generator wiring, not a full docs-site redesign.

Implementation recipe

Use the bundled template at assets/generate-reference.mjs as the starting point for website/scripts/generate-reference.mjs or the project's equivalent scripts directory.

Adapt these values to the project:

• websiteRoot: where the Node docs package lives.
• repoRoot: usually one directory above the website.
• defaultOutputDir: the generated Markdown location, commonly website/src/content/docs/reference.
• Sidebar links/slugs to match the website router.
• Any project-specific note in the generated reference index.

Prefer deriving the Gleam package name from gleam.toml instead of hardcoding it. Hardcoding is acceptable only when the project already hardcodes other website metadata and the package name is stable.

Add package scripts

In the website package manager scripts, add:

{
  "generate:reference": "node scripts/generate-reference.mjs",
  "test:reference": "node --test scripts/generate-reference.test.mjs"
}

Keep existing script style and indentation. If the project does not use pnpm, use the existing package manager commands in docs and just recipes.

Add just recipes

If a justfile exists, add or adapt:

# Build Gleam documentation metadata
docs:
    gleam docs build

# Generate website reference docs from Gleam docs JSON
site-reference: docs
    cd website && pnpm generate:reference

# Build website
site-build: site-reference
    cd website && pnpm build

# Type-check and validate website
site-check: site-reference
    cd website && pnpm check:astro

Do not duplicate existing recipes. If docs, site-build, or site-check already exist, preserve their existing commands and add site-reference as a dependency where appropriate.

Add sidebar entries

For Astro/Starlight, update website/astro.config.mjs or the relevant sidebar config so the generated pages are discoverable:

• Add a Reference group.
• Include the generated index at /reference/.
• Add one item per public module, using slugs generated by replacing / with -, for example my_pkg/http -> reference/my_pkg-http.
• If there is already a canonical HexDocs link, keep it as an external link.

When the module list is generated, make sure sidebar links match the actual Markdown file names.

Add tests when the project has Node tests

Add website/scripts/generate-reference.test.mjs when the website already uses Node or when adding a Node script. Cover:

• Index and module pages are generated from a fixture package-interface.json.
• Missing JSON reports a helpful error mentioning gleam docs build.
• Types, type aliases, constants, functions, constructors, tuple types, function types, type variables, and deprecations render correctly enough for the project.

Use temporary directories so tests do not modify checked-in docs.

Generator behavior to preserve

The generator should:

• Read build/dev/docs/<package-name>/package-interface.json.
• Validate name and modules.
• Remove and recreate the output reference directory.
• Write index.md with package name, version, generated-content note, and a module table.
• Write one Markdown page per public module.
• Render sections in this order: Types, Type aliases, Constants, Functions.
• Sort modules and members alphabetically for stable diffs.
• Normalize documentation whether Gleam emits it as an array or string.
• Render Gleam type signatures from JSON, including named types, variables, tuples, and function types.
• Omit qualifiers for prelude types and types from the current module; use the last module path segment for other modules.
• Surface deprecation metadata as a docs-site warning/caution block.

Validation

Run the smallest useful checks:

1. gleam docs build
2. The website reference generator, for example cd website && pnpm generate:reference
3. The generator tests if added, for example cd website && pnpm test:reference
4. The website check/build if they already exist, for example just site-check or just site-build

If generated files change, inspect at least the reference index and one module page before finishing.

Output to the user

Report:

• The generator script path.
• The generated docs JSON path.
• The output docs directory.
• The commands added or changed.
• Any follow-up needed, such as committing regenerated reference pages.