hedgedoc/markdown-it-plugins

Markdown-It plugins

This repository contains plugins for Markdown-It that are used by HedgeDoc. All these plugins are (re)created in typescript.

License

Everything is licensed under MIT

Usage

Install the lib using yarn install @hedgedoc/markdown-it-plugins or npm i @hedgedoc/markdown-it-plugins

Development

If you want to contribute to this lib then:

• Clone this repository
• Install the dependencies using yarn install. Don't use npm!
• Make your changes
• Make sure that your changes are covered by tests. Use yarn test to run all tests
• Make sure that your code follows the code style. Use yarn lint to check the style
• Commit your changes (please use conventional commits) and create a pull request

markdown-it-image-size

A markdown-it plugin for size-specified image markups. This plugin overloads the original image renderer of markdown-it.

This is a typescript port of https://github.com/tatsy/markdown-it-imsize without the local file system support.

Usage

Enable plugin

import MarkdownIt from 'markdown-it'
import { imageSize } from '@hedgedoc/markdown-it-plugins'

const md = new MarkdownIt({
    html: true,
    linkify: true,
    typography: true
}).use(imageSize);

Example

![test](image.png =100x200)

is interpreted as

<p><img src="image.png" alt="test" width="100" height="200"></p>

markdown-it-better-task-lists

A markdown-it plugin that renders GitHub-style task-lists. It builds task/todo lists out of Markdown lists with items starting with [ ] or [x].

This is a typescript port of markdown-it-task-lists.

Why is this useful?

When you have markdown documentation with checklists, rendering HTML checkboxes out of the list items looks nicer than the raw square brackets.

Usage

Use it the same as a normal markdown-it plugin:

import MarkdownIt from 'markdown-it'
import { taskLists } from '@hedgedoc/markdown-it-plugins'

const parser = new MarkdownIt().use(taskLists)

const result = parser.render(`
- [ ] Open task
- [x] Done task
- Not a task
`) // markdown string containing task list items

The rendered checkboxes are disabled; to change this, set enabled property of the plugin options to true:

const parser = new MarkdownIt().use(taskLists, { enabled: true })

If you need to know which line in the markdown document the generated checkbox comes set the lineNumber property of the plugin options to true for the <input> tag to be created with a data-line attribute containing the line number:

const parser = new MarkdownIt().use(taskLists, { lineNumber: true })

If you'd like to wrap the rendered list items in a <label> element for UX purposes, set the label property of the plugin options to true:

const parser = new MarkdownIt().use(taskLists, { label: true })

To add the label after the checkbox set the labelAfter property of the plugin options to true:

const parser = new MarkdownIt().use(taskLists, { label: true, labelAfter: true })

Note: This option does require the label option to be truthy.

The options can be combined, of course.

markdown-it-toc

A markdown-it plugin that renders a table of contents. It uses the found headlines as content.

This is a typescript port of markdown-it-toc-done-right.

Usage

Use it the same as a normal markdown-it plugin:

import MarkdownIt from 'markdown-it'
import { toc } from '@hedgedoc/markdown-it-plugins'

const parser = new MarkdownIt().use(toc)

const result = parser.render(`
[toc]

# head 1

# head 2
`) // markdown string containing task list items