markdown-it-attribution
Version:
Add attribution to your quotations.
120 lines (89 loc) • 4.53 kB
Markdown
# markdown-it-attribution
[](https://www.npmjs.org/package/markdown-it-attribution)
[](https://travis-ci.org/dweidner/markdown-it-attribution)
[](https://coveralls.io/github/dweidner/markdown-it-attribution?branch=master)
> A plugin for [markdown-it](https://github.com/markdown-it/markdown-it) that
> generates accessible markup for block quotes with attribution line. The
> generated output follows the suggestions in the living standard of the
> [WHATWG](https://html.spec.whatwg.org/multipage/grouping-content.html#the-blockquote-element).
**Requires `markdown-it` v5.+**
The plugin allows to provide an attribution for a quotation:
```md
> That's one small step for [a] man, one giant leap for mankind.
> — Neil Armstrong (1969, July 21)
```
The generated markup is not only accessible for screen readers but allows you to style the attribution line however you like:
```html
<figure class="c-blockquote">
<blockquote>
<p>
That's one small step for [a] man, one giant leap for mankind.
</p>
</blockquote>
<figcaption class="c-blockquote__attribution">
Neil Armstrong (1969, July 21)
</figcaption>
</figure>
```
By default an `em dash` is used as the marker for an attribution line. Note that the `em dash` has to follow a soft break or has to be *the first character* of a new paragraph. This restriction should avoid situation in which an `em dash` is used within the body of a quotation. You can customize the characters used as an attribution marker. Have a look at the available [plugin options](#options) for more details.
## Install
node:
```bash
npm install --save markdown-it markdown-it-attribution
```
## Usage
```js
var md = require('markdown-it')()
.use(require('markdown-it-attribution'));
var blockquote = [
'> That\'s one small step for [a] man, one giant leap for mankind.',
'> — Neil Armstrong (1969, July 21)'
];
md.render(blockquote.join('\n'));
```
### Options
You can customize the plugin behavior by providing custom options when you register the parser plugin:
```js
var md = require('markdown-it')()
.use(require('markdown-it-attribution'), {
classNameContainer: 'c-quote',
classNameAttribution: 'c-quote__attribution',
marker: '--',
removeMarker: false,
});
md.render('…');
```
List of available options:
- `[classNameContainer='c-blockquote']` - Select the HTML class added to the container of the `blockquote`.
- `[classNameAttribution='c-blockquote__attribution']` - Select the HTML class added to the container of an attribution line.
- `[marker='—']` - Select the characters used to identify the beginning of an attribution line.
- `[removeMarker=true]` - Determines whether the attribution marker will be included in the generated markup.
### Customization
Like always you can customize the output of all the elements generated by `markdown-it`. If you want to change the HTML element used for the container and the attribution you can provide your own template functions:
```js
// Setup the markdown it parser.
var md = require('markdown-it')()
.use(require('markdown-it-attribution'));
/**
* A utility function used to generate custom template functions which returns
* the markup for an HTML tag.
*
* @param {string} name The name of the HTML tag.
* @param {Boolean} open Whether an opening or closing tag should be generated.
* @return {Function}
*/
function tag (name, open) {
return function () {
return open ? '<' + name + '>' : '</' + name + '>';
}
}
// Overwrite the template functions for the various elements.
md.renderer.rules.blockquote_container_open = tag('aside', true);
md.renderer.rules.blockquote_attribution_open = tag('div', true);
md.renderer.rules.blockquote_attribution_close = tag('div', false);
md.renderer.rules.blockquote_container_close = tag('aside', false);
```
## Motivation
I wanted to add an attribution line to the generated markup of some of my block quotes (including the `cite` attribute) and searched for an unobtrusive way. The current solution still looks good in applications that do not support the custom syntax and provides accessible markup otherwise.
## License
[MIT](https://github.com/dweidner/markdown-it-attribution/blob/master/LICENSE.txt)