mdschema

Lint the structure of your Markdown, not just its style.

Declare what your docs must contain in a small YAML schema,
then validate, scaffold, and enforce it in CI.

Installation · Quick Start · Schema Reference · GitHub Action · Examples

Style linters tell you a line is too long. mdschema tells you the README is missing its ## Installation section, that the install section has no bash snippet, or that a blog post's date isn't a valid date.

The same schema also generates a ready-to-fill template for new documents, and can be derived from a document you already like.

• Schema-driven — describe the expected document in plain YAML, with nested sections and repeatable headings
• Content rules — require or forbid text, code blocks by language, images, tables, lists, and word counts per section
• Frontmatter checks — required fields, types, formats (date, email, url), enums, and nested keys
• Link checks — internal anchors, relative files, and (optionally) external URLs
• Dynamic headings — match headings against the filename with expressions like slug(filename) == slug(heading)
• Templates both ways — generate a skeleton from a schema, or derive a schema from an existing document
• AST-based — parses Markdown properly, so headings inside code blocks never confuse it
• Runs anywhere — single static binary for Linux, macOS, and Windows; also on npm and as a GitHub Action
• Editor support — JSON Schema for completion and inline validation of .mdschema.yml

brew install jackchuka/tap/mdschema

npm install -g @jackchuka/mdschema
# or run without installing
npx @jackchuka/mdschema check README.md

go install github.com/jackchuka/mdschema/cmd/mdschema@latest

Download a prebuilt binary from the releases page.

git clone https://github.com/jackchuka/mdschema.git
cd mdschema
go build -o mdschema ./cmd/mdschema

1. Create a schema — start from defaults, or infer one from a document you already like:

   mdschema init                              # writes .mdschema.yml
   mdschema derive README.md -o .mdschema.yml # or derive it from README.md

2. Validate your Markdown files:

   mdschema check README.md "docs/**/*.md"

3. Scaffold a new document that already satisfies the schema:

   mdschema generate -o new-doc.md

Every command accepts --schema <path> (default: .mdschema.yml).

A schema has one structure tree plus optional document-wide rules:

structure: [...] # expected sections, in order
heading_rules: { ... } # heading levels and uniqueness
links: { ... } # link validation
frontmatter: { ... } # YAML frontmatter validation

Each entry in structure (and in any children) describes one section:

…and these content rules, checked inside that section:

Use expr to match headings dynamically, for example to require that my-file.md starts with # My File:

structure:
  - heading:
      expr: "slug(filename) == slug(heading)"
    children:
      - heading: "## Features"

Variables: filename (without extension), heading (heading text), level (1–6).

heading_rules:
  no_skip_levels: true # disallow h1 -> h3 without h2
  unique: true # all headings must be unique
  unique_per_level: false # unique within the same level only
  max_depth: 4 # deepest allowed heading (h4)

links:
  validate_internal: true # anchors like (#section)
  validate_files: true # relative files like (./file.md)
  validate_external: false # external URLs (slower)
  external_timeout: 10 # seconds
  allowed_domains: [github.com, golang.org]
  blocked_domains: [example.com]

Frontmatter is required once a frontmatter block exists; fields are required unless marked optional.

frontmatter:
  optional: false
  fields:
    - { name: "title", type: string }
    - { name: "date", format: date }
    - { name: "author", optional: true, format: email }
    - { name: "tags", optional: true, type: array, enum: [go, cli, markdown] }
    - { name: "status", enum: [draft, published, archived] }
    - { name: "metadata.version" } # nested key via dot-notation

• Types: string, number, boolean, array, date, object
• Formats: date (YYYY-MM-DD), email, url
• Enums: with type: array, every element must be listed. Entries are checked against the declared type/format when the schema loads, so an enum no value could satisfy (e.g. { type: number, enum: [low, high] }) is reported as a schema warning.
• Nested keys: metadata.author validates author under metadata. Escape a literal dot with a backslash: name: "weird\\.key".

name: Docs
on: [push, pull_request]

jobs:
  mdschema:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jackchuka/mdschema@v0.15.3
        with:
          files: "README.md docs/**/*.md"
          schema: ".mdschema.yml"

For a monorepo, point working-directory at the package (e.g. ./packages/docs).

.mdschema.yml has a JSON Schema for completion, hover docs, and validation in any editor using the YAML Language Server (VS Code, Neovim, JetBrains, …). Add this line to the top of the file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json

Or map it once in VS Code's settings.json:

{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json": ".mdschema.yml"
  }
}

Complete schema + document pairs live in examples/:

structure:
  - heading: { pattern: "# .*" }
    children:
      - heading: "## Prerequisites"
      - heading: { pattern: "## Step [0-9]+: .*" }
        count: { min: 1, max: 0 } # one or more steps
        code_blocks: [{ min: 1 }] # each step needs a code block
      - heading: "## Next Steps"
        optional: true

structure:
  - heading: "# Project Name"
    allow_additional: true # authors may add FAQ, Troubleshooting, ...
    children:
      - heading: "## Overview"
      - heading: "## Installation"
        code_blocks: [{ lang: bash, min: 1 }]

go test ./...
go build -o mdschema ./cmd/mdschema

Contributions are welcome! For major changes, please open an issue first to discuss what you would like to change. See CONTRIBUTING.md for details.

MIT