Docs CLI Commands

The @refrakt-md/docs package extends the refrakt CLI with the docs extract subcommand for generating API reference documentation from source code.

refrakt docs extract

Extracts exported symbols from TypeScript or Python source code and generates Markdown documentation using the {% symbol %} rune. Each exported function, class, interface, or type gets its own .md file, plus a _layout.md for navigation.

Basic usage

refrakt docs extract ./src -o ./content/api

This scans ./src for source files, extracts all exported symbols, and writes one Markdown file per symbol to ./content/api/.

Language detection

The language is auto-detected from file extensions and the presence of tsconfig.json. You can override it explicitly:

refrakt docs extract ./src -o ./content/api --lang typescript

refrakt docs extract ./lib -o ./content/api --lang python

Source links

Add clickable links back to source code in the generated docs:

refrakt docs extract ./src -o ./content/api --source-url https://github.com/my/repo/blob/main/src

Custom section title

By default the generated _layout.md uses "API Reference" as the navigation title. Override it with:

refrakt docs extract ./src -o ./content/api --title "SDK Reference"

CI validation

Use --validate to check that generated files are up to date without overwriting them:

refrakt docs extract ./src -o ./content/api --validate

This exits with code 1 if any files are missing or stale, making it suitable for CI pipelines that enforce documentation freshness.

What gets generated

For a project with exported symbols createClient, Config, and Response:

content/api/
├── _layout.md          # Navigation with section title
├── create-client.md    # createClient docs
├── config.md           # Config docs
└── response.md         # Response docs

If two symbols produce the same slug (e.g., a Config type and a Config interface), the kind is appended: config-type.md, config-interface.md.

Files skipped during extraction: .d.ts, .test.ts, .spec.ts.

Options