remark-lint-frontmatter-schema

3.15.4 verified Fri May 01 auth: no javascript

Validate Markdown frontmatter YAML against an associated JSON schema using remark-lint. Current version: 3.15.4 (released Oct 2023). Released regularly with bug fixes. Key differentiators: supports JSON Schema draft-07, both in-file $schema and global pattern associations, auto-fixes, integration with VS Code and ESLint MDX, and CLI reporting. Uses ajv for validation.

Common errors

error Error: Cannot find module 'remark-lint-frontmatter-schema' ↓

cause Package not installed or incorrect import path.

fix

Run npm install remark-lint-frontmatter-schema and ensure import path is correct.

error TypeError: plugin is not a function ↓

cause Importing the module incorrectly (e.g., named import instead of default).

fix

Use default import: import plugin from 'remark-lint-frontmatter-schema'

error ValidationError: data must have required property 'title' ↓

cause Frontmatter missing required fields as per schema.

fix

Add the missing required fields to the frontmatter YAML.

error Error: No schema defined for pattern '*.md' ↓

cause Glob pattern in configuration doesn't match any defined schema.

fix

Check the schemas array configuration and ensure the pattern matches the file being processed.

Warnings

gotcha Schema must be a valid JSON Schema (draft-07) object. Invalid schemas will fail silently or throw obscure errors. ↓

fix Validate your schema against JSON Schema meta-schema before use.

breaking From v3.0.0, the plugin changed from a custom configuration format to using a `schemas` array with `pattern` and `schema` objects. Old `schemaPath` option removed. ↓

fix Update configuration to new format: { schemas: [{ pattern: '*.md', schema: {...} }] }

deprecated The `schemaPath` option was deprecated in v3.0.0 and removed in v3.14.0. ↓

fix Use `schemas` array with inline schema or `$ref` to external file.

gotcha In-file `$schema` key in frontmatter is only supported if the schema URL is an HTTP(S) URL or a relative file path. Absolute file paths are not supported. ↓

fix Use relative paths (e.g., `$schema: ./schema.json`) or a URL. For local schemas, ensure the file resolves relative to the working directory.

gotcha The plugin only validates the first YAML block in the Markdown file even if multiple YAML blocks exist. It treats the first YAML as frontmatter. ↓

fix Ensure that only one YAML frontmatter block exists, or the first one is the intended frontmatter.

Install

npm install remark-lint-frontmatter-schema

yarn add remark-lint-frontmatter-schema

pnpm add remark-lint-frontmatter-schema

Imports

remarkLintFrontmatterSchema

wrong

const { remarkLintFrontmatterSchema } = require('remark-lint-frontmatter-schema')

correct

import remarkLintFrontmatterSchema from 'remark-lint-frontmatter-schema'

Default export is a function that returns a remark plugin. CommonJS require is also supported.

default

wrong

const { default: plugin } = require('remark-lint-frontmatter-schema')

correct

const plugin = require('remark-lint-frontmatter-schema')

In CJS, default export is accessed directly via require, not destructured.

remarkLintFrontmatterSchema

wrong

import { remarkLintFrontmatterSchema } from 'remark-lint-frontmatter-schema'

correct

import remarkLintFrontmatterSchema from 'remark-lint-frontmatter-schema'

This is a default export, not named export. Named import will result in undefined.

Quickstart

Set up a remark processor with remark-lint and remark-lint-frontmatter-schema, validate frontmatter against a JSON schema, and see lint messages.

import { readSync } from 'fs';
import { remark } from 'remark';
import remarkLint from 'remark-lint';
import remarkLintFrontmatterSchema from 'remark-lint-frontmatter-schema';

const processor = remark()
  .use(remarkLint)
  .use(remarkLintFrontmatterSchema, {
    schemas: [
      {
        pattern: '*.md',
        schema: {
          type: 'object',
          properties: {
            title: { type: 'string' },
            date: { type: 'string', format: 'date' }
          },
          required: ['title', 'date']
        }
      }
    ]
  });

const result = processor.processSync(
  '---\ntitle: Hello\ndate: 2023-01-01\n---\n# Content'
);

console.log(result.messages);
// [] (no errors)

const result2 = processor.processSync(
  '---\ntitle: 123\ndate: not-a-date\n---\n# Content'
);

console.log(result2.messages);
// [ { message: 'title: must be string', ... } ]