markdown-it-decorate
v1.2.2
Add classes, identifiers and attributes to your markdown with HTML comments
0/weekUpdated 3 years agoMIT
Published by Rico Sta. Cruz
npm install markdown-it-decoratemarkdown-it-decorate
> Add attributes, IDs and classes to Markdown
Annotate your Markdown documents with HTML comments to add classes to HTML elements. Supported for and tested on [markdown-it] 6.x, 7.x, and 8.x.
``html`
Hello, from Markdown!
` Hello, from Markdown!html`
Usage
Install the markdown-it-decorate package alongside markdown-it (they are peer dependencies).
`sh`
yarn add --exact markdown-it markdown-it-decorateor:
npm install --save --save-exact markdown-it markdown-it-decorate
markdown-it-decorate can be loaded as a plugin using use().
`js`
const md = require('markdown-it')()
.use(require('markdown-it-decorate'))
Cheatsheet
You can add classes, ID's, or attributes. (See § Annotating elements)
| Source | Output |
|----|----|
| Text |
Text
|
| Text | Text
|
| # Hola | Hola
|
| # Hola | Hola
|
| # Hola | Hola
|
| !Image | 
|You can specify the element name to decorate. (See § Disambiguating)
| Source | Output |
|----|----|
|
# Hi world | Hi world
|
| # Hi world | Hi world
|
| # Hi world | Hi world
|Annotating elements
Create an HTML comment in the format
, where ... can be a .class, #id, key=attr or a combination of any of them. The spaces around {} are optional. Be sure to render markdownIt with html: true to enable parsing of .`html
`You can put the comment in the same line or in the next. I recommend keeping it on a separate line, since this will make GitHub ignore it.
html
Hello!
`html
Hello!
`Disambiguating
By default, annotations will be applied to the deepest element preceding it. In the case below,
will be applied to the link ("Next").`md
> This is a blockquote
>
> * It has a list.
> * You can specify tag names. Next
>
`$3
To make it apply to a different element, precede your annotations with the tag name followed by a
.`md
> * It has a list.
> * You can specify tag names. Next
`$3
You can combine them as you need. In this example, the link gets
, the list item gets .wide, and the blockquote gets .bordered.`md
> * Continue
`html
`$3
To go back to previous parent with the same name, add
after the tag name, where n is how many levels deep to go back to. Using ^0 is the same as not specifying it at all. (This convention is taken from gitrevisions.)`md
> > > targets 3rd quote
`md
> > > targets 2nd quote
`md
> > > targets 1st quote
`$3
You can decorate code blocks. You may choose to decorate
, code, or even both.
`
return true;
Indented code blocks are only supported in markdown-it 7.x or later.
// this is a code block
return true;
Prior art
* This is initially based off of arve0/markdown-it-attrs which uses text to annotate blocks (eg,
). markdown-it-attr's approach was based off of Pandoc's header attributes.* Maruku (Ruby Markdown parser) also allows for block-level attributes and classnames with its meta-data syntax. The syntax is similar to PanDoc's syntax (
{: .class #id}).* Kramdown (Ruby markdown parser) also supports the same syntax, also with a colon (
{: .class #id}`).Motivation
markdown-it-decorate is inspired by the design of those features and improves on them:
* Elements are marked via HTML comments; they'll be invisible to other Markdown parsers like GitHub's.
* It supports inline elements in addition to block elements.
Thanks
markdown-it-decorate © 2015+, Rico Sta. Cruz. Released under the [MIT] License.
Authored and maintained by Rico Sta. Cruz with help from contributors ([list][contributors]).
> ricostacruz.com ·
> GitHub @rstacruz ·
> Twitter @rstacruz
[MIT]: http://mit-license.org/
[contributors]: http://github.com/rstacruz/markdown-it-decorate/contributors
[markdown-it]: https://www.npmjs.com/package/markdown-it