markdown-it-container-handler

The markdown-it-container plugin is quite powerful, but can take a lot of boilerplate code to add multiple containers. This package provides a class that tries to help in that regard.

This has been tested mostly via the version of markdown-it embedded in the eleventy static website generator.

Example Usage

This example is in the form of an eleventy config file, but you can use the library with any instance of markdown-it.

It shows a few additional plugins being added as well to give an idea of how the plugins can work together. The markdown-it-attrs plugin in particular is fully supported, and highly recommended as a complimentary plugin.

/// <eleventy.config.js>

const {EleventyRenderPlugin} = require('@11ty/eleventy');
const YAML = require('js-yaml'); // to support YAML data files
const ConHand = require('markdown-it-container-handler');

/**
 * Each item in this array is a nested array of arguments
 * to be passed to the markdownIt.use() method.
 */
const mdPlugins = 
[
  // The `attrs` plugin is a great compliment to `containers`.
  // Should always be used BEFORE any containers so that it will
  // process any {.class #id attr="foo"} rules first.
  [require('markdown-it-attrs')],

  [ // Enhanced table syntax plugin, with some plugin options set.
    require('markdown-it-multimd-table'),
    {
      multiline: true,
      rowspan: true,
    },
  ],

  // Building an instance and calling use() method on it.
  // 
  // :::details Summary text here {.my-class}
  // Content for the details block.
  // Note that in order to support the `attrs` plugin, you need to
  // use the `data.attrs` getter attribute in the element string;
  // {.my-class} is an example attribute rule.
  // :::
  //
  (new ConHand('details_block', {
    validate(tag) {
      return tag?.name === 'details';
    },
    render(data) {
      if (data.isOpen) {
        return `<details${data.attrs}><summary>${data.tag.param}</summary>\n`;
      }
      else {
        return '</details>\n';
      }
    },
  })).use(),

  // Using the static use() wrapper method.
  //
  // :::section {#my-id}
  // Content of section block here.
  // You could also use 'blockquote' or 'div' containers.
  // The render() method uses data.renderToken(), so these simple blocks
  // support the `attrs` plugin automatically; {#my-id} is an example.
  // :::
  //
  ConHand.use('simple_blocks', {
    TAGS: new Set(['blockquote','div','section']),
    validate(tag) {
      return tag?.name && this.TAGS.has(tag.name);
    },
    render(data) {
      return data.renderToken(data.tag.name);
    },
  }),

  // A simple container where the id is also the tag name.
  //
  // :::help
  // Help text here
  // :::
  //
  ConHand.use('help', {
    render(data) {
      return data.renderToken(data.tag.name);
    }
  }),

]; // markdown-it plugins

module.exports = function(eleventyConfig) {
  eleventyConfig.addDataExtension('yaml', (data) => YAML.load(data));
  eleventyConfig.addPlugin(EleventyRenderPlugin);
  eleventyConfig.ammendLibrary('md', (mdLib) => {
    // mdLib is the markdown-it instance.
    for (let plugin of mdPlugins) {
      mdLib.use(...plugin);
    }
  });
}

module.exports.config = {
  dir: {
    output:   'out',
    input:    'src',
    data:     '_data',
    layouts:  '_layouts',
    includes: '_parts',
  },
  htmlTemplateEngine:     'liquid',
  markdownTemplateEngine: 'liquid',
  templateFormats: ['html','md','11ty.js'],
}

Official URLs

This library can be found in two places:

• Github
• NPM

Author

Timothy Totten [email protected]

License

MIT