Necessarily Precedes Mischief

    @julian_cataldo/remark-lint-frontmatter-schema
    TypeScript icon, indicating that this package has built-in type declarations

    3.4.0 • Public • Published

    remark-lint-frontmatter-schema

    NPM prettier PRs Welcome ISC License Downloads

    Validate Markdown frontmatter YAML against an associated JSON schema with this remark-lint rule plugin.

    Supports:

    • Types validation, pattern, enumerations,… and all you can get with JSON Schema
    • Code location problems indicator (for IDE to underline)
    • Auto-fixes with suggestions
    • Command Line Interface reporting
    • VS Code integration (see below)
    • Global patterns or in-file schemas associations
    • In JS framework MD / MDX pipelines

    Demo

    Demo screenshot of frontmatter schema linter

    👉  See ./demo



    Quick start

    Installation

    pnpm install -D \
    remark remark-cli \
    remark-frontmatter \
    @julian_cataldo/remark-lint-frontmatter-schema

    Remove -D flag for runtime unified MD / MDX pipeline (custom, Astro, Gatsby, etc.), for production.
    Keep it if you just want to lint with CLI or your IDE locally, without any production / CI needs.

    VS Code (optional)

    code --install-extension unifiedjs.vscode-remark
    

    Configuration

    👉  See ./demo folder to get a working, pre-configured, bare project workspace.
    You also get example markdown files and associated schema to play with.
    Supports remark-cli and/or unifiedjs.vscode-remark extension.

    📌  Check out the demo/README.md for bootstrapping it.

    Workspace

    Create root config file for remark to source from:
    touch ./.remarkrc.mjs

    Paste this base config:

    import remarkFrontmatter from 'remark-frontmatter';
    import rlFmSchema from '@julian_cataldo/remark-lint-frontmatter-schema';
    
    const remarkConfig = {
      plugins: [remarkFrontmatter, rlFmSchema],
    };
    export default remarkConfig;

    Schemas associations

    Inspired by VS Code JSON Schema and redhat.vscode-yaml conventions.

    Schema example

    creative-work.schema.yaml

    type: object
    properties:
      title:
        type: string
    #

    Inside frontmatter

    See ./demo/content files for examples.

    Schema association can be done directly inside the frontmatter of the markdown file, relative to project root, thanks to the '$schema' key:

    ---
    '$schema': /content/creative-work.schema.yaml
    
    title: Hello there
    category: Book
    #
    ---
    
    # You're welcome!
    
    🌝  My **markdown** content…  🌚
    …

    🆕  Globally, with patterns

    Note:
    Locally defined '$schema' takes precedence over global settings below.

    const remarkConfig = {
      plugins: [
        remarkFrontmatter,
        [
          rlFmSchema,
          {
            schemas: {
              /* One schema for many files */
              './content/creative-work.schema.yaml': [
                /* Support glob patterns */
                './content/*-creative-work.md',
                /* Or direct file association */
                './content/the-one.md',
              ],
              './content/ghost.schema.yaml': [
                './content/casper.md',
                './content/ether.md',
              ],
            },
          },
        ],
      ],
    };

    './foo', '/foo', 'foo', all will work.
    It's always relative to your ./.remarkrc.mjs file, in your workspace root.

    CLI / IDE (VS Code) - linting

    Linting whole workspace files (as ./**/*.md) with remark-cli:

    pnpm remark .

    Yields:

    #
    content/correct-creative-work.md
      1:1  warning  /category: Must be equal to one of the allowed values  frontmatter-schema  remark-lint
      1:1  warning  /complex/some: Must be string                          frontmatter-schema  remark-lint
    
    ⚠ 6 warnings

    MD / MDX pipeline

    Use it as usual like any remark plugin inside your framework or your custom unified pipeline.

    🆕  Custom pipeline - runtime

    When processing markdown as single files inside your JS/TS app.

    This is different to static linting as demonstrated above.
    It will not source .remarkrc (still, you can source it by your means if you want).
    In fact, is not aware of your file structure, nor it will associated or import any schema files.
    That way, it will integrate easier with your own plugin / framework systems.

    Schema should be provided programmatically like this:

    // …
    import remarkFrontmatter from 'remark-frontmatter';
    import rlFmSchema from '@julian_cataldo/remark-lint-frontmatter-schema';
    import type { JSONSchema7 } from 'json-schema';
    import { reporter } from 'vfile-reporter';
    
    const mySchema: JSONSchema7 = {
      /* … */
    };
    
    const output = await unified()
      // Your pipeline
      .use(remarkParse)
      // …
      .use(remarkFrontmatter)
      .use(rlFmSchema, {
        /* Bring your own schema */
        embed: mySchema,
      })
      // …
      .use(remarkRehype)
      .use(rehypeStringify)
      .use(rehypeFormat)
      // …
      .process(theRawMarkdownLiteral);
    
    output.path = './the-current-processed-md-file.md';
    
    console.error(reporter([output]));

    Yields:

    ./the-current-processed-md-file.md
      1:1  warning  Must have required property 'tag'  frontmatter-schema  remark-lint
    
    ⚠ 1 warning
    

    Framework

    Warning
    WIP. NOT tested yet!

    Astro

    In astro.config.mjs

    // …
    export default defineConfig({
      // …
      remarkPlugins: [
        // …
        'remark-frontmatter',
        '@julian_cataldo/remark-lint-frontmatter-schema',
        // …
      ];
      // …
    });
    Gatsby

    In gatsby-config.js

    {
      // …
      plugins: [
        // …
        {
          resolve: 'gatsby-transformer-remark',
          options: {
            plugins: [
              // …
              'remark-frontmatter',
              '@julian_cataldo/remark-lint-frontmatter-schema',
              // …
            ],
          },
        },
        // …
      ];
    }

    Using:

    Major dependencies:

    ajv, yaml, remark, remark-frontmatter, unified, remark-cli


    See CHANGELOG.md for release history.


    🔗  JulianCataldo.com

    Install

    npm i @julian_cataldo/remark-lint-frontmatter-schema

    DownloadsWeekly Downloads

    779

    Version

    3.4.0

    License

    ISC

    Unpacked Size

    466 kB

    Total Files

    20

    Last publish

    Collaborators

    • julian.cataldo