Remarkable

Remarkable converts markdown to HTML by scanning content and producing a list of tokens. Tokens represent either markdown syntax or plain text. All tokens include the following properties:

• type: The type of the token.
• level: The nesting level of the associated markdown structure in the source.

Tokens generated by block parsing rules also include a lines property, which is a 2-element array marking the first and last line of the src used to generate the token.

When implementing a block rule, you must decide if your block allows other Markdown blocks to be nested inside it.

• To allow nesting: Invoke state.parser.tokenize(state, startLine, endLine, true). This allows the next batch of rules to run on the content within your block's boundaries.
• To disallow nesting: Simply push a new inline token containing the content of the block. You can use state.getLines(begin, end, indent, keepLastLF) to retrieve this content.

Install Remarkable via npm for Node.js environments:

npm install remarkable --save

For browser usage, you can use the jsDelivr CDN or cdnjs.

Plugins are extensions for Remarkable loaded using the md.use(plugin[, opts]) method, where md is your Remarkable instance. A plugin is a function that accepts two arguments:

1. md: The Remarkable instance.
2. options: The options object provided to md.use.

Plugins typically add parsing and rendering rules or modify the Remarkable instance directly.

To create a custom rendering rule, define a function that accepts four specific arguments. Each rule is registered with a name that must correspond to a token's type. The function must return the appropriate HTML string for that token.

Arguments:

• tokens: The list of tokens currently being processed.
• idx: The index of the token currently being processed.
• options: The options object provided to remarkable during initialization.
• env: The key-value store created by the parsing rules.

Important Constraint: Rendering rules are not provided with helpers to recursively invoke the renderer. You should not attempt to call the renderer recursively within a rule.

Remarkable converts Markdown to HTML in two steps: parsing raw text into tokens, and rendering those tokens into HTML. To extend the syntax, you must add rules to the appropriate ruler.

Adding Parsing Rules

Parsing rules are categorized into core, block, and inline. To add a rule, access the relevant parser from the Remarkable instance and use its ruler. For example, to add an inline rule for strike-through:

md.inline.ruler.push("strike-through", strikeThroughInlineRule, { strokesCount: 2 });

Adding Rendering Rules

To add a rendering rule, use the md.renderer.rules object following the same pattern as parsing rules.

When typographer: true is set, Remarkable performs automatic replacements for common typographical characters (e.g., (c) to ©, -- to –). You can customize the quotes option to change the replacement pairs for different languages.

import { Remarkable } from 'remarkable';
var md = new Remarkable({
  typographer: true,
  quotes: '“”‘’'
});

// To disable specific typographical rules:
md.core.ruler.disable([ 'replacements', 'smartquotes' ]);

The linkify plugin automatically converts URL-like text into clickable links.

import { Remarkable } from 'remarkable';
import { linkify } from 'remarkable/linkify';

var md = new Remarkable().use(linkify);

Footnotes

• Reference: [^first]
• Inline: ^[Text of inline footnote]
• Definition: [^first]: Footnote text.

Abbreviations

Define abbreviations using the following syntax to convert them into HTML <abbr> tags: *[HTML]: Hyper Text Markup Language

To highlight fenced code blocks, provide a highlight function in the options object. This function receives the code string and the language identifier.

import { Remarkable } from 'remarkable';
import hljs from 'highlight.js'

var md = new Remarkable({
  highlight: function (str, lang) {
    if (lang && hljs.getLanguage(lang)) {
      try {
        return hljs.highlight(lang, str).value;
      } catch (err) {}
    }

    try {
      return hljs.highlightAuto(str).value;
    } catch (err) {}

    return ''; // use external default escaping
  }
});