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

Hello, from *Markdown*!
<!-- {.center} -->

<p class='center'>Hello, from <em>Markdown</em>!</p>

Usage

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')()
  .use(require('markdown-it-decorate'))

Cheatsheet

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 <!-- {.center.red} --> | <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:.red} --> | <h1 class='red'>Hi <em>world</em></h1> | | # *Hi* *world* <!-- {em^1:.red} --> | <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}-->
<!-- {.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} -->

Disambiguating

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} -->

Combining

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">
  <ul>
    <li class="wide">
      <a href="#continue" class="button">Continue</a>
    </li>
  </ul>
</blockquote>

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}).

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

ricostacruz.com  ·  GitHub @rstacruz  ·  Twitter @rstacruz