Home

Awesome

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>

Status

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)

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

SourceOutput
> > Hi *world* <!-- {.red} --><blockquote><blockquote>Hi <em class='red'>world...
> > Hi *world* <!-- {blockquote:.red} --><blockquote><blockquote class='red'>Hi <em>world...
> > Hi *world* <!-- {blockquote^1:.red} --><blockquote class='red'><blockquote>Hi <em>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 <!--{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

Motivation

markdown-it-decorate is inspired by the design of those features and improves on them:

Thanks

markdown-it-decorate © 2015-2017, Rico Sta. Cruz. Released under the MIT License.<br> Authored and maintained by Rico Sta. Cruz with help from contributors (list).

ricostacruz.com  ·  GitHub @rstacruz  ·  Twitter @rstacruz