npm package: @gerhobbelt/markdown-it-attribution
Description: Add attribution to your quotations.
Author: Daniel Weidner
Latest version: 0.1.4-3

# markdown-it-attribution

[![NPM version](https://img.shields.io/npm/v/markdown-it-attribution.svg?style=flat)](https://www.npmjs.org/package/markdown-it-attribution)
[![Build Status](https://img.shields.io/travis/dweidner/markdown-it-attribution/master.svg?style=flat)](https://travis-ci.org/dweidner/markdown-it-attribution)
[![Coverage Status](https://coveralls.io/repos/github/dweidner/markdown-it-attribution/badge.svg?branch=master)](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` v10.+**

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/GerHobbelt/markdown-it-attribution/blob/master/LICENSE.txt)