markdown-it-attribution

A plugin for 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.

Requires markdown-it v10.+

The plugin allows to provide an attribution for a quotation:

> 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:

<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 for more details.

Install

node:

npm install --save markdown-it markdown-it-attribution

Usage

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:

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:

// 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