/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
CLI CLI Reference stx generate

stx generate

Generate API reference pages from @stx annotations in your source code.

3 min read

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.

Note

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

bash
stx generate [options]

Options

FlagAliasTypeDefaultDescription
--dir <dir>-dstring.Project root directory
--src <paths...>-sstring[]srcSource directories to scan, relative to the project root
--output <dir>-ostringdocs/apiWhere to write the generated pages
--repo-url <url>stringRepository URL; adds a View source link to each symbol
--dry-runbooleanfalseList the pages and symbols that would be generated, without writing files
--jsonbooleanfalseOutput the result as JSON

Test files (.test., .spec., __tests__, __mocks__), node_modules and paths in your .gitignore are skipped.

Examples

Generate from src/

bash
stx generate
text
✔ Generated 3 page(s) from 14 annotations
→ docs/api/users.mdx
→ docs/api/billing.mdx
→ docs/api/webhooks.mdx
bash
stx generate --src src lib --repo-url https://github.com/acme/api

Preview without writing

bash
stx generate --dry-run
text
Dry run — would generate 2 page(s):
+ api/users.mdx (2 symbols)
function createUser
function getUser
+ api/billing.mdx (1 symbols)
class Invoice

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.

mdx
---
title: "Users"
description: "API reference for Users"
---
## Create User
Create a new user account
```typescript
async function createUser(data: CreateUserInput): Promise<User>
```
### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `data` | `CreateUserInput` | **Yes** | The new user's details |
### Returns
`Promise<User>` — The created user

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:

typescript
/**
* @stx group "Users"
* @stx title "Create User"
* @stx description "Create a new user account"
*/
export async function createUser(data: CreateUserInput): Promise<User> {
// ...
}

Supported Languages

LanguageExtensionsComment StyleExample
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 "..."
Note

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

DirectiveDescription
@stx group "Name"Group/section name
@stx title "Name"Page title
@stx description "..."Short description
@stx param name {type} descParameter documentation
@stx returns {type} descReturn value documentation
@stx exampleCode 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 internalExclude from public docs
Note

When @stx annotations are present, they take precedence over conventional doc comments (JSDoc, docstrings, etc.).

Was this page helpful? Yes No
Previous
Product
Resources
Company
© 2026 SyntextBuilt with Syntext