Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jorgeferrando/sdd-skills/llms.txt

Use this file to discover all available pages before exploring further.

/sdd-docs turns your openspec/ directory into a fully-formed documentation website. It reads your canonical specs, steering files, and change archive, then uses an LLM to produce narrative prose — not template placeholders — for every section. The result is a complete MkDocs Material site that is ready to preview with mkdocs serve and deploy to GitHub Pages with mkdocs gh-deploy. If an LLM API key is not available, the skill falls back to generating placeholder-filled templates that you can fill in manually.

​
Usage

/sdd-docs

​
Prerequisites

  • openspec/ initialized — run /sdd-init if it does not exist yet.
  • sdd-tui installed with the [fill] extra: 
    pip install sdd-tui[fill]
  • ANTHROPIC_API_KEY set in the environment for AI-enriched output (see Without an API key if not available).

​
What It Does

1
Verify the LLM environment
2
Checks that an API key is available:
3
echo $ANTHROPIC_API_KEY   # should return a key value, not be empty
4
If the key is missing, the skill explains how to obtain and export one, and offers the placeholder fallback path.
5
Generate the documentation
6
Runs the CLI command:
7
sdd-docs --fill --force
8
The CLI reads the full openspec/ directory, builds a project context, and generates the documentation site using the configured LLM. --fill enables AI-enriched prose (no placeholders); --force overwrites any existing output files.
9
Preview locally
10
mkdocs serve
11
Open the local URL in a browser to review the generated site. Edit any section manually if needed — the next sdd-docs --fill --force run will regenerate, so commit manual edits before re-running.

​
Output

All generated files land in the project root alongside mkdocs.yml:
FileContent
mkdocs.ymlComplete MkDocs Material config — navigation, Mermaid support, theme features
docs/index.mdNarrative homepage: problem statement, tools, quick-start guide, architecture diagram
docs/reference/{domain}.mdOne page per domain from openspec/specs/ — prose explanation, requirement tables, decision log
docs/changelog.mdChange history generated from openspec/changes/archive/
The CLI confirms what was written: 
sdd-docs: Overwritten 10 file(s) (AI-enriched), skipped 0

  +  mkdocs.yml
  +  docs/index.md
  +  docs/reference/core.md
  +  docs/reference/auth.md
  +  docs/changelog.md
  ...

Next: run 'mkdocs serve' to preview

​
Without an API Key

If ANTHROPIC_API_KEY is not set, the CLI generates templates with {placeholder} markers instead of AI-written prose: 
sdd-docs --force    # --fill omitted: generates placeholders
Fill the placeholders manually in the generated files, then commit. Future runs with --fill (once a key is available) will replace the placeholders with AI-generated content.
Without ANTHROPIC_API_KEY, every narrative section in the generated docs will contain placeholder text like {project description} or {domain overview}. The structure and navigation are correct, but the content requires manual authoring. Set the key and re-run with --fill to get fully-written documentation.

​
Supported LLM Providers

Environment variableProviderNotes
ANTHROPIC_API_KEYClaude (Haiku by default)Currently supported
OPENAI_API_KEYGPT / CodexPlanned
GEMINI_API_KEYGeminiPlanned
The first available variable wins. Provider selection logic lives in src/sdd_tui/ai_docs.py → make_provider().

​
Skill Metadata

FieldValue
model_hinthaiku
requiresopenspec/specs/
producesdocs/ directory and mkdocs.yml

​
Next Steps

After previewing locally with mkdocs serve, deploy to GitHub Pages: 
mkdocs gh-deploy
To keep docs in sync with the codebase, re-run /sdd-docs after each /sdd-archive cycle — the changelog and reference pages will reflect the newly archived change automatically.

Build docs developers (and LLMs) love

Get started for freeTalk to us