rm.hbs

[![view on npm](https://img.shields.io/npm/v/@uttori/plugin-renderer-markdown-it.svg)](https://www.npmjs.com/package/@uttori/plugin-renderer-markdown-it)
[![npm module downloads](https://img.shields.io/npm/dt/@uttori/plugin-renderer-markdown-it)](https://www.npmjs.com/package/@uttori/plugin-renderer-markdown-it)
[![Build Status](https://travis-ci.com/uttori/uttori-plugin-renderer-markdown-it.svg?branch=master)](https://app.travis-ci.com/github/uttori/uttori-plugin-renderer-markdown-it)
[![Coverage Status](https://coveralls.io/repos/uttori/uttori-plugin-renderer-markdown-it/badge.svg?branch=master)](https://coveralls.io/r/uttori/uttori-plugin-renderer-markdown-it?branch=master)

# Uttori Renderer - Markdown - MarkdownIt

Uttori renderer support for Markdown powered by [MarkdownIt](https://markdown-it.github.io/).

This also includes a MarkdownIt plugin you can use seperately that supports:

* Generate a Table of Contents based on `H#` header tags with `[toc]`
* Adding a URL prefix
* Properly handle external domains with `noopener noreferrer` and optionally set up allowed domains for `nofollow` SEO support to curb spam
* Support for `[^1] ... [^1]: Footnote` Footnotes based on [markdown-it-footnote](https://github.com/markdown-it/markdown-it-footnote)
* Support for [WikiLinks](https://en.wikipedia.org/wiki/Help:Link#Wikilinks_(internal_links)) style linking
* Support for adding [Lazy Loading](https://developer.mozilla.org/en-US/docs/Web/Performance/Lazy_loading) tags to `img` tags
* Support for adding YouTube iframe videos
* Support for `<br> or <br/> or <br />` style line breaks anywhere, useful for tables
* Support for `<video src="/uploads/example.mp4">` video embeds with allowed domains filtering
* Support for adding color to spans with `[Text](color:#ffadad)`
* Parse to tokens for building an AST (abstract syntax tree) using `MarkdownItRenderer.parse(content, config)`

## Install

```bash
npm install --save @uttori/plugin-renderer-markdown-it
```

## Config

Configuration outside of registration events and Uttori specific items is avaliable by passing in [MarkdownIt](https://github.com/markdown-it/markdown-it#init-with-presets-and-options) config.

```js
{
  // Registration Events
  events: {
    renderContent: [],
    renderCollection: [],
    validateConfig: [],
    viewModelDetail: [],
  },

  // MarkdownIt Configuration
  // Enable HTML tags in source
  html: false,

  // Use '/' to close single tags (<br />).
  xhtmlOut: false,

  // Convert '\n' in paragraphs into <br>, this is only for full CommonMark compatibility.
  breaks: false,

  // CSS language prefix for fenced blocks. Can be useful for external highlighters.
  langPrefix: 'language-',

  // Autoconvert URL-like text to links.
  linkify: false,

  // Enable some language-neutral replacement + quotes beautification.
  typographer: false,

  // Double + single quotes replacement pairs, when typographer enabled, and smartquotes on. Could be either a String or an Array.
  // For example, you can use '«»„“' for Russian, '„“‚‘' for German, and ['«\xA0', '\xA0»', '‹\xA0', '\xA0›'] for French (including nbsp).
  quotes: '“”‘’',

  // Highlighter function. Should return escaped HTML, or '' if the source string is not changed and should be escaped externally.
  // If result starts with <pre... internal wrapper is skipped.
  // highlight: (/* str, lang */) => '',

  // Any other supported MarkdownIt configuration
  ...,

  // Custom Values for Uttori Specific Use
  uttori: {
    // Prefix for relative URLs, useful when the Express app is not at root.
    baseUrl: '',

    // Good Noodle List, f a domain is not in this list, it is set to 'external nofollow noreferrer'.
    allowedExternalDomains: [],

    // Open external domains in a new window.
    openNewWindow: true,

    // Add lazy loading params to image tags.
    lazyImages: true,

    // Footnotes
    footnotes: {
      // A funciton to return the default HTML for a footnote reference.
      referenceTag: ({ id, label }) => {
        return `...`;
      },

      // A funciton to return the default opening HTML for a footnote definition.
      definitionOpenTag: ({ id, label }) => {
        return `...`;
      },

      // The default closing HTML for a footnote definition.
      definitionCloseTag: '</div>\n',
    },

    // Table of Contents
    toc: {
      // The opening DOM tag for the TOC container.
      openingTag: '<nav class="table-of-contents">',

      // The closing DOM tag for the TOC container.
      closingTag: '</nav>',

      // Slugify options for convering headings to anchor links.
      slugify: {
        lower: true,
      },
    },

    // WikiLinks
    wikilinks: {
      // Slugify options for convering Wikilinks to anchor links.
      slugify: {
        lower: true,
      },
    },
  },
}
```

### Table of Contents Generation

You can generate a table of contents based on the headers in a file. Example:

```md
# First
## Second
### Third
### Third Again
#### Fouth

## Second Again
### Third Last
Content

[toc]
```

Will render to a minified version of:

```html
<p>
  <nav class="table-of-contents">
    <ul class="table-of-contents-h1">
      <li><a href="#first-0" title="First">First</a></li>
      <li><ul class="table-of-contents-h2">
        <li><a href="#second-1" title="Second">Second</a></li>
        <li><ul class="table-of-contents-h3">
          <li><a href="#third-2" title="Third">Third</a></li>
          <li><a href="#third-again-3" title="Third Again">Third Again</a></li>
          <li><ul class="table-of-contents-h4">
            <li><a href="#fouth-4" title="Fouth">Fouth</a></li>
          </ul></li>
        </ul></li>
        <li><a href="#second-again-6" title="Second Again">Second Again</a></li>
        <li><ul class="table-of-contents-h3">
          <li><a href="#third-last-7" title="Third Last">Third Last</a></li>
        </ul></li>
      </ul></li>
    </ul>
  </nav>
  Content Content
</p>
```

### Footnotes

This allos for adding footnotes & their definitions.

```md

`ADC (dp,X)`[^1]

[^1]: Add 1 cycle if m=0 (16-bit memory/accumulator)
```

### YouTube Embedding

This allows safe embedding of YouTube videos. Example:

```md
<youtube v="XG9dCoTlJYA" start="0" width="560" height="315" title="YouTube Video Player" start="0">
```

Will render to a minified version of:

```html
<div class="youtube-embed">
  <iframe class="youtube-embed-video" width="560" height="315" src="https://www.youtube-nocookie.com/embed/aR3fVuLEtj8?start=0" title="YouTube Video Player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen="true"></iframe>
</div>
```

The only required parameter is `v`:

```md
<youtube v="aR3fVuLEtj8">
```

Will render to a minified version of:

```html
<div class="youtube-embed">
  <iframe class="youtube-embed-video" width="560" height="315" src="https://www.youtube-nocookie.com/embed/aR3fVuLEtj8?start=0" title="" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen="true"></iframe>
</div>
```

### Colored Text

You can add colored text with special links:

```md
[Text](color:#ffadad)
[Text](color:#ffd6a5)
[Text](color:#fdffb6)
[Text](color:#caffbf)
[Text](color:#9bf6ff)
[Text](color:#A0C4FF)
[Text](color:#bdb2ff)
[Text](color:#ffcff8)
[Text](color:#fffffc)
[Text](color:rgba(0,0,0,0.5))
```

* * *

## API Reference

{{>main}}

* * *

## Tests

To run the test suite, first install the dependencies, then run `npm test`:

```bash
npm install
npm test
DEBUG=Uttori* npm test
```

## Contributors

* [Matthew Callis](https://github.com/MatthewCallis)

## License

* [MIT](LICENSE)