@e11ty/eleventy-plugin-markdown

An Eleventy markdown plugin enhancement around markdown-it. This plugin includes necessary plugins and some normalization logic for building static sites in 11ty.

NOTE This enhancement plugin is tailored to my specific development approach and to some degree that tooling I use and maintain. Universal usage might require adjustments in certain contexts due to its custom nature.

Included

The enhancement comes with markdown-it installed as a dependency, along with the following markdown-it plugins.

• markdown-it-anchor
• markdown-it-attrs

Install

The @11ty/eleventy module is a peer and needs to be installed along side it.

pnpm add @e11ty/eleventy-plugin-markdown -D

Usage

There is a named export of markdown which expects the eleventyConfig be provided. The options parameter can be used to hook into the transform cycles and is also where you can control the included plugins options. Optionally use with 11ty.ts wrapper for type completions.

const { defineConfig } = require('11ty.ts'); // Optional
const { markdown } = require('@e11ty/eleventy-plugin-markdown');
const papyrus = require('papyrus');

module.exports = defineConfig(eleventyConfig => {

  const md = markdown(eleventyConfig, {
    highlight: {
      fence: ({ raw, language, escape }) => `<h1>${language}</h1><p>Override codeblock</p>`,
      block: ({ raw, language, escape }) => papyrus.highlight(raw, { language }),
      inline: ({ raw, language }) => papyrus.inline(raw, { language })
    },
    anchors: {
      attrs: [ ['spx-node', 'spy.anchor'] ],
      plugin: { /* plugin options */ }
    },
    options: {
      html: true,
      linkify: true,
      typographer: true,
      breaks: false
    }
  })

});

Enhancements

The plugin provides a refined set of enhancements for both markdown and liquid.

• Grid Container
• Syntax Highlighting
• Anchors
• Blockquote
• Filters

Grid System

Grid access is made possible using 2 character fenced markers in markdown. Occurences of :: signal for div and the suffixed words will be added as class names result in encapsulate content being wrapped.

Markdown Input

Use the minimum of 3 :: colon for open/close containers.

:: row jc-center ai-center
:: col-sm-6 col-md-4

# Header

Lorem ipsum dolor sit...

::
:: col-6 col-md-8

**bold** ipsum dolor sit...

::
::

Markup Output

The resulting output of the above will generate the following markup.

<div class="row jc-center ai-center">
  <div class="col-sm-6 col-md-4">
    <h1>Header</h1>
    <p>Lorem ipsum dolor sit...</p>
  </div>
  <div class="col-6 col-md-8">
   <p>
    <strong>bold</strong> Lorem ipsum dolor sit...
   </p>
  </div>
</div>

Syntax Highlighting

Markdown codeblock regions will be passed to the highlight property and call either block or inline functions when structures are encountered. Designed for usage with Papyrus.

Codeblock

Markdown codeblock will fire the block() method. Papyrus determines whether to render editor or not.

```js
const foo = 'bar'; // Comment
```

Fence Block

You can override the default code blocks to pass something more expressive than <pre>, this can be done by using fence(). You cannot use both fence() and block(), only one is possible.

markdown(eleventyConfig, {
  highlight: {
    fence({ language, raw, escape }) {
      if (language.endsWith(':foo')) {
        return `<h1>${language}</h1>`;
      }

      return papyrus.highlight(raw, { language });
    }
  }
});

Inline Code

Papyrus support inline code highlighting and fires the inline() method. Signal inline code as follows:

`{html} <h1>HTML</h1>`
`{js} someMethod()`
`{liquid} {% if %}`

The single literal quotes with single whitespace to trigger inline highlighting, e.g: {:language} code

Anchors

Link anchors support scroll-spy logic. This uses the markdown-it-anchors plugin under the hood and provides an attrs helper for assigning additional attributes to heading blocks. The existence of and anchors array value contained in the frontmatter of a markdown page will determine whether or not anchor annotations apply.

Frontmatter

The anchors frontmatter data will be used to generate the markup and also applies annotation to headings.

---
anchors:
  Group Name:
    - Some Title
    - Another Title
  Second Group:
    - Foo
    - Bar
    - Baz
---

# Some Title

Anchor Filter

Liquid output tags accept an | anchor filter which result in the href value being hash id.

| Syntax | Example | | ------ | ------------------------------------------------------------ | | Liquid | <a href="{{ href \| anchor }}" spx-node="spy.href">Link<a> | | Markup | <a href="#some-title" spx-node="spy.href">Link<a> |

Heading Annotation

The heading values provided to frontmatter anchors will be matched and result in the following.

| Syntax | Example | | -------- | ------------------------------------------------------------------------- | | Markdown | # Some Title | | Markup | <h1 id="some-title" tabindex="-1" spx-node="spy.anchor">Some Title</h1> |

Blockquote

Control the class="" values of blockquote occurrences within markdown. Whenever a blockquote begins with a colon prefixed value of :class it will be applied as the class name.

Markdown Example

The :class annotation in markdown will simply add the class name/s.

> :class note fs-xl
> This will be a note blockquote

---

> :class warn fw-bold
> This will be a warning blockquote

Filters

An additional | md Liquid filter is made available. This md filter will apply inline rendering.

| Filter | Example | | ------ | ------------------- | | md | {{ value \| md }} |

License

Apache 2.0