Add attributes, IDs and classes to Markdown.
This is some text.
<!--{.center}-->
<p class='center'>This is some text.</p>
const md = require('markdown-it')
.use(require('markdown-it-decorate'), opts)
Create an HTML comment in the format <!-- {...} -->
, where ...
can be a .class
, #id
, key=attr
or a combination of any of them. Be sure to render markdownIt with html: true
to enable parsing of <!--{comments}-->
.
It will be applied to the deepest thing it's seen; ie, a blockquote containing a bold link (> **[link]**
) will style the innermost element: the link.
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.
Source | Output |
---|---|
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'> |
Annotations will apply itself 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} -->
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">
<ul>
<li class="wide">
<a href="#continue" class="button">Continue</a>
</li>
</ul>
</blockquote>
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}-->
You can decorate fenced code blocks. Indented code blocks are not supported, unfortunately.
```
return true
```
<!-- {code: .lang-javascript} -->
-
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).
ricostacruz.com · GitHub @rstacruz · Twitter @rstacruz