Wondering what’s next for npm?Check out our public roadmap! »

    markdown-it-attribution

    0.1.4 • Public • Published

    markdown-it-attribution

    NPM version Build Status Coverage Status

    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 v5.+

    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

    Install

    npm i markdown-it-attribution

    DownloadsWeekly Downloads

    22

    Version

    0.1.4

    License

    MIT

    Unpacked Size

    79.2 kB

    Total Files

    10

    Last publish

    Collaborators

    • avatar