remark-code-frontmatter

Extract frontmatter from markdown code blocks using remark and front-matter, and do interesting things!

For example:

• Add properties that add indentation to your code
• Add properties that indicate how the given code should wrap
• Add properties that specify links that should be attached to the HTML output of your code
• Add properties that specify which sort of syntx highlighting should be used
• Add properties that specify other ways in which HTML output should be manipulated

... The possibilities are endless!

This plugin is compatible with most remark syntax highlighting plugins, including remark-midas, remark-tree-sitter and remark-highlight.js. Just make sure that you use this plugin before the highlighting plugins.

You can also use this plugin with remark-code-extra to use frontmatter data in additional HTML output for your code blocks.

Install

npm:

npm install remark-code-frontmatter

Use

An additional field frontmatter is added to all code MDAST nodes for later use.

Say we have the following Markdown file, example.md:

```c
---
wrap: c-main
---
printf("Hello, World!");
return 0;
```

```c
// Some other code
```

And our script, example.js, looks as follows:

const vfile = require('to-vfile')
const report = require('vfile-reporter')
const unified = require('unified')
const visit = require('unist-util-visit');
const markdown = require('remark-parse')
const html = require('remark-html')
const codeFrontmatter = require('remark-code-frontmatter');

// Wrap code in boilerplate where neccesary
const transformer = tree => {
  visit(tree, 'code', node => {
    if (node.frontmatter.wrap === 'c-main') {
      node.value = [
        '#include<stdio.h>',
        'int main()',
        '{',
        // indent
        ...node.value.split('\n').map(line => '  ' + line),
        `}`,
      ].join('\n');
    }
  });
  return tree;
};

unified()
  .use(markdown)
  .use(codeFrontmatter)
  .use(() => transformer)
  .use(html)
  .process(vfile.readSync('example.md'), (err, file) => {
    console.error(report(err || file))
    console.log(String(file))
  })

Now, running node example yields:

example.md: no issues found
<pre><code class="language-c">#include&#x3C;stdio.h>
int main()
{
  printf("Hello, World!");
  return 0;
}
</code></pre>
<pre><code class="language-c">// Some other code
</code></pre>

Use with code highlighters

This plugin is compatible with most remark syntax highlighting plugins, including remark-midas, remark-tree-sitter and remark-highlight.js. Just make sure that you use this plugin before the highlighting plugins.

Example:

unified()
  .use(markdown)
  .use(codeFrontmatter)
  .use(highlight) // comes AFTER codeFrontmatter, could be other highlighting plugins
  // Other plugins
  .use(html)

Use with remark-code-extra

You can access the markdown from within the transform function that you pass to the options for that plugin.

For example, if you had the following markdown:

```
---
before: Some header text
---
Code block with a header
```

```
---
after: Some footer text
---
Code block with a footer
```

```
---
before: Some header text
after: Some footer text
---
Code block with a header and footer
```

```
Code block with no header or footer
```

And the following unified processor:

// other imports
const codeFrontmatter = require('remark-code-frontmatter');
const codeExtra = require('remark-code-extra');

const processor = remark()
  .use(codeFrontmatter)
  .use(codeExtra, {
    transform: node => node.frontmatter.before || node.frontmatter.after ? {
      before: node.frontmatter.before && [{
        type: 'text',
        value: node.frontmatter.before
      }],
      after: node.frontmatter.after && [{
        type: 'text',
        value: node.frontmatter.after
      }]
    } : null
  })
  .use(html);

Then this would output the following HTML:

<div class="code-extra">Some header text<pre><code>Code block with a header</code></pre></div>
<div class="code-extra"><pre><code>Code block with a footer</code></pre>Some footer text</div>
<div class="code-extra">Some header text<pre><code>Code block with a header and footer</code></pre>Some footer text</div>
<pre><code>Code block with no header or footer
</code></pre>

API

remark().use(codeFrontmatter)

Extract frontmatter from markdown code blocks using front-matter.

Related

• remark-midas — Highlight CSS code blocks with midas (rehype compatible)
• remark-tree-sitter — Highlight code with tree-sitter (rehype compatible)
• remark-highlight.js — Highlight code with highlight.js (via lowlight)
• remark-code-extra — Add to or transform the HTML output of code blocks (rehype compatible)