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