Lint rules

leadtype lint validates source MDX before generation. Run it in CI to fail PRs on schema and link issues before they reach a build. CLI flags are documented in the CLI reference — this page covers the rules, schemas, and library API.

import { lintDocs } from "leadtype/lint";

Rules

Grouped by what they catch.

Frontmatter rules

unknown-field upgrades to error with --error-unknown. Treat parse-error as the highest priority — it blocks every other check.

Content / link rules

GEO rules

The geo:* rules are the mechanical half of Write for agents & GEO — the structure signals a linter can check. The editorial ones (lead-with-the-answer, question-form headings) can't be linted; that's what the guide is for. All three are warn-level: legitimate exceptions exist, so they never fail the build by default (gate with --max-warnings if you want them to). The same checks feed the Structure portion of leadtype score.

Linting renders MDX through the default remark stack before walking links — same flattening the converter performs, so link checks see the final URLs.

The unflattened-component rule walks the MDX AST, so components inside code fences or inline code are examples — not rendered JSX — and never warn. It recognizes the built-in tag contract plus any custom defineComponentFlattener plugins declared in your config.

Library API

import { lintDocs } from "leadtype/lint";

const result = await lintDocs({
  srcDir: "docs",
  unknownFieldSeverity: "error",
});

Default ignore patterns: **/shared/**, **/_shared/**, **/_partials/**, **/node_modules/**.

Result shape

type LintResult = {
  violations: Array<{
    file: string;
    kind: "frontmatter" | "changelog" | "meta" | "content";
    severity: "error" | "warn";
    rule:
      | "schema"
      | "unknown-field"
      | "parse-error"
      | "invalid-link"
      | "unresolved-placeholder"
      | "cross-framework-link"
      | "unflattened-component"
      | "jsonld"
      | "geo:heading-skip"
      | "geo:code-language"
      | "geo:image-alt";
    field?: string;
    message: string;
  }>;
  summary: {
    filesScanned: number;
    errors: number;
    warnings: number;
  };
};

Required-field failures are reported as schema violations — that's the public rule for missing or invalid required fields.

Default schemas

Docs frontmatter

lastModified and lastAuthor are produced by leadtype generate when git metadata is available. Don't author them.

Page status is editorial metadata. Release channels such as canary, RC, preview, and stable should be modeled in build config or transformers, not in source-authored page status.

Changelog frontmatter

meta.json

Custom schemas

Pass a Valibot schema to extend or replace the defaults:

import * as v from "valibot";
import { lintDocs } from "leadtype/lint";

const customFrontmatter = v.object({
  title: v.pipe(v.string(), v.minLength(1)),
  audience: v.picklist(["beginner", "advanced"]),
});

await lintDocs({
  srcDir: "docs",
  schemas: { frontmatter: customFrontmatter },
});

Once you provide a custom schema, unknown-field warnings apply to that schema. Add --error-unknown in CI to keep your contract strict.

Practical guidance

• Run lint before leadtype generate so content errors fail fast.
• Use --format github in GitHub Actions and --format json in any other CI.
• Treat unresolved-placeholder as a content bug first — usually a missing entry in variants or a stale URL template.
• After a docs move, lint and run meta.json updates together; they drift at the same time.

For wiring lint into pipelines, see Validate in CI.