Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jgarber623/eleventy-plugin-markdown
An Eleventy plugin for processing Markdown files with markdown-it.
https://github.com/jgarber623/eleventy-plugin-markdown
11ty 11ty-plugin eleventy eleventy-plugin markdown markdown-it
Last synced: 4 months ago
JSON representation
An Eleventy plugin for processing Markdown files with markdown-it.
- Host: GitHub
- URL: https://github.com/jgarber623/eleventy-plugin-markdown
- Owner: jgarber623
- License: mit
- Created: 2024-01-13T16:43:22.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-07-15T15:24:46.000Z (7 months ago)
- Last Synced: 2024-09-29T13:22:53.879Z (4 months ago)
- Topics: 11ty, 11ty-plugin, eleventy, eleventy-plugin, markdown, markdown-it
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/@jgarber/eleventy-plugin-markdown
- Size: 418 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# eleventy-plugin-markdown
**An [Eleventy](https://www.11ty.dev) plugin for processing Markdown files with [markdown-it](https://markdown-it.github.io).**
[](https://www.npmjs.com/package/@jgarber/eleventy-plugin-markdown)
[](https://www.npmjs.com/package/@jgarber/eleventy-plugin-markdown)
[](https://github.com/jgarber623/eleventy-plugin-markdown/actions/workflows/ci.yml)
## Usage
First, add the plugin as [a development dependency](https://docs.npmjs.com/cli/configuring-npm/package-json#devdependencies) to your project's `package.json` file:
```sh
npm install --save-dev @jgarber/eleventy-plugin-markdown
```
Next, add the plugin to your project's [Eleventy configuration file](https://www.11ty.dev/docs/config#default-filenames) (e.g. `eleventy.config.js`):
```js
module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(require('@jgarber/eleventy-plugin-markdown'));
};
```
### Filters
With no additional configuration, eleventy-plugin-markdown will configure markdown-it and add a `markdown` [filter](https://www.11ty.dev/docs/filters) for use in your Eleventy project's templates.
In [a JavaScript template](https://www.11ty.dev/docs/languages/javascript) (e.g. `post.11ty.js`), you might use the `markdown` filter to process a post's title to properly render typographic quotes. The optional second argument, `'inline'`, instructs the filter to use [`MarkdownIt.renderInline`](https://markdown-it.github.io/markdown-it#MarkdownIt.renderInline) which will not wrap the output in a `
` element.
```js
module.exports = class {
render({ collections }) {
const post = collections.post[0];
return JSON.stringify({
title: this.markdown(post.data.title, 'inline')
});
}
};
```
Or, in [a Liquid template](https://www.11ty.dev/docs/languages/liquid) (e.g. `post.liquid`):
```liquid
{{ post.data.title | markdown: "inline" }}
```
> [!TIP]
> Omit the `inline` argument/option to wrap the processed output in `
` elements. Using the examples above: `this.markdown(post.data.title)` and `{{ post.data.title | markdown }}`.
## Options
| Name | Type(s) | Default |
|:----------|:---------|:--------------------------------------------------|
| `preset` | `String` | `default` |
| `options` | `Object` | `{ breaks: true, html: true, typographer: true }` |
| `plugins` | `Array` | `[]` |
| `rules` | `Object` | `{}` |
See [the `MarkdownIt.new` documentation](https://markdown-it.github.io/markdown-it#MarkdownIt.new) for details on additional `preset` and `options` values.
### Plugins
The `plugins` option accepts an Array whose elements may be plugin functions or an Array of a plugin function and an Object of options. Each element in the `plugins` Array is passed directly to [`MarkdownIt.use`](https://markdown-it.github.io/markdown-it#MarkdownIt.use).
```js
module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(require('@jgarber/eleventy-plugin-markdown'), {
plugins: [
require('markdown-it-footnote'),
[require('markdown-it-handle'), { attributes: false }]
]
});
};
```
### Renderer Rules
The `rules` option accepts an Object whose keys are tokens and values are functions conforming to [markdown-it's `Renderer#rules` interface](https://markdown-it.github.io/markdown-it#Renderer.prototype.rules). Various plugins (like [markdown-it-footnote](https://www.npmjs.com/package/markdown-it-footnote)) support this kind of customization.
```js
module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(require('@jgarber/eleventy-plugin-markdown'), {
plugins: [require('markdown-it-footnote')],
rules: {
footnote_block_open: () => `
Footnotes
\n\n`,
footnote_block_close: () => '
\n'
}
});
};
```
## ESM Support
Eleventy v3.0.0 [added bundler-free ESM support](https://www.11ty.dev/blog/canary-eleventy-v3). This plugin works with either ESM or CommonJS projects!
```js
import markdownPlugin from '@jgarber/eleventy-plugin-markdown';
export default async function(eleventyConfig) {
eleventyConfig.addPlugin(markdownPlugin);
}
```
## Acknowledgments
First and foremost, eleventy-plugin-markdown wouldn't be possible without [Zach Leatherman](https://www.zachleat.com)'s incredible work creating Eleventy and his stewardship of its community.
eleventy-plugin-markdown is written and maintained by [Jason Garber](https://sixtwothree.org).