@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.

Table of Contents

1. Installation
2. Configuration
3. Code of Conduct
4. Contributing
5. Changelog
6. 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,
      },
    },
  ],
});

Additional options

enableRehype (defaults to 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);
    });
  };
}

Code of Conduct

See CODE_OF_CONDUCT

Contributing

To contribute to eleventy-plugin-remark, follow these steps:

1. Fork this repository.
2. Create a branch: git checkout -b <branch_name>.
3. Install dependencies: npm install
4. Make your changes (and don't forget to update the tests)
5. Don't forgot to run the tests: npm test
6. Commit your changes: git commit -m '<commit_message>'
7. Push to the original branch: git push origin <project_name>/<location>
8. Create the pull request.

Alternatively see the GitHub documentation on creating a pull request.

Changelog

Version 4.0.0 (13 November 2023)

• #148 Update dependencies (by Porges)
• #149 Execute unit and integration tests on Node 18, 19 and 20
• New minimum Node version is 16.x

Version 3.1.1 (30 April 2022)

• #101 Create processor for each render to allow per-page data

Version 3.1.0 (29 April 2022)

• #100 Pass Eleventy Data to Remark

Version 3.0.0 (6 January 2022)

• #87 Upgrade to latest remark (with support for ESM) (by j-f1)

Version 2.2.2 (9 November 2021)

• Update dependencies
• Add official support for Node 16.x and Node 17.x

Version 2.2.1 (18 February 2021)

• #60 Update .npmignore
• #61 Add Node 15.x to CI test matrix
• #62 Update Rollup config: update externals, explicitly set default export

Version 2.2.0 (18 February 2021)

• #58 Update dependencies
• #59 Add option to enable rehype (defaults to true)

Version 2.1.0 (1 December 2020)

• #55 Use rehype-stringify instead of remark-html to convert to HTML
• Update dependencies

Version 2.0.0 (3 October 2020)

• #35 Add support for plugin options (by byoigres)
• Update dependencies
• Minimum Node version is now 10.x

v1.0.2 (2 December 2019)

• Update README and links in package.json

v1.0.0 (2 December 2019)

• Initial release

License

This project is licenses under the MIT License.