@fec/eleventy-plugin-remark

Eleventy plugin to process Markdown files with Remark

With @fec/eleventy-plugin-remark you can transpile the Markdown of your Eleventy site with Remark. You can also use Remark plugins.

Made by 👨‍💻Florian Eckerstorfer in beautiful 🎡 Vienna, Europe.

Installation
Configuration
Code of Conduct
Contributing
Changelog
License

Installation

You need to install eleventy-plugin-remark with NPM and it requires at least Node 16.x.

npm install -D @fec/eleventy-plugin-remark

⚠️ Since v3.0.0 eleventy-plugin-remark supports ESM and it should be possible to use recent versions of remark. However, please remember that Eleventy does not fully support ESM yet. See the Eleventy ESM Support project for their progress.

If you do not need ESM support yet you can still use eleventy-plugin-remark v2.x. Here are a couple of Remark/Rehype packages and the last version that works with Eleventy:

remark            ^13.0.0
rehype-stringify   ^8.0.0
remark-rehype      ^8.1.0
remark-html       ^13.0.1

Configuration

To activate @fec/eleventy-plugin-remark you call addPlugin() on eleventyConfig, like this:

// .eleventy.js
const eleventyRemark = require('@fec/eleventy-plugin-remark');

module.exports = (eleventyConfig) => {
  eleventyConfig.addPlugin(eleventyRemark);
  return {};
};

If you want to add custom Remark plugins, use the plugins option.

Signatures

plugins: [<plugin-function|plugin-name>, ...<plugin-n>]
plugins: [[{ plugin: <plugin> }], ...[{ plugin: <plugin-n>, options: <plugin-options> }]]

const emoji = require('remark-emoji');

eleventyConfig.addPlugin(eleventyRemark, {
  plugins: [
    emoji,
    require('remark-emoji'),
    'remark-emoji',
    {
      plugin: emoji,
    },
    {
      plugin: 'remark-emoji',
      options: {
        padSpaceAfter: true,
        emoticon: true,
      },
    },
  ],
});

If true the plugins remark-rehype and rehype-stringify are added to the processor. Set enableRehype to false if you want either not use remark-rehype and rehype-stringify at all or if you want to call these plugins with custom options. For example, to enable HTML inside your Markdown you need to use rehype-raw:

eleventyConfig.addPlugin(eleventyRemark, {
  enableRehype: false,
  plugins: [
    {
      plugin: remarkRehype,
      options: { allowDangerousHtml: true }
    },
    rehypeRaw,
    rehypeStringify
  ],
});

Using Eleventy Data

eleventy-plugin-remark passes Eleventy supplied data to remark. Plugins can use this data in their Markdown processing. For example, the following plugin access the date of the current page:

import { visit } from 'unist-util-visit';

export default function myRemarkPlugin() {
  const eleventy = this.data().eleventy;
  return (tree) => {
    visit(tree, (node) => {
      console.log('date', eleventy.page.date);
    });
  };
}