Showdowns

Showdowns is a lib that make markdown to html with some extensions features(include more diagrams extensions) of showdown.js.

In browser environment, it is implemented to dynamically load js lib files related to more showdown diagrams extension for using showdowns >= 0.3.0 version.

If you think the showdowns library can help you or also hope to encourage the author, click on the top right corner to give me a Star⭐️.

Markdown To Html

Showdowns can converte markdown content to html that using the showdown.js.

Showdown is a Javascript Markdown to HTML converter, based on the original works by John Gruber. Showdown can be used client side (in the browser) or server side (with NodeJs). For more information, refer to the following document:

Showdowns Features Syntax
Showdown's Markdown Syntax
Showdown Options

Live Demo Editor —— `showdowns-editor`

Check a live demo editor here https://jhuix.github.io/vue-showdowns-editor

Table Extension

The following features are extended based on the showdown's table:
- Cell spans over columns
- Cell spans over rows (optional)
- Omitted table header (optional)
Showdown's table

cell style syntax has "-{2,}",":-{2,}",":-{2,}:","-{2,}:", means default (align left), align left, align center, and align right style

| Return Code | Style | Value | DESC      |
| ----------- | :-----: | :----- | ---------: |
| OK          | int   | 1     | Succeeded |
| ERROR       | int   | 0     | Failed '\|'    |

Return Code	Style	Value	DESC
OK	int	1	Succeeded
ERROR	int	0	Failed

Colspan table

"||" indicates cells being merged left.

| Return Code | Style | Value | DESC      |
| ====== | :-----: | ===== | ===== |
| **OK**          | int   | 1     | [Succeeded](https://www.baidu.com) |
| ERROR       | int   | 0     ||
| ERROR       || 0     ||

Return Code	Style	Value	DESC
OK	int	1	Succeeded
ERROR	int	0
ERROR		0

Rowspan table (optional: tablesRowspan)

"^^" indicates cells being merged above.

| Return Code | Style | Value | DESC      |
| ====== | :-----: | ===== | ===== |
| ^^         || 1     | [Succeeded](https://www.baidu.com) |
| ^^       || 0     ||
| ERROR       | int   | 0     ||
| ERROR       || 0     ||
| ^^       || 0     ||

Return Code	Style	Value	DESC
^^		1	Succeeded
^^		0
ERROR	int	0
ERROR		0
ERROR		0

Headerless table (optional: tablesHeaderless)

Table header can be eliminated.

|--|--|--|--|--|--|--|--|
|♜|  |♝|♛|♚|♝|♞|♜|
|  |♟|♟|♟|  |♟|♟|♟|
|♟|  |♞|  |  |  |  |  |
|  |♗|  |  |♟|  |  |  |
|  |  |  |  |♙|  |  |  |
|  |  |  |  |  |♘|  |  |
|♙|♙|♙|♙|  |♙|♙|♙|
|♖|♘|♗|♕|♔|  |  |♖|

♜		♝	♛	♚	♝	♞	♜
	♟	♟	♟		♟	♟	♟
♟		♞
	♗			♟
				♙
					♘
♙	♙	♙	♙		♙	♙	♙
♖	♘	♗	♕	♔			♖

Supporting some markdown extension features

Footnotes

Container

Table of Contents

LaTeX math and AsciiMath

See more information, refer to the following document:

Extensions Examples

Preview

View Extensions Examples is previewed as Showdowns Features
View video

Usage

Installation

Using npm:
```
npm install @jhuix/showdowns
```
Note: add --save if you are using npm < 5.0.0

In a browser:

put the following line into your HTML page <header> or <body>:

<link rel="stylesheet" href="dist/showdowns.min.css">
<script src="dist/showdowns.min.js"></script>

In Node.js:

For commonjs

var showdowns = require('showdowns');

or

import 'showdowns/dist/showdowns.core.min.css';
import showdowns from 'showdowns';

For umd

var showdowns = require('showdowns/dist/showdowns.min.js');

or

import 'showdowns/dist/showdowns.min.css';
import showdowns from 'showdowns/dist/showdowns.min.js';

Support compress markdown content with zip.

Quick Example

Node

var showdowns = require('showdowns'),
showdowns.init()
var text = '# hello, markdown!',
showdowns.makeHtml(text).then(obj => {
  //Do something for 'obj.html' and 'obj.scripts'      
});

Browser

Put the following line into your HTML page <header> or <body>:

<link rel="stylesheet" href="../dist/showdowns.min.css" />

<div id="main" class="workspace-container"></div>
<script src="../dist/showdowns.min.js"></script>
<script>
  (function(element) {
    showdowns.init();
    let md = "";
    window
      .fetch("https://jhuix.github.io/showdowns/showdowns-features.md")
      .then(function(response) {
        if (response.ok) {
          return response.text();
        }
      })
      .then(function(text) {
        md = text;
        return window.fetch(
          "https://jhuix.github.io/showdowns/Showdown's-Markdown-syntax.md"
        );
      })
      .then(function(response) {
        if (response.ok) {
          return response.text();
        }
      })
      .then(function(text) {
        md = md + `\n\n## Showdown's Markdown syntax\n\n` + text;
        showdowns.makeHtml(md).then(obj => {
          element.innerHTML = obj.html;
          showdowns.completedHtml(obj.scripts, '.showdowns');
        }).catch(err =>{
          element.innerHTML = '';
          console.log(err);
        });
      })
      .catch(function(error) {
        console.log(error);
        if (md) {
          showdowns.makeHtml(md).then(obj => {
            element.innerHTML = obj.html;
            showdowns.completedHtml(obj.scripts, '.showdowns');
          }).catch(err =>{
            element.innerHTML = '';
            console.log(err);
          });
        }
      });
  })(document.getElementById("main"));
</script>

Options

defaultOptions

Type: {showdown: object, plantuml: object, mermaid: object, vega: object }

Default options is described below:

defaultOptions = {
  showdown: {
    flavor: 'github',
  },
  plantuml: { imageFormat: 'svg' },
  mermaid: { theme: 'default' },
  katex: { mathDelimiters: [
    { left: '$$', right: '$$', display: true },
    { left: '\\[', right: '\\]', display: true },
    { left: "\\begin{equation}", right: "\\end{equation}", display: true },
    { left: "\\begin{align}", right: "\\end{align}", display: true },
    { left: "\\begin{alignat}", right: "\\end{alignat}", display: true },
    { left: "\\begin{gather}", right: "\\end{gather}", display: true },
    { left: "\\begin{CD}", right: "\\end{CD}", display: true },      
    { left: '\\(', right: '\\)', display: false },
    { left: '@@', right: '@@', display: true, asciimath: true },
    { left: "\\$", right: "\\$", display: false, asciimath: true }
  ]},
  vega: { theme: 'vox' }
};

showdown: showdown options object

For more showdown options, refer to the following document:

Showdown Options

plantuml: plantuml options object

For more plantuml options:

{
  umlWebSite: "www.plantuml.com/plantuml",
  imageFormat: "svg" | "png" | "jpg"
}

mermaid: mermaid options object

For more mermaid options, refer to the following document:

Mermaid Options

katex: katex options object

For more katex options, refer to the following document:

Katex AutoRender Options Katex Render Options

In addition, mathDelimiters is another format::

{
  mathDelimiters: {
    texmath: {
      display: [
         {left: "$$", right: "$$"},
         {left: '\\[', right: '\\]'}
      ],
      inline:  [
        {left: '\\(', right: '\\)'}
      ]
    },
    asciimath: {
      display: [ {left: "@@", right: "@@"}],
      inline:  [ {left: "\\$ ", right: "\\$"}]
    }
  }
}

vega: vega-embed options object

For more vega-embed options, refer to the following document:

Vega-embed Options

defaultExtensions

Type: Array of showdown extensions

Default extensions is described below:

defaultExtensions = {
  'showdown-toc': showdownToc,
  'showdown-align': showdownAlign,
  'showdown-footnotes': showdownFootnotes,
  'showdown-container': showdownContainer,
  'showdown-sequence': showdownSequence
}

For more showdown extensions, refer to the following document:

Showdown Extensions

defaultAsyncExtensions

Type: Array of showdown async extensions

Default async extensions is described below:

defaultAsyncExtensions = {
  'showdown-plantuml': showdownPlantuml(plantumlOptions),
  'showdown-mermaid': showdownMermaid(mermaidOptions),
  'showdown-katex': showdownKatex(katexOptions),
  'showdown-flowchart': showdownFlowchart,
  'showdown-viz': showdownViz,
  'showdown-vega': showdownVega(vegaOptions),
  'showdown-wavedrom': showdownWavedrom,
  'showdown-railroad': showdownRailroad,
  'showdown-abc': showdownAbc,
  'showdown-echarts': showdownEcharts,
}

Properties

showdown

Type: showdown

Default: showdown

Output showdown.js native object for global.

convertor

Type: showdown.convertor | null

Default: null

Output showdown.convertor native object in current showdowns Instance.

Methods

setFlavor

Type: {name: string} => void

A function to add or update flavor of showdown and showdown.convertor.

addOptions

Type: {options: object} => void

A function to add or update options of showdown and showdown.convertor.

addExtension

Type: [name, extension] => void

A function to add or update extension of showdown and showdown.convertor.

removeExtension

Type: [name] => void

A function to remove extension of showdown and showdown.convertor.

addAyncExtension

Type: [name, extension] => void

A function to add or update aync extension of showdowns.

removeAyncExtension

Type: [name] => void

A function to remove aync extension of showdowns.

setCDN

Type: (cdnname: string, defSheme: string, distScheme: string) => void

A function to set cdn source when dynamically load js lib files related to more showdown diagrams extension.

Parameter cdnname can be selected 'local' or 'cdnjs' or 'jsdelivr' source.
Parameter defSheme is default prefix scheme string of source url.
Parameter distScheme is dist prefix scheme string of source url that has prefix string is '../dist/'.

setShowdownFlavor

Type: (name: string) => void

A function to set default flavor of showdown. When showdown.convertor instance be created, it can update flavor of the showdown and convertor.convertor.

See showdown options of defaultOptions.

flavor field value: ['github', 'ghost', 'vanilla', 'original', 'allon'], default set to 'github' flavor.