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

stx check

Validate syntext.json, frontmatter, MDX tags and props, links, custom code and annotations — and explain where your site's look comes from.

8 min read

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

bash
stx check [options]

Options

FlagAliasTypeDefaultDescription
--dir <dir>-dstring.Project folder that holds syntext.json. Relative or absolute
--strictbooleanfalseTreat warnings as errors — exits 1 on any issue. Use it in CI
--jsonbooleanfalsePrint the result as one JSON object
--explain [topic]stringShow each resolved value and where it came from, instead of checking. Topic: appearance (the default)
--src <paths...>-sstring[]srcSource folders to scan for @stx annotations
--require-annotationsbooleanfalseRequire @stx on every exported symbol
--save-hashesbooleanfalseSave the current signature hashes for future drift checks
--coveragebooleanfalseShow annotation coverage
--style-guide <path>string.syntext/style-guide.jsonAnnotation style guide to lint against
--markdownbooleanfalsePrint the annotation drift report as Markdown, for a PR comment

Examples

Basic validation

bash
stx check
text
⚠ Found 3 issue(s)
⚠ syntext.json:3: Unknown key "nmae" is ignored. Did you mean "name"?
⚠ syntext.json:7: colors.accent: "#2AC3DE" is deprecated. Use themeOverrides.colors.light.accent-strong: "#2AC3DE" and themeOverrides.colors.dark.accent-strong: "#2AC3DE" instead.
⚠ docs/components/updates.mdx:32: <Update label="…"> is deprecated. Use <Update title="…"> instead.

With no issues it prints All checks passed, plus the number of annotations found.

Strict mode (CI)

bash
stx check --strict

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

bash
stx check --json
json
{
"files": 47,
"sourceFiles": 12,
"issues": [
{
"file": "docs/components/updates.mdx",
"line": 32,
"type": "warning",
"message": "<Update label=\"…\"> is deprecated. Use <Update title=\"…\"> instead.",
"code": "mdx.update-label"
}
],
"annotations": 18,
"coverage": 100
}

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

bash
stx check --dir /path/to/docs-project

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:

CheckExample message
The file parsessyntext.json is not valid JSON: …
Unknown keys, with the closest valid keyUnknown 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 valuelanguage: "en" is deprecated. Use locale: "en" instead.
appearance and theme valuesThe appearance resolver's own messages — see Unknown values

Pages

CheckDescription
Frontmatter presentA page without a frontmatter block is a warning
titleA page without title is a warning
Unknown frontmatter keysWarned with "did you mean" — Unknown key "descripton" is ignored. Did you mean "description"?
Frontmatter valuesEnum keys such as layout, protocol or dir are checked against their values
Deprecated frontmatternoIndex, 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 linksA 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.

text
✗ docs/_syntext/theme.css: CSS must not contain </style>
✗ docs/_syntext/theme.css: CSS may load only https:// URLs (found "http://cdn.example.com/a.woff2")
✗ docs/_syntext/*.css: combined CSS is 61.2KB; the limit is 50KB
✗ docs/_syntext/app.js: script is 12.3KB; the limit is 10KB
⚠ docs/_syntext/app.js: _syntext/app.js runs only when "Scripts from your docs" is on in Integrations › Custom code (off by default), and never on previews
⚠ _syntext/: ignored: docs/_syntext/ exists and takes precedence. Move these files into docs/_syntext/.
•
Errors fail the publish too — fix them before you push. Every message and its fix is in What's refused.
•
Each script and head.html gets a warning that it runs only when its switch is on, and never on previews.
•
A linked project (one with a 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.
•
Both 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.

CheckDescription
Signature driftAnnotated signatures still match the stored hashes
Unannotated exportsExported symbols missing @stx (with --require-annotations)
Style guideAnnotations satisfy .syntext/style-guide.json

Explain your appearance

bash
stx check --explain appearance

Instead of checking, prints how your site's look is resolved:

1.
Whether the site renders with doc engine v1 or v2, and which preset. On a v1 site it shows what the site would look like on v2.
2.
Values — every 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.
3.
Tokens set on top — what themeOverrides, then the legacy colors and fonts keys, set.
4.
Contrast — the accent's link text (needs 4.5:1) and fills (need 3:1) in light and dark mode, with the nearest passing shade when one fails. It is measured on the accent that actually renders: a themeOverrides accent or the legacy colors.primary wins over appearance.accent.
5.
Problems — any value the resolver rejected.
text
Appearance (syntext.json)
Renders with doc engine v1 (theme "default").
The values below are what the site would look like on v2 (workbench preset). Name a preset in theme, or add appearance, to switch.
Values (preset → v1 theme → features → organization theme → appearance)
accent.light #E4512B preset workbench preset
accent.dark #E4512B preset workbench preset
mode light preset workbench preset
...
Tokens set on top (themeOverrides, then the legacy colors and fonts keys)
colors.light.accent-strong #2AC3DE legacy colors.accent
colors.dark.accent-strong #2AC3DE legacy colors.accent
Contrast (accent #E4512B on the workbench page background)
✓ light link 5.13:1, needs 4.5:1.
✓ light fill 3.81:1, needs 3:1.
✓ dark link 7.10:1, needs 4.5:1.
✓ dark fill 5.16:1, needs 3:1.

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

yaml
- name: Validate docs
run: stx check --strict

Pre-commit hook

bash
# .husky/pre-commit
stx check --strict

Exit codes

CodeMeaning
0No errors (warnings are allowed unless --strict)
1Errors found — a broken link, annotation drift at error level, any issue under --strict — or the check couldn't run

Common issues

Deprecated syntax

text
⚠ docs/guide.mdx:12: <Caution> is deprecated. Use <Warning> instead.

Fix: run stx migrate --dry-run to see the rewrite, then stx migrate to apply it. See Deprecated syntax.

Unknown key

text
⚠ syntext.json:3: Unknown key "nmae" is ignored. Did you mean "name"?

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.

text
✗ getting-started.mdx: Broken link: /setup

Fix: update the link to an existing page or create the missing page.

•
stx migrate — rewrite deprecated syntax
•
Deprecated syntax — every deprecated form and the policy
•
syntext.json — the configuration reference
Was this page helpful? Yes No
Previous
Product
Resources
Company
© 2026 SyntextBuilt with Syntext