Add classes, identifiers and attributes to your markdown with HTML comments
Last updated 4 years ago by rstacruz .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install markdown-it-decorate 
SYNC missed versions from official npm registry.


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.

Hello, from *Markdown*!
<!-- {.center} -->
<p class='center'>Hello, from <em>Markdown</em>!</p>



Install the markdown-it-decorate package alongside markdown-it (they are peer dependencies).

yarn add --exact markdown-it markdown-it-decorate
# or:
npm install --save --save-exact markdown-it markdown-it-decorate

markdown-it-decorate can be loaded as a plugin using use().

const md = require('markdown-it')()


You can add classes, ID's, or attributes. (See § Annotating elements)

Source Output
Text <!--{.center}--> <p class='center'>Text</p>
Text <!-- {.center} --> <p class='center'>Text</p>
# Hola <!-- {} --> <h1 class='center red'>Hola</h1>
# Hola <!-- {#top .hide} --> <h1 id='top' class='hide'>Hola</h1>
# Hola <!-- {data-show="true"} --> <h1 data-show='true'>Hola</h1>
![Image](img.jpg)<!-- {width=20} --> <img src='img.jpg' alt='Image' width='20'>

You can specify the element name to decorate. (See § Disambiguating)

Source Output
# Hi *world* <!-- {.red} --> <h1>Hi <em class='red'>world</em></h1>
# Hi *world* <!-- {} --> <h1 class='red'>Hi <em>world</em></h1>
# *Hi* *world* <!-- {em^} --> <h1><em class='red'>Hi</em> <em>world</em></h1>

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 <!--{comments}-->.

<!-- {.class} -->
<!-- {.class1.class2} -->
<!-- {.class1 .class2} -->
<!-- {#id} -->
<!-- {attr="val"} -->

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.

# Hello! <!-- {.center} -->
# Hello!
<!-- {.center} -->


By default, annotations will be applied to the deepest element preceding it. In the case below, .wide will be applied to the link ("Next").

> This is a blockquote
> * It has a list.
> * You can specify tag names. [Next](#next)
> <!-- {.wide} -->

Specifying elements

To make it apply to a different element, precede your annotations with the tag name followed by a :.

> * It has a list.
> * You can specify tag names. [Next](#next) <!-- {li:.wide} -->


You can combine them as you need. In this example, the link gets .button, the list item gets .wide, and the blockquote gets .bordered.

> * [Continue](#continue)
<!-- {a:.button} -->
<!-- {li:.wide} -->
<!-- {blockquote:.bordered} -->
<blockquote class="bordered">
    <li class="wide">
      <a href="#continue" class="button">Continue</a>

Selecting same names

To go back to previous parent with the same name, add ^n 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.)

> > > targets 3rd quote <!--{blockquote:.wide}-->
> > > targets 2nd quote <!--{blockquote^1:.wide}-->
> > > targets 1st quote <!--{blockquote^2:.wide}-->

Decorating code blocks

You can decorate code blocks. You may choose to decorate pre, code, or even both.

return true;
<!-- {code: .lang-javascript} -->

Indented code blocks are only supported in markdown-it 7.x or later.

    // this is a code block
    return true;

<!-- {code: .lang-javascript} -->

Prior art

  • This is initially based off of arve0/markdown-it-attrs which uses text to annotate blocks (eg, {.class #id}). 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}).


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.


markdown-it-decorate © 2015+, Rico Sta. Cruz. Released under the MIT License.
Authored and maintained by Rico Sta. Cruz with help from contributors (list).  ·  GitHub @rstacruz  ·  Twitter @rstacruz

Current Tags

  • 1.2.2                                ...           latest (4 years ago)

9 Versions

  • 1.2.2                                ...           4 years ago
  • 1.2.1                                ...           5 years ago
  • 1.2.0                                ...           5 years ago
  • 1.1.0                                ...           5 years ago
  • 1.0.0                                ...           5 years ago
  • 0.3.1                                ...           5 years ago
  • 0.3.0                                ...           5 years ago
  • 0.2.0                                ...           5 years ago
  • 0.1.0                                ...           5 years ago

Copyright 2014 - 2016 © |