markdown-it-special-paragraphs

About

This plugin is work in progress! Currently, it is mostly a clone of another plugin, although the documentation may indicate more functionality already.

This plugin to the Javascript Commonmark parser markdown-it is based upon markdown-it-implicit-figures (npm) and markdown-it-html5-media. It made sense to incorporate them in a single plugin for this instead of having users chain them themselves.

Render links and embedded images, videos or audios occurring by itself in a paragraph as figures with caption. Expanded link previews use Twitter Card and Facebook Open Graph meta data if available. HTML5 element types figure and figcaption Images show are wrapped <figure><img ...></figure>, similar to pandoc's implicit figures.

To do

We have not decided yet which scraper for link metadata to use (by default):

• embedza
• Open Graph scraper
• grabity
• metascraper
• metaphor
• unfurled
• html-metadata

Example

Example input

text with ![image](img.png), ![video](vid.mp4), ![audio](aud.mp3) and [link](page.html),
[image link](img.png), [video link](vid.mp4), [audio link](aud.mp3). 

![figure](fig.png)

![video](vid.mp4)

![audio](aud.mp3)

[link](page.html)

[![preview](fig.png)](page.html)

[![video](vid.mp4)](page.html)

[![audio](aud.mp3)](page.html)

Reference and shortcut links work as well, of course, and generate the same result.

text with ![image], ![video], ![audio] and [link],
[image link][image], [video link][video], [audio link][audio]. 

![figure][image]

![video][]

![audio]

[link]

[![preview][image]][link]

[![video][]][link]

[![audio]][link]

  [image]: img.png
  [video]: vid.mp4
  [audio]: aud.mp3
  [link]: page.html

Example output

<p>text with <img src="img.png" alt="image">, <img src="vid.mp4" alt="video">, <img src="aud.mp3" alt="audio"> and <a href="page.html">link</a>,
<a href="img.png">image link</a>, <a href="vid.mp4">video link</a>, <a href="aud.mp3">audio link</a>.</p>
<figure><img src="fig.png" alt="figure"></figure>
<figure><video src="vid.mp4">video</video></figure>
<figure><audio src="aud.mp3">audio</audio></figure>
<figure><a href="page.html">...link...</a></figure>
<figure><a href="page.html"><img src="fig.png" alt="preview"></a></figure>
<figure><a href="page.html"><video src="vid.mp4">video</video></a></figure>
<figure><a href="page.html"><audio src="aud.mp3">audio</audio></a></figure>

Install

$ npm install --save markdown-it-special-paragraphs

Usage

var md = require('markdown-it')();
var implicitFigures = require('markdown-it-special-paragraphs');

md.use(implicitFigures, {
  dataType: false,  // <figure data-type="image">, default: false
  figcaption: false,  // <figcaption>alternative text</figcaption>, default: false -- will change to true
  tabindex: false, // <figure tabindex="1+n">..., default: false -- deprecated
  link: false // <a href="img.png"><img src="img.png"></a>, default: false
});

var src = `text with ![](img.png)

![](fig.png)

another paragraph`;
var res = md.render(src);

console.log(res);

Demo at JS Fiddle

Options

• dataType: Set dataType to true to declare the data-type being wrapped, e.g.: <figure data-type="image">. This can be useful for applying special styling for different kind of figures.

• figcaption: Set figcaption to true to put the alternative text in a <figcaption>-block after the image. E.g.: ![caption](img.png) renders to

  <figure>
    <img src="img.png" alt="caption">
    <figcaption>caption</figcaption>
  </figure>

• tabindex: Set tabindex to true to add a tabindex property to each figure, beginning at tabindex="1" and incrementing for each figure encountered. Could be used with this css-trick, which expands figures upon mouse-over. (Deprecated)

• link: Put a link around the image if there is none yet.

• copyAttrs: Copy attributes matching (RegExp or string) copyAttrs to figure element. (Deprecated)

License

MIT © Arve Seljebu, Erik Moeller, Christoph Päper

The parts from the HTML5 Media plugin are actually licensed under Creative Commons 0 (CC0), which are both as close to Public Domain (PD) as possible.