https://github.com/uttori/uttori-plugin-renderer-markdown-it

Uttori plugin for rendering Markdown powered by MarkdownIt
https://github.com/uttori/uttori-plugin-renderer-markdown-it
markdown markdownit uttori uttori-wiki
Last synced: 5 months ago
JSON representation
Uttori plugin for rendering Markdown powered by MarkdownIt
Host: GitHub
URL: https://github.com/uttori/uttori-plugin-renderer-markdown-it
Owner: uttori
License: mit
Created: 2019-04-06T00:48:32.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2024-02-20T20:01:02.000Z (over 2 years ago)
Last Synced: 2025-10-09T01:14:56.708Z (9 months ago)
Topics: markdown, markdownit, uttori, uttori-wiki
Language: JavaScript
Homepage: https://wiki.superfamicom.org/
Size: 2.67 MB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 1
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project

README

          [![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 `
 or 
 or 
` style line breaks anywhere, useful for tables

* Support for `` 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 (
).

  xhtmlOut: false,

  // Convert '\n' in paragraphs into 
, 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  '',

  // 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: '\n',

    },

    // Table of Contents

    toc: {

      // The opening DOM tag for the TOC container.

      openingTag: '',

      // The closing DOM tag for the TOC container.

      closingTag: '',

      // 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



  

    


      First

      

        Second

        

          Third

          Third Again

          

            Fouth

          

        

        Second Again

        

          Third Last

        

      

    

  

  Content Content



```

### 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

```

Will render to a minified version of:

```html



  



```

The only required parameter is `v`:

```md

```

Will render to a minified version of:

```html



  



```

### 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

## Classes



MarkdownItRenderer



Uttori MarkdownIt Renderer





## Typedefs





MarkdownItRendererOptions : object









## MarkdownItRenderer

Uttori MarkdownIt Renderer

**Kind**: global class  

* [MarkdownItRenderer](#MarkdownItRenderer)

    * [.configKey](#MarkdownItRenderer.configKey) ⇒ string

    * [.defaultConfig()](#MarkdownItRenderer.defaultConfig) ⇒ [MarkdownItRendererOptions](#MarkdownItRendererOptions)

    * [.extendConfig(config)](#MarkdownItRenderer.extendConfig) ⇒ [MarkdownItRendererOptions](#MarkdownItRendererOptions)

    * [.validateConfig(config, _context)](#MarkdownItRenderer.validateConfig)

    * [.register(context)](#MarkdownItRenderer.register)

    * [.renderContent(content, context)](#MarkdownItRenderer.renderContent) ⇒ string

    * [.renderCollection(collection, context)](#MarkdownItRenderer.renderCollection) ⇒ Array.<object>

    * [.render(content, [config])](#MarkdownItRenderer.render) ⇒ string

    * [.parse(content, [config])](#MarkdownItRenderer.parse) ⇒ Array.<module:markdown-it/lib/token>

    * [.cleanContent(content)](#MarkdownItRenderer.cleanContent) ⇒ string

    * [.viewModelDetail(viewModel, context)](#MarkdownItRenderer.viewModelDetail) ⇒ object



### MarkdownItRenderer.configKey ⇒ string

The configuration key for plugin to look for in the provided configuration.

**Kind**: static property of [MarkdownItRenderer](#MarkdownItRenderer)  

**Returns**: string - The configuration key.  

**Example** *(MarkdownItRenderer.configKey)*  

```js

const config = { ...MarkdownItRenderer.defaultConfig(), ...context.config[MarkdownItRenderer.configKey] };

```



### MarkdownItRenderer.defaultConfig() ⇒ [MarkdownItRendererOptions](#MarkdownItRendererOptions)

The default configuration.

**Kind**: static method of [MarkdownItRenderer](#MarkdownItRenderer)  

**Returns**: [MarkdownItRendererOptions](#MarkdownItRendererOptions) - The default configuration.  

**Example** *(MarkdownItRenderer.defaultConfig())*  

```js

const config = { ...MarkdownItRenderer.defaultConfig(), ...context.config[MarkdownItRenderer.configKey] };

```



### MarkdownItRenderer.extendConfig(config) ⇒ [MarkdownItRendererOptions](#MarkdownItRendererOptions)

Create a config that is extended from the default config.

**Kind**: static method of [MarkdownItRenderer](#MarkdownItRenderer)  

**Returns**: [MarkdownItRendererOptions](#MarkdownItRendererOptions) - The new configration.  

| Param | Type | Description |

| --- | --- | --- |

| config | [MarkdownItRendererOptions](#MarkdownItRendererOptions) | The user provided configuration. |



### MarkdownItRenderer.validateConfig(config, _context)

Validates the provided configuration for required entries.

**Kind**: static method of [MarkdownItRenderer](#MarkdownItRenderer)  

| Param | Type | Description |

| --- | --- | --- |

| config | Record.<string, MarkdownItRendererOptions> | A provided configuration to use. |

| _context | object | Unused |

**Example** *(MarkdownItRenderer.validateConfig(config, _context))*  

```js

MarkdownItRenderer.validateConfig({ ... });

```



### MarkdownItRenderer.register(context)

Register the plugin with a provided set of events on a provided Hook system.

**Kind**: static method of [MarkdownItRenderer](#MarkdownItRenderer)  

| Param | Type | Description |

| --- | --- | --- |

| context | object | A Uttori-like context. |

| context.hooks | object | An event system / hook system to use. |

| context.hooks.on | function | An event registration function. |

| context.config | [MarkdownItRendererOptions](#MarkdownItRendererOptions) | A provided configuration to use. |

**Example** *(MarkdownItRenderer.register(context))*  

```js

const context = {

  hooks: {

    on: (event, callback) => { ... },

  },

  config: {

    [MarkdownItRenderer.configKey]: {

      ...,

      events: {

        renderContent: ['render-content', 'render-meta-description'],

        renderCollection: ['render-search-results'],

        validateConfig: ['validate-config'],

      },

    },

  },

};

MarkdownItRenderer.register(context);

```



### MarkdownItRenderer.renderContent(content, context) ⇒ string

Renders Markdown for a provided string with a provided context.

**Kind**: static method of [MarkdownItRenderer](#MarkdownItRenderer)  

**Returns**: string - The rendered content.  

| Param | Type | Description |

| --- | --- | --- |

| content | string | Markdown content to be converted to HTML. |

| context | object | A Uttori-like context. |

| context.config | [MarkdownItRendererOptions](#MarkdownItRendererOptions) | A provided configuration to use. |

**Example** *(MarkdownItRenderer.renderContent(content, context))*  

```js

const context = {

  config: {

    [MarkdownItRenderer.configKey]: {

      ...,

    },

  },

};

MarkdownItRenderer.renderContent(content, context);

```



### MarkdownItRenderer.renderCollection(collection, context) ⇒ Array.<object>

Renders Markdown for a collection of Uttori documents with a provided context.

**Kind**: static method of [MarkdownItRenderer](#MarkdownItRenderer)  

**Returns**: Array.<object> - } The rendered documents.  

| Param | Type | Description |

| --- | --- | --- |

| collection | Array.<object> | A collection of Uttori documents. |

| context | object | A Uttori-like context. |

| context.config | [MarkdownItRendererOptions](#MarkdownItRendererOptions) | A provided MarkdownIt configuration to use. |

**Example** *(MarkdownItRenderer.renderCollection(collection, context))*  

```js

const context = {

  config: {

    [MarkdownItRenderer.configKey]: {

      ...,

    },

  },

};

MarkdownItRenderer.renderCollection(collection, context);

```



### MarkdownItRenderer.render(content, [config]) ⇒ string

Renders Markdown for a provided string with a provided MarkdownIt configuration.

**Kind**: static method of [MarkdownItRenderer](#MarkdownItRenderer)  

**Returns**: string - The rendered content.  

| Param | Type | Description |

| --- | --- | --- |

| content | string | Markdown content to be converted to HTML. |

| [config] | [MarkdownItRendererOptions](#MarkdownItRendererOptions) | A provided MarkdownIt configuration to use. |

**Example** *(MarkdownItRenderer.render(content, config))*  

```js

const html = MarkdownItRenderer.render(content, config);

```



### MarkdownItRenderer.parse(content, [config]) ⇒ Array.<module:markdown-it/lib/token>

Parse Markdown for a provided string with a provided MarkdownIt configuration.

**Kind**: static method of [MarkdownItRenderer](#MarkdownItRenderer)  

**Returns**: Array.<module:markdown-it/lib/token> - The rendered content.  

**See**: [MarkdownIt.parse](https://markdown-it.github.io/markdown-it/#MarkdownIt.parse)  

| Param | Type | Description |

| --- | --- | --- |

| content | string | Markdown content to be converted to HTML. |

| [config] | [MarkdownItRendererOptions](#MarkdownItRendererOptions) | A provided MarkdownIt configuration to use. |

**Example** *(MarkdownItRenderer.parse(content, config))*  

```js

const tokens = MarkdownItRenderer.parse(content, config);

```



### MarkdownItRenderer.cleanContent(content) ⇒ string

Removes empty links, as these have caused issues.

Find missing links, and link them to the slug from the provided text.

**Kind**: static method of [MarkdownItRenderer](#MarkdownItRenderer)  

**Returns**: string - The rendered content.  

| Param | Type | Description |

| --- | --- | --- |

| content | string | Markdown content to be converted to HTML. |



### MarkdownItRenderer.viewModelDetail(viewModel, context) ⇒ object

Will attempt to extract the table of contents when set to and add it to the view model.

**Kind**: static method of [MarkdownItRenderer](#MarkdownItRenderer)  

**Returns**: object - The view model.  

| Param | Type | Description |

| --- | --- | --- |

| viewModel | object | Markdown content to be converted to HTML. |

| context | object | A Uttori-like context. |

| context.config | [MarkdownItRendererOptions](#MarkdownItRendererOptions) | A provided configuration to use. |

**Example** *(MarkdownItRenderer.viewModelDetail(viewModel, context))*  

```js

viewModel = MarkdownItRenderer.viewModelDetail(viewModel, context);

```



## MarkdownItRendererOptions : object

**Kind**: global typedef  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| baseUrl | string | Prefix for relative URLs, useful when the Express app is not at URI root. |

| allowedExternalDomains | Array.<string> | Allowed External Domains, if a domain is not in this list, it is set to 'nofollow'. Values should be strings of the hostname portion of the URL object (like example.org). |

| disableValidation | boolean | Optionally disable the built in Markdown-It link validation, large security risks when link validation is disabled. |

| openNewWindow | boolean | Open external domains in a new window. |

| lazyImages | boolean | Add lazy loading params to image tags. |

| footnotes | object | Footnote settings. |

| footnotes.referenceTag | function | A funciton to return the default HTML for a footnote reference. |

| footnotes.definitionOpenTag | function | A funciton to return the default opening HTML for a footnote definition. |

| footnotes.definitionCloseTag | string | The default closing HTML for a footnote definition. |

| toc | object | Table of Contents settings. |

| toc.extract | boolean | When true, extract the table of contents to the view model from the content. |

| toc.openingTag | string | The opening DOM tag for the TOC container. |

| toc.closingTag | string | The closing DOM tag for the TOC container. |

| toc.slugify | object | Slugify options for convering headings to anchor links. |

| wikilinks | object | WikiLinks settings. |

| wikilinks.slugify | object | Slugify options for convering Wikilinks to anchor links. |

* * *

## 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)
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/uttori/uttori-plugin-renderer-markdown-it

Awesome Lists containing this project

README
