remark-attrs

A Remark plugin for adding attributes (IDs, classes, custom properties) to Markdown elements. This lets you extend Markdown with extra styling and semantic control.

• Installation
• Usage
• Syntax
  • Heading
  • Paragraph
  • List
  • Emphasis
  • Image
  • Code Block
  • Definition List
• Example
• Contributing
• Related
• License

Installation

npm install remark-attrs

Usage

Example: add attributes in Markdown

Input Markdown:

# Hello World  {.title #greeting}

Output HTML:

<h1 class="title" id="greeting">Hello World</h1>

Adding the plugin to a remark chain:

import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'
import remarkAttrs from 'remark-attrs'

const {value} = unified().
  use(remarkParse).
  use(remarkAttrs).
  use(remarkRehype).
  use(rehypeStringify).
  processSync(markdownText)
console.log(String(value))

Syntax

Add classes, IDs, and arbitrary attributes using {} notation. It works with block and inline elements.

• {.class} → adds a class
• {#id} → adds an ID
• {key=value} or {key="value with spaces"} → adds an attribute

Heading

Markdown:

# Top Level Heading      {#top-level-heading}

### H3 Heading          {.third-level-heading}

Top Setext Heading
================
{#top-heading-setext-style}

Second Level Heading
-------------------
{class=second-level-setext-heading}

HTML:

<h1 id="top-level-heading">Top Level Heading</h1>

<h3 class="third-level-heading">H3 Heading</h3>

<h1 id="top-heading-setext-style">Top Setext Heading</h1>

<h2 class="second-level-setext-heading">Second level Heading</h2>

Paragraph

Markdown:

Attributes for paragraphs should be placed at the end of the text. {#paragraph-example} 

HTML:

<p id="paragraph-example">Attributes for paragraphs should be placed at the end of the text.</p

List

Unordered List

Markdown:

- Item 1  {.first-item}
- Item 2
- Item 3
{#list-1 .list .unordered-list}

HTML:

<ul id="list-1" class="list unordered-list">
  <li class="first-item">Item 1</li>
  <li>Item 2</li>
  <li>Item 3</li>
</ul>

Ordered List

Markdown:

1) A  {.item-1}
2) B  {.item-2}
3) C  {.item-3}
4) D  {.item-4}
{#list-2 .list .ordered-list}

HTML:

<ol id="list-2" class="list ordered-list">
    <li class="item-1">A</li>
    <li class="item-2">B</li>
    <li class="item-3">C</li>
    <li class="item-4">D</li>
</ol>

Nested Lists

Markdown:

- Item 1
  - Item 1.1  {.nested-list-first-item}
  - Item 1.2
  {#nested-list-1 .nested-list}
- Item 2
- Item 3
  - Item 3.1
  {#nested-list-2 .nested-list}
{#list-3 .list .unordered-list}

HTML:

<ul id="list-3" class="list unordered-list">
    <li>Item 1</li>
    <ul id="nested-list-1" class="nested-list">
        <li class="nested-list-first-item">Item 1.1</li>
        <li>Item 1.2</li>
    </ul>
    <li>Item 2</li>
    <li>Item 3</li>
    <ul id="nested-list-2" class="nested-list">
        <li>Item 3.1</li>
    </ul>
</ul>

Emphasis

Markdown:

Some **bold** {.strong} and *italics*{.em} text.

HTML:

<p>Some <strong class="strong">bold</strong> and <em class="em">italics</em> text.</p>

Image

Markdown:

![Image Description](images/picture.jpg) {.full-width}

HTML:

<p><img src="images/picture.jpg" alt="Image Description" class="full-width"/></p>

Code Block

Markdown:

``` {.js-code #js-for}
for (const item of list) {
  console.log(item)
}
```

HTML:

<pre><code id="js-for" class="js-code">
for (const item of list) {
  console.log(item)
}
</code></pre>

Definition List

Using the remark-definition-list plugin

Markdown:

Markdown  {.term}
: A lightweight markup language for creating formatted text using a plain-text editor. {.def}

HTML      {.term}
: The standard markup language for documents designed to be displayed in a web browser. {.def}

HTML:

<dl>
    <dt class="term">Markdown</dt>
    <dd class="def">A lightweight markup language for creating formatted text 
        using a plain-text editor.</dd>
    
    <dt class="term">HTML</dt>
    <dd class="def">The standard markup language for documents designed to be 
        displayed in a web browser.</dd>
</dl>

Example

Input Markdown:

# Document

{#id-for-h1}

You can easily add attributes to the various markdown elements like **this 
bold text**{.bold-text} or [the link](https://github.com){.link-to-github} or 
the paragraph itself.{#first-paragraph}

Ordered (`<ol>`{.ordered}) and unordered (`<ul>`{.unordered}) lists are also 
supported:

- Item 1  {.first-item}
- Item 2
  - Item 2.1  {.second-level-item}
- Item 3  {.last-item}
{#ul-id}

1) First Item  {.first-item value=1}
2) Second Item {value=2}
3) Third Item  {#last-ordered-list-item value=3}

Output HTML:

<h1 id="id-for-h1">Document</h1>
<p id="first-paragraph">You can easily add attributes to the various markdown 
    elements like 
    <strong class="bold-text">this
    bold text</strong> or <a href="https://github.com" class="link-to-github">the link</a> or
    the paragraph itself.</p>
<p>Ordered (<code class="orderered">&#x3C;ol></code>) and unordered (<code class="unordered">&#x3C;ul></code>) lists are also
    supported:</p>
<ul id="ul-id">
    <li class="first-item">Item 1</li>
    <li>Item 2
        <ul><li class="second-level-item">Item 2.1</li></ul>
    </li><li class="last-item">Item 3</li>
</ul>
<ol>
    <li class="first-item" value="1">First Item</li>
    <li value="2">Second Item</li>
    <li id="last-ordered-list-item" value="3">Third Item</li>
</ol>

Contributing

Contributions, issues, and feature requests are welcome!
Feel free to open an issue or submit a pull request.

Related

• remark-gen-toc – Generate a table of contents for a markdown document
• remark-definition-list – Support definition lists in Markdown

License

MIT © Anatoly Nechaev