Validate & lint STYLE.md

Three surfaces run the same linter against a STYLE.md document. This guide shows each and what the rules catch.

The linter returns errors (the file is unusable or misleading) and warnings (quality issues worth fixing). A file is valid when it has no errors.

Validate with the CLI

npx styleref validate lints the STYLE.md in the current directory, offline by default:

npx styleref validate

Add --remote to run the check against the API instead of locally. See the CLI reference.

Validate with the REST API

POST /api/v1/style-md/validate lints a document you send in the body:

curl -X POST "https://styleref.io/api/v1/style-md/validate" \
  -H "Content-Type: text/markdown" \
  --data-binary @STYLE.md

A well-formed file returns:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "meta": { "name": "80s-Inspired Poster", "generator": "styleref.io", "sections": ["colors"] }
}

A failing document still returns HTTP 200 — read the valid field. For example, a bad hex value and a missing generator:

{
  "valid": false,
  "errors": ["Malformed hex color: \"#GGG\" (expected #RGB, #RGBA, #RRGGBB or #RRGGBBAA)."],
  "warnings": ["Frontmatter has no `generator:` line (expected `generator: \"styleref.io\"`)."],
  "meta": { "name": "Test", "generator": null, "sections": ["colors"] }
}

See Endpoints reference for the full contract.

Validate with MCP

Agents connected to the MCP server call the validate_style_md tool with the document text. It returns the same result shape. See Tools reference.

What the linter checks

Errors

• Missing YAML frontmatter (--- … ---) at the top of the file.
• No sections: list, an empty list, or an unknown section id.
• An empty body (no style rules after the frontmatter).
• A malformed hex color (expected #RGB, #RGBA, #RRGGBB, or #RRGGBBAA).

Warnings

• No name: in the frontmatter — agents show the style as unnamed.
• No generator: line — expected generator: "styleref.io".
• No ## headings in the body.
• A section declared in the frontmatter with no matching body section.

See the Format reference for the structure these rules enforce.

Next steps

• Format reference — the structure being validated.
• CLI reference — validate options.
• Endpoints reference — the validate endpoint.