stx generate
Generate API reference pages from @stx annotations in your source code.
Scan your source code for @stx annotations and write one MDX reference page per @stx group. It also resolves {@embed} directives in your existing pages.
stx generate reads source code only. To build API reference pages from an OpenAPI spec, list it under openapi in syntext.json — pages are generated at build time. See OpenAPI sync.
Usage
Options
| Flag | Alias | Type | Default | Description |
|---|---|---|---|---|
--dir <dir> | -d | string | . | Project root directory |
--src <paths...> | -s | string[] | src | Source directories to scan, relative to the project root |
--output <dir> | -o | string | docs/api | Where to write the generated pages |
--repo-url <url> | string | Repository URL; adds a View source link to each symbol | ||
--dry-run | boolean | false | List the pages and symbols that would be generated, without writing files | |
--json | boolean | false | Output the result as JSON |
Test files (.test., .spec., __tests__, __mocks__), node_modules and paths in your .gitignore are skipped.
Examples
Generate from src/
Scan several folders, with source links
Preview without writing
Generated pages
Each @stx group becomes one page at <output>/<group-slug>.mdx. Every symbol in the group is a ## section with, in order: a deprecation callout, a Since badge, the source link, the description, the signature, a Parameters table, Returns, Examples and See Also. Symbols marked @stx internal are left out.
Add the generated pages to your navigation like any other page. Re-running stx generate overwrites them, so keep hand-written content on separate pages and pull symbols in with {@embed}.
Resolving {@embed}
After writing the pages, stx generate looks for {@embed symbolName} directives in every .md and .mdx file under docs/ and replaces each directive in the file with that symbol's generated section (heading, signature, parameters and so on). A name it can't find becomes an HTML comment saying so. The {@embed src="path#symbol"} form is left for hosted builds, which embed the symbol's code — see Annotations.
Source Code Annotations
@stx Annotation Syntax
Add @stx directives in your doc comments:
Supported Languages
| Language | Extensions | Comment Style | Example |
|---|---|---|---|
| TypeScript | .ts .tsx .mts .cts | /** ... */ | @stx title "..." |
| JavaScript | .js .jsx .mjs .cjs | /** ... */ | @stx title "..." |
| Python | .py | """...""" | @stx title "..." |
| Go | .go | // ... | // @stx title "..." |
| Rust | .rs | /// ... | /// @stx title "..." |
| Java/Kotlin | .java .kt .kts | /** ... */ | @stx title "..." |
| PHP | .php | /** ... */ | @stx title "..." |
| C# | .cs | /// ... | /// @stx title "..." |
Ruby (.rb) is parsed by hosted builds but not by the stx CLI, which has no
local Ruby parser. stx generate and stx check count any .rb files they find
and print a warning rather than skipping them silently, so a local run is never
mistaken for a complete one. The warning is also in --json output, under warnings.
Available Directives
| Directive | Description |
|---|---|
@stx group "Name" | Group/section name |
@stx title "Name" | Page title |
@stx description "..." | Short description |
@stx param name {type} desc | Parameter documentation |
@stx returns {type} desc | Return value documentation |
@stx example | Code example (until next directive) |
@stx since "1.2.0" | Version the symbol was added in (shown as a badge) |
@stx deprecated "Use X" | Mark the symbol deprecated, with an optional message |
@stx see "otherSymbol" | Add a See Also link |
@stx internal | Exclude from public docs |
When @stx annotations are present, they take precedence over conventional doc comments (JSDoc, docstrings, etc.).