hedgedoc/markdown-it-plugins/README.md
Tilman Vatteroth f5736dad0f feat: import markdown-it-plugins from https://github.com/hedgedoc/markdown-it-plugins
Signed-off-by: Tilman Vatteroth <git@tilmanvatteroth.de>
2023-08-26 15:30:30 +02:00

143 lines
3.9 KiB
Markdown

<!--
SPDX-FileCopyrightText: 2020 The HedgeDoc developers (see AUTHORS file)
SPDX-License-Identifier: CC0-1.0
-->
# Markdown-It plugins
This repository contains plugins for [Markdown-It](https://github.com/markdown-it/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](https://www.conventionalcommits.org/en/v1.0.0/)) 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
```ts
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
```md
![test](image.png =100x200)
```
is interpreted as
```html
<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](https://github.com/blog/1825-task-lists-in-all-markdown-documents) out of Markdown lists with items starting with `[ ]` or `[x]`.
This is a typescript port of [markdown-it-task-lists](https://github.com/revin/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:
```ts
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`:
```ts
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:
```ts
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`:
```ts
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`:
```ts
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](https://github.com/nagaozen/markdown-it-toc-done-right).
### Usage
Use it the same as a normal markdown-it plugin:
```ts
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
```