stx check
Validate syntext.json, frontmatter, MDX tags and props, links, custom code and annotations — and explain where your site's look comes from.
Validate your documentation project before building or deploying. stx check
reads syntext.json (or syntext.yml / syntext.yaml), every page, your
custom code in _syntext/, and the
@stx annotations in your source, and reports problems with
the file and the line — in the same words as the hosted build.
Pages are read where the hosted build reads them: from docs/ when it holds
.md or .mdx pages at its top level, otherwise from the folder that holds
syntext.json (stx 0.11.1 and later). node_modules, dist, _syntext/ and
dot folders are skipped.
Usage
Options
| Flag | Alias | Type | Default | Description |
|---|---|---|---|---|
--dir <dir> | -d | string | . | Project folder that holds syntext.json. Relative or absolute |
--strict | boolean | false | Treat warnings as errors — exits 1 on any issue. Use it in CI | |
--json | boolean | false | Print the result as one JSON object | |
--explain [topic] | string | Show each resolved value and where it came from, instead of checking. Topic: appearance (the default) | ||
--src <paths...> | -s | string[] | src | Source folders to scan for @stx annotations |
--require-annotations | boolean | false | Require @stx on every exported symbol | |
--save-hashes | boolean | false | Save the current signature hashes for future drift checks | |
--coverage | boolean | false | Show annotation coverage | |
--style-guide <path> | string | .syntext/style-guide.json | Annotation style guide to lint against | |
--markdown | boolean | false | Print the annotation drift report as Markdown, for a PR comment |
Examples
Basic validation
With no issues it prints All checks passed, plus the number of annotations
found.
Strict mode (CI)
Every warning becomes an error, so the command exits 1. Deprecated syntax,
unknown keys and invalid values then fail CI before they reach a build.
Machine-readable output
code is the deprecation code
for deprecated forms and unknown keys. line is present whenever the issue can
be pinned to a line.
A project in another folder
What it checks
Configuration
syntext.json, syntext.yaml and syntext.yml are checked against the
published JSON Schema — the same one the
hosted build uses:
| Check | Example message |
|---|---|
| The file parses | syntext.json is not valid JSON: … |
| Unknown keys, with the closest valid key | Unknown key "nmae" is ignored. Did you mean "name"? |
| Values outside their allowed set | "tre" is not a layout.nav value. Use one of: tree, pills, … |
| Deprecated keys, with the replacement for your value | language: "en" is deprecated. Use locale: "en" instead. |
appearance and theme values | The appearance resolver's own messages — see Unknown values |
Pages
| Check | Description |
|---|---|
| Frontmatter present | A page without a frontmatter block is a warning |
title | A page without title is a warning |
| Unknown frontmatter keys | Warned with "did you mean" — Unknown key "descripton" is ignored. Did you mean "description"? |
| Frontmatter values | Enum keys such as layout, protocol or dir are checked against their values |
| Deprecated frontmatter | noIndex, fullWidth, home — see Frontmatter |
| Generated home (doc engine v2) | On a v2 site, an index page that uses home frontmatter, or has no content of its own, is a warning — the generated docs home ended on 16 November 2026. appearance.layout.home in syntext.json is reported too |
| Deprecated MDX tags and props | <Caution>, <Callout type>, <Update label>, <Endpoint url>, <SearchBar hint>, <Playground base-url> and the rest of the deprecation table. Code fences and inline code are skipped |
| Internal links | A link to a page that doesn't exist is an error — Broken link: /setup |
The generated-home warning names the file and points to Appearance ›
Convert home to content in the dashboard, or stx migrate, to write the home
components into index.mdx.
The hosted build never fails on the generated home — it is ignored with a
warning instead. Locally, --strict still turns it, like every warning, into
an error. See Home page.
Deprecated forms are reported as warnings. stx check doesn't know a form's
removal date, so it never fails on its own after a deprecation window closes —
the hosted build does. Run stx migrate to rewrite every
deprecated form in place, or use Fix automatically in the dashboard — see
Fixing them.
Custom code
stx check checks your _syntext/ folder and
every page's css: file with the
same rules and messages as a publish — sizes, what a stylesheet, script or
head.html may contain, and where a page's css: points. Files in _syntext/
are never checked as pages.
head.html gets a warning that it runs only when its
switch is on, and never on previews.projectId, and you're logged in) is checked
against its switches in Integrations › Custom code: a file whose switch is
off is reported as _syntext/app.js is skipped: "Scripts from your docs" is off in Integrations › Custom code.
A switch that's on says nothing. If the switches can't be read, you get the
general warning instead; the check never fails because of it.docs/_syntext/ and a root _syntext/ — the root one is ignored,
with a warning.Custom code checks need CLI v0.10.0 or later.
Annotations
stx check also scans your source tree (--src, default src) for @stx
annotations and reports signature drift against the stored hashes.
It scans exactly the extensions stx generate
scans — TypeScript (.ts .tsx .mts .cts), JavaScript (.js .jsx .mjs
.cjs), Python, Go, Rust, Java/Kotlin, PHP and C#. Files the CLI cannot parse
locally but a hosted build can — currently Ruby — are reported as a warning
naming the count, rather than skipped silently.
| Check | Description |
|---|---|
| Signature drift | Annotated signatures still match the stored hashes |
| Unannotated exports | Exported symbols missing @stx (with --require-annotations) |
| Style guide | Annotations satisfy .syntext/style-guide.json |
Explain your appearance
Instead of checking, prints how your site's look is resolved:
appearance
field with its value and its source: preset, legacy-theme (a v1 theme
name mapped onto v2), feature-flag (a v1 features flag), org-theme or
appearance.themeOverrides, then the legacy colors and
fonts keys, set.themeOverrides accent or
the legacy colors.primary wins over appearance.accent.When theme is an organization theme
("@acme/brand"), the theme is fetched from Syntext if you're logged in
(stx login). Otherwise the output says it couldn't be resolved
and shows the preset without it.
--json prints the same information as one object
({ "success": true, "topic": "appearance", "configFile", … }). An unknown
topic exits 1 with a suggestion.
CI integration
Add to your CI pipeline to catch issues before merge:
GitHub Actions
Pre-commit hook
Exit codes
| Code | Meaning |
|---|---|
0 | No errors (warnings are allowed unless --strict) |
1 | Errors found — a broken link, annotation drift at error level, any issue under --strict — or the check couldn't run |
Common issues
Deprecated syntax
Fix: run stx migrate --dry-run to see the rewrite, then stx migrate to
apply it. See Deprecated syntax.
Unknown key
Fix: rename the key to the suggestion, or delete it. Unknown keys are ignored by the build, so the setting you meant has no effect until you do.
Broken internal link
Fix: update the link to an existing page or create the missing page.