@md-reader/markdown-it-front-matter

Plugin for processing front matter for markdown-it markdown parser.

Markdown Reader's fork of parksb/markdown-it-front-matter. It targets markdown-it 15.0.2 or later within v15 and uses its bundled TypeScript types. The raw-text callback and hidden front_matter token API are unchanged. The v15 renderer no longer inserts a leading blank line before a heading that follows hidden front matter. Custom renderers can still read the raw string from token.meta (narrow it from unknown in TypeScript).

Install

$ npm install markdown-it@^15.0.2 @md-reader/markdown-it-front-matter

Valid Front Matter

Essentially, valid front matter is a fenced block:

• Indicated by three or more dashes: ---
• Opening and closing fences must be the same number of dash characters
• Opening fence must begin on the first line of the markdown string/file
• Opening fence must not be indented

---
valid-front-matter: true
---

The example above uses YAML but YAML is not required

(bring your own front matter parser)

Example

• Front Matter is not rendered.
• Any markup inside the block is passed to the required callback function.

const md = require('markdown-it')()
  .use(require('@md-reader/markdown-it-front-matter'), function(fm) {
    console.log(fm)
  });

let result = md.render('---\ntitle: This is the Title\n---\n# Heading\n----\nsome text');

// > title: This is the Title

ES modules / TypeScript

import MarkdownIt from 'markdown-it'
import frontMatter from '@md-reader/markdown-it-front-matter'

const md = new MarkdownIt().use(frontMatter, (rawMeta: string) => {
  console.log(rawMeta)
})

Development

Use Node.js 22 or 24, run npm ci, then npm test to check the upstream behavior and CommonJS/ES module TypeScript consumers. Publish with npm publish --access public.

References / Thanks

Code heavily borrowed from markdown-it-container

• Alex Kocharin github/rlidwka
• Vitaly Puzrin github/puzrin

License

markdown-it-front-matter is distributed under the MIT License - see the LICENSE file for details.