markdown-it-citation v0.1.1

markdown-it-citation

A plugin for markdown-it that generates accessible markup for quotes with citation lines. The generated output follows the suggestions in the living standard of the WHATWG.

Requires markdown-it v5.+

The plugin allows you to provide a citation line with your quote:

> 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 but allows you to style your citations however you like:

<figure class="quote">
  <blockquote>
    <p>
      That's one small step for [a] man, one giant leap for mankind.  
    </p>
  </blockquote>
  <figcaption>
    Neil Armstrong (1969, July 21)
  </figcaption>
</figure>

By default an em dash is used as the marker for a citation 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 quote. You can customize the characters used as a citation marker. Have a at the available plugin options for more details.

Install

node:

npm install --save markdown-it markdown-it-citation

Usage

var md = require('markdown-it')()
  .use(require('markdown-it-citation'));

var quote = [
  '> That\'s one small step for [a] man, one giant leap for mankind.',
  '> — Neil Armstrong (1969, July 21)'
];

md.render(quote.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-citation'), {
    className: 'c-quote',
    marker: '--',
    removeMarker: false,
  });

md.render('…');

List of available options:

• [className='quote'] - Select the HTML class added to the container of the blockquote.
• [marker='—'] - Select the characters used to identify the beginning of a citation line.
• [removeMarker=true] - Determines whether the citation 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 caption you can provide your own template functions.

// Setup the markdown it parser.
var md = require('markdown-it')()
  .use(require('markdown-it-citation'));

/**
 * 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 function for the citation tokens.
md.renderer.rules.blockquote_container_open = tag('aside', true);
md.renderer.rules.blockquote_citation_open = tag('div', true);
md.renderer.rules.blockquote_citation_close = tag('div', false);
md.renderer.rules.blockquote_container_close = tag('aside', false);

Motivation

I wanted to add a citation line to the generated markup of some of my 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.

License

MIT