metalsmith@metalsmith/markdown
A Metalsmith plugin to render markdown files to HTML, using Marked (by default).
Features
- Compiles
.mdand.markdownfiles inmetalsmith.source()to HTML. - Enables rendering file or metalsmith metadata keys to HTML through the keys option
- Define a dictionary of markdown globalRefs (for links, images) available to all render targets
- Supports using the markdown library of your choice through the render option
Installation
NPM:
npm install @metalsmith/markdown
Yarn:
yarn add @metalsmith/markdown
Usage
@metalsmith/markdown is powered by Marked (by default), and you can pass any of the Marked options to it, including the 'pro' options: renderer, tokenizer, walkTokens and extensions.
import markdown from '@metalsmith/markdown'
import hljs from 'highlight.js'
// use defaults
metalsmith.use(markdown())
// use explicit defaults
metalsmith.use({
wildcard: false,
keys: [],
engineOptions: {}
})
// custom
metalsmith.use(
markdown({
engineOptions: {
highlight: function (code) {
return hljs.highlightAuto(code).value
},
pedantic: false,
gfm: true,
tables: true,
breaks: false,
sanitize: false,
smartLists: true,
smartypants: false,
xhtml: false
}
})
)
@metalsmith/markdown provides the following options:
keys: Key names of file metadata to render to HTML in addition to itscontents- can be nested key pathswildcard(default:false) - Expand*wildcards inkeysoption keypathsglobalRefs- An object of{ refname: 'link' }pairs that will be available for all markdown files and keys, or ametalsmith.metadata()keypath containing such objectrender- Specify a custom render function with the signature(source, engineOptions, context) => string.contextis an object with the signature{ path:string, key:string }where thepathkey contains the current file path, andkeycontains the target metadata key.engineOptionsOptions to pass to the markdown engine (default marked)
Rendering metadata
You can render markdown to HTML in file or metalsmith metadata keys by specifying the keys option.
The keys option also supports dot-delimited key-paths. You can also use globalRefs within them
metalsmith
.metadata({
from_metalsmith_metadata: 'I _shall_ become **markdown** and can even use a [globalref][globalref_link]',
markdownRefs: {
globalref_link: 'https://johndoe.com'
}
})
.use(
markdown({
keys: {
files: ['html_desc', 'nested.data'],
global: ['from_metalsmith_metadata']
},
globalRefs: 'markdownRefs'
})
)
You can even render all keys at a certain path by setting the wildcard option and using a globstar * in the keypaths.
This is especially useful for arrays like the faq below:
metalsmith.use(
markdown({
wildcard: true,
keys: ['html_desc', 'nested.data', 'faq.*.*']
})
)
A file page.md with front-matter:
---
html_desc: A **markdown-enabled** _description_
nested:
data: '#metalsmith'
faq:
- q: '**Question1?**'
a: _answer1_
- q: '**Question2?**'
a: _answer2_
---
would be transformed into:
{
"html_desc": "A <strong>markdown-enabled</strong> <em>description</em>\n",
"nested": {
"data": "<h1 id=\"metalsmith\">metalsmith</h1>\n"
},
"faq": [
{ "q": "<p><strong>Question1?</strong></p>\n", "a": "<p><em>answer1</em></p>\n" },
{ "q": "<p><strong>Question2?</strong></p>\n", "a": "<p><em>answer2</em></p>\n" }
]
}
Notes about the wildcard
- It acts like the single bash globstar. If you specify
*this would only match the properties at the first level of the metadata. - If a wildcard keypath matches a key whose value is not a string, it will be ignored.
- It is set to
falseby default because it can incur some overhead if it is applied too broadly.
Defining a dictionary of markdown globalRefs
Markdown allows users to define links in reference style ([]:).
In a Metalsmith build it may be especially desirable to be able to refer to some links globally. The globalRefs options allows this:
metalsmith.use(
markdown({
globalRefs: {
twitter_link: 'https://twitter.com/johndoe',
github_link: 'https://github.com/johndoe',
photo: '/assets/img/me.png'
}
})
)
Now contents of any file or metadata key processed by @metalsmith/markdown will be able to refer to these links as [My Twitter][twitter_link] or ![Me][photo]. You can also store the globalRefs object of the previous example in a metalsmith.metadata() key and pass its keypath as globalRefs option instead.
This enables a flow where you can load the refs into global metadata from a source file with @metalsmith/metadata, and use them both in markdown and templating plugins like @metalsmith/layouts:
metalsith
.metadata({
global: {
links: {
twitter: 'https://twitter.com/johndoe',
github: 'https://github.com/johndoe'
}
}
})
// eg in a markdown file: [My Twitter profile][twitter]
.use(markdown({ globalRefs: 'global.links' }))
// eg in a handlebars layout: {{ global.links.twitter }}
.use(layouts({ pattern: '**/*.html' }))
Custom markdown rendering
You can use a custom renderer by using marked.Renderer()
import markdown from '@metalsmith/markdown'
import { marked } from 'marked'
const markdownRenderer = new marked.Renderer()
markdownRenderer.image = function (href, title, text) {
return `
<figure>
<img src="${href}" alt="${title}" title="${title}" />
<figcaption>
<p>${text}</p>
</figcaption>
</figure>`
}
metalsmith.use(
markdown({
engineOptions: {
renderer: markdownRenderer,
pedantic: false,
gfm: true,
tables: true,
breaks: false,
sanitize: false,
smartLists: true,
smartypants: false,
xhtml: false
}
})
)
Using another markdown library
If you don't want to use marked, you can use another markdown rendering library through the render option. For example, this is how you could use markdown-it instead:
import MarkdownIt from 'markdown-it'
let markdownIt
metalsmith.use(markdown({
render(source, opts, context) {
if (!markdownIt) markdownIt = new MarkdownIt(opts)
if (context.key == 'contents') return mdIt.render(source)
return markdownIt.renderInline(source)
},
// specify markdownIt options here
engineOptions: { ... }
}))
Debug
To enable debug logs, set the DEBUG environment variable to @metalsmith/markdown*:
metalsmith.env('DEBUG', '@metalsmith/markdown*')
CLI Usage
Add @metalsmith/markdown key to your metalsmith.json plugins key
{
"plugins": {
"@metalsmith/markdown": {
"engineOptions": {
"pedantic": false,
"gfm": true,
"tables": true,
"breaks": false,
"sanitize": false,
"smartLists": true,
"smartypants": false,
"xhtml": false
}
}
}
}