# markdown-it-citation

> Add citation lines to your quotes.

Latest version **0.1.1** (published 2019-03-29) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install markdown-it-citation
pnpm add markdown-it-citation
yarn add markdown-it-citation
bun add markdown-it-citation
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2019-03-29 |
| First published | 2019-03-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 73.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Daniel Weidner |
| Maintainers | dweidner |
| Keywords | markdown, markdown-it, markdown-it-plugin, blockquote, citation, cite |

## Links

- npm: https://www.npmjs.com/package/markdown-it-citation
- Repository: https://github.com/dweidner/markdown-it-citation
- Homepage: https://github.com/dweidner/markdown-it-citation#readme
- Issues: https://github.com/dweidner/markdown-it-citation/issues
- npm.io page: https://npm.io/package/markdown-it-citation

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 0.1.1 (latest) — 2019-03-29
- 0.1.0 — 2019-03-28

## README

# markdown-it-citation

[![NPM version](https://img.shields.io/npm/v/markdown-it-citation.svg?style=flat)](https://www.npmjs.org/package/markdown-it-citation)
[![Build Status](https://img.shields.io/travis/dweidner/markdown-it-citation/master.svg?style=flat)](https://travis-ci.org/dweidner/markdown-it-citation)
[![Coverage Status](https://coveralls.io/repos/github/dweidner/markdown-it-citation/badge.svg?branch=master)](https://coveralls.io/github/dweidner/markdown-it-citation?branch=master)

> A plugin for [markdown-it](https://github.com/markdown-it/markdown-it) that
> generates accessible markup for quotes with citation lines. 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 you to provide a citation line with your quote:

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

```html
<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](#options) for more details.

## Install

node:

```bash
npm install --save markdown-it markdown-it-citation
```

## Usage

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

```js
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.

```js
// 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](https://github.com/dweidner/markdown-it-citation/blob/master/LICENSE.txt)

---
_Source: https://npm.io/package/markdown-it-citation · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._