Skip to content

Latest commit

 

History

History
923 lines (717 loc) · 21.5 KB

showdowns-features.md

File metadata and controls

923 lines (717 loc) · 21.5 KB
Raw

Showdowns

Showdowns Features

Showdowns is a lib that make markdown to html with some extensions of showdown.js. Click the link to preview the showdowns features.

Showdowns Markdown Syntax, refer to the document -- Showdown's Markdown Syntax.

  • 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.

  • In codeblock of markdown, expanded syntax language attribute from "```language" to "```language {json}" or "```language [json]".

    • The common "align" field value of json is "left" or "center" or "right" in syntax language attribute, and it is empty means "left" align.

    • The common "codeblock" field value of json is "true" or "false" in syntax language attribute, and it is empty means "false". It is "true" means the codeblock is forced to display as normal code block, otherwise the codeblock is tried to parse as corresponding diagrams.

    • For example, see following Network Sequence example.

Table

  • 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 || | ^^ || 0 ||

  • Headerless table (optional: tablesHeaderless)

Table header can be eliminated.

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

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

Markdown extension features

[TOC]

Table of Contents

It's implemented sub-TOC in showdown-toc.js.

Markdown Syntax

[TOC]

sub-TOC examples

[TOC]

sub-TOC examples1
sub examples1
sub-TOC examples2
sub examples2

Footnotes

It's implemented in showdown-footnotes.js, use for reference the showdown-footnotes.

Markdown Syntax

[^1]: The explanation.

Footnotes examples

[^1]: The explanation.

Container

It's implemented in showdown-container.js, allows you to create block level containers. By default, The CSS effect with class name tip|info|warning|error|success|alert-tip|alert-info|alert-warning|alert-error|alert-success is implemented. And you can also customize the class name.

Markdown Syntax

::: <classname | parentclass-childclass> <title content>
*Some text*
:::

Which will be rendered as:

<div class="showdown-container [container classname | parentclass parentclass-childclass]">
  <p class="container-title">title content</p>
  <p>
    <em>Some text</em>
  </p>
</div>

Container examples

::: tip A simple tip text! :::

::: tip Tip! A simple tip text! :::

::: info Info! A simple info text! :::

::: warning Warning! A simple warning text! :::

::: error Error! A simple error text! :::

::: success Success! A simple success text! :::

::: alert-tip A simple tip alert text! :::

::: alert-tip Alert Tip! A simple tip alert text! :::

::: alert-info Alert Info! A simple info alert text! :::

::: alert-warning Alert Warning! A simple warning alert text! :::

::: alert-error Alert Error! A simple error alert text! :::

::: alert-success Alert Success! A simple success alert text! :::

::: alert-success-tip Alert Success Tip!

<style>.alert-success-tip:after {content: '\00a0';width: 0;height: 0;display: block;border-style: solid;border-width: 15px;border-color: #f3961c transparent transparent transparent;position: absolute;z-index: -1;bottom: -30px;left: 50px;}</style>

A simple success alert text! :::

LaTeX math and AsciiMath

It's supported by showdown-katex, that render LaTeX math and AsciiMath using KaTeX, You can check KaTeX supported functions/symbols.

Markdown Syntax

  • AsciiMath syntax:

    • Block multiple math

      Multiple math are separated by an empty line.

      
    ```asciimath {"align": "left | center | right", "codeblock": true | false}
    <code content>
    ```

    • Inline math

      • @@...@@ is delimiters of inline ascii math
      • \\~...\\~ is delimiters of inline block ascii math

  • LaTex syntax:

    • Block multiple latex

      Multiple math are separated by an empty line.

          ```latex {"align": "left | center | right", "codeblock": true | false}
    <code content>
    ```

    • Inline latex

      • \\(...\\) is delimiters of inline latex math
      • \\[...\\] is delimiters of inline block latex math
      • $$...$$ is delimiters of inline block latex math

LaTex examples

x=\frac{ -b\pm\sqrt{ b^2-4ac } } {2a}

x=\frac{ -b\pm\sqrt{ b^2-4ac } } {2a}



x=\frac{ -b\pm\sqrt{ b^2-4ac } } {2a}
x=\frac{ -b\pm\sqrt{ b^2-4ac } } {2a}

where:

  • \(\sqrt{ b^2-4ac }\) is inline latex math
  • \[\sqrt{ b^2-4ac }\] is inline latex block math
  • $$\sqrt{ b^2-4ac }$$ is inline latex block math

AsciiMath examples

Internal heat energy:

delta Q = rho \ c \u

delta Q = rho \ c \u
      
delta Q = rho \ c \u



delta Q = rho \ c \u

where:

  • @@delta Q@@ is the internal heat energy per unit volume \$(J * m^-3)\$

Mermaid

It's implemented in showdown-mermaid.js, render diagrams of Flowchart or Sequence or Gantt using mermaid, check mermaid doc for more information.

Markdown Syntax

  • Flowchart syntax:

      ```mermaid {"align": "left | center | right", "codeblock": true | false}
  graph TD;
  <code content>
  ```

  • Sequence diagram syntax:

      ```mermaid {"align": "left | center | right", "codeblock": true | false}
  sequenceDiagram
  <code content>
  ```

  • Gantt diagram syntax:

      ```mermaid {"align": "left | center | right", "codeblock": true | false}
  gantt
  <code content>
  ```

Mermaid examples

Flowchart
graph TD;
           A-->B;
           A-->C;
           B-->D;
           C-->D;
Loading 
graph TD;
           A-->B
           A-->C
           B-->D
           C-->D
Loading
Sequence diagram
sequenceDiagram
           participant Alice
           participant Bob
           Alice->>John: Hello John, how are you?
           loop Healthcheck
               John->>John: Fight against hypochondria
           end
           Note right of John: Rational thoughts <br/>prevail!
           John-->>Alice: Great!
           John->>Bob: How about you?
           Bob-->>John: Jolly good!
Loading
Gantt diagram
       gantt
       dateFormat  YYYY-MM-DD
       title Adding GANTT diagram to mermaid
       excludes weekdays 2014-01-10

       section A section
       Completed task            :done,    des1, 2014-01-06,2014-01-08
       Active task               :active,  des2, 2014-01-09, 3d
       Future task               :         des3, after des2, 5d
       Future task2               :         des4, after des3, 5d
Loading

Plantuml

It's implemented in showdown-plantuml.js. render diagrams of uml using plantuml. To know more about PlantUML, please visit plantuml website.

Markdown Syntax

```plantuml {"align": "left | center | right", "codeblock": true | false}
@startuml
<code content>
@enduml
```

Plantuml example

      @startuml
      participant User

      User -> A: DoWork
      activate A

      A -> B: << createRequest >>
      activate B

      B -> C: DoWork
      activate C
      C --> B: WorkDone
      destroy C

      B --> A: RequestCreated
      deactivate B

      A -> User: Done
      deactivate A

      @enduml

Flowchart

It's implemented in showdown-flowchart.js, render diagrams of flowchart using flowchart.js, check flowchart website for more information.

Markdown Syntax

```flow {"align": "left | center | right", "codeblock": true | false}
<code content>
```

OR

```flowchart {"align": "left | center | right", "codeblock": true | false}
<code content>
```

Flowchart example

st=>start: Start:>http://www.google.com[blank]
e=>end:>http://www.google.com
op1=>operation: My Operation
sub1=>subroutine: My Subroutine
cond=>condition: Yes
or No?:>http://www.google.com
io=>inputoutput: catch something...
para=>parallel: parallel tasks

st->op1->cond
cond(yes)->io->e
cond(no)->para
para(path1, bottom)->sub1(right)->op1
para(path2, top)->op1

st=>start: Start
e=>end
op1=>operation: My Operation
sub1=>subroutine: My Subroutine
cond=>condition: Yes
or No?:>http://www.google.com
io=>inputoutput: catch something
st->op1->cond
cond(yes)->io->e
cond(no)->sub1(right)->op1

Graphviz's dot

It's implemented in showdown-viz.js, render diagrams of graphviz's dot using viz.js.

Markdown Syntax

The <engine name> of json's "engine" field value is 'circo', 'dot', 'neato', 'osage', 'twopi' in syntax language attribute.

```dot {"engine": "<engine name>", "align": "<align>"}
<code content>
```

Graphviz's dot example

  • Dot example with dot engine:
digraph G {
    main -> parse -> execute;
    main -> init;
    main -> cleanup;
    execute -> make_string;
    execute -> printf
    init -> make_string;
    main -> printf;
    execute -> compare;
}

  • Dot example with circo engine:
digraph G {
    main -> parse -> execute;
    main -> init;
    main -> cleanup;
    execute -> make_string;
    execute -> printf
    init -> make_string;
    main -> printf;
    execute -> compare;
}

Railroad diagrams

It's implemented in showdown-viz.js, render diagrams of railroad using railroad-diagrams.

Markdown Syntax

```railroad {"align": "left | center | right", "codeblock": true | false}
<code content>
```

Railroad diagrams example

Diagram(
  Optional('+', 'skip'),
    Choice(0,
      NonTerminal('name-start char'),
      NonTerminal('escape')),
      ZeroOrMore(
        Choice(0,
          NonTerminal('name char'),
          NonTerminal('escape'))))

WaveDrom

It's implemented in showdown-viz.js, render diagrams of wavedrom using wavedrom, check wavedrom website for more information.

Markdown Syntax

```wavedrom {"align": "left | center | right", "codeblock": true | false}
<code content>
```

WaveDrom example

{signal: [
  {name: 'clk', wave: 'p.....|...'},
  {name: 'dat', wave: 'x.345x|=.x', data: ['head', 'body', 'tail', 'data']},
  {name: 'req', wave: '0.1..0|1.0'},
  {},
  {name: 'ack', wave: '1.....|01.'}
]}

{ signal: [
  { name: "pclk", wave: 'p.......' },
  { name: "Pclk", wave: 'P.......' },
  { name: "nclk", wave: 'n.......' },
  { name: "Nclk", wave: 'N.......' },
  {},
  { name: 'clk0', wave: 'phnlPHNL' },
  { name: 'clk1', wave: 'xhlhLHl.' },
  { name: 'clk2', wave: 'hpHplnLn' },
  { name: 'clk3', wave: 'nhNhplPl' },
  { name: 'clk4', wave: 'xlh.L.Hx' },
]}

Echarts

Markdown Syntax

```echarts {"align": "left | center | right", "codeblock": true | false, "width":400, "height":300, "type": "javascript" | "json"}
<code content>
```

Echarts example

{
  "title": { "text": "最近 30 天" },
  "tooltip": { "trigger": "axis", "axisPointer": { "lineStyle": { "width": 0 } } },
  "legend": { "data": ["帖子", "用户", "回帖"] },
  "xAxis": [{
      "type": "category",
      "boundaryGap": false,
      "data": ["2019-05-08","2019-05-09","2019-05-10","2019-05-11","2019-05-12","2019-05-13","2019-05-14","2019-05-15","2019-05-16","2019-05-17","2019-05-18","2019-05-19","2019-05-20","2019-05-21","2019-05-22","2019-05-23","2019-05-24","2019-05-25","2019-05-26","2019-05-27","2019-05-28","2019-05-29","2019-05-30","2019-05-31","2019-06-01","2019-06-02","2019-06-03","2019-06-04","2019-06-05","2019-06-06","2019-06-07"],
      "axisTick": { "show": false },
      "axisLine": { "show": false }
  }],
  "yAxis": [{ "type": "value", "axisTick": { "show": false }, "axisLine": { "show": false }, "splitLine": { "lineStyle": { "color": "rgba(0, 0, 0, .38)", "type": "dashed" } } }],
  "series": [
    {
      "name": "帖子", "type": "line", "smooth": true, "itemStyle": { "color": "#d23f31" }, "areaStyle": { "normal": {} }, "z": 3,
      "data": ["18","14","22","9","7","18","10","12","13","16","6","9","15","15","12","15","8","14","9","10","29","22","14","22","9","10","15","9","9","15","0"]
    },
    {
      "name": "用户", "type": "line", "smooth": true, "itemStyle": { "color": "#f1e05a" }, "areaStyle": { "normal": {} }, "z": 2,
      "data": ["31","33","30","23","16","29","23","37","41","29","16","13","39","23","38","136","89","35","22","50","57","47","36","59","14","23","46","44","51","43","0"]
    },
    {
      "name": "回帖", "type": "line", "smooth": true, "itemStyle": { "color": "#4285f4" }, "areaStyle": { "normal": {} }, "z": 1,
      "data": ["35","42","73","15","43","58","55","35","46","87","36","15","44","76","130","73","50","20","21","54","48","73","60","89","26","27","70","63","55","37","0"]
    }
  ]
}

const data = [];
for (let i = 0; i <= 100; i++) {
  let theta = (i / 100) * 360;
  let r = 5 * (1 + Math.sin((theta / 180) * Math.PI));
  data.push([r, theta]);
}
const option = {
  title: {
    text: 'Two Value-Axes in Polar'
  },
  legend: {
    data: ['line']
  },
  polar: {},
  tooltip: {
    trigger: 'axis',
    axisPointer: {
      type: 'cross'
    }
  },
  angleAxis: {
    type: 'value',
    startAngle: 0
  },
  radiusAxis: {},
  series: [
    {
      coordinateSystem: 'polar',
      name: 'line',
      type: 'line',
      data: data
    }
  ]
};

Vega and Vega-Lite

It's implemented in showdown-vega.js, render diagrams of Vega and Vega-Lite using vega-embed, check vega website and vega-lite website for more information.

Markdown Syntax

```vega {"align": "left | center | right", "codeblock": true | false, "type": "javascript" | "json"}
<code content>
```

OR

```vega-lite {"align": "left | center | right", "codeblock": true | false, "type": "javascript" | "json"}
<code content>
```

Vega and Vega-Lite example

  • Vega example:
{
  "$schema": "https://vega.github.io/schema/vega/v5.json",
  "width": 200,
  "height": 200,
  "autosize": "none",

  "signals": [
    {
      "name": "startAngle", "value": 0,
      "bind": {"input": "range", "min": 0, "max": 6.29, "step": 0.01}
    },
    {
      "name": "endAngle", "value": 6.29,
      "bind": {"input": "range", "min": 0, "max": 6.29, "step": 0.01}
    },
    {
      "name": "padAngle", "value": 0,
      "bind": {"input": "range", "min": 0, "max": 0.1}
    },
    {
      "name": "innerRadius", "value": 0,
      "bind": {"input": "range", "min": 0, "max": 90, "step": 1}
    },
    {
      "name": "cornerRadius", "value": 0,
      "bind": {"input": "range", "min": 0, "max": 10, "step": 0.5}
    },
    {
      "name": "sort", "value": false,
      "bind": {"input": "checkbox"}
    }
  ],

  "data": [
    {
      "name": "table",
      "values": [
        {"id": 1, "field": 4},
        {"id": 2, "field": 6},
        {"id": 3, "field": 10},
        {"id": 4, "field": 3},
        {"id": 5, "field": 7},
        {"id": 6, "field": 8}
      ],
      "transform": [
        {
          "type": "pie",
          "field": "field",
          "startAngle": {"signal": "startAngle"},
          "endAngle": {"signal": "endAngle"},
          "sort": {"signal": "sort"}
        }
      ]
    }
  ],

  "scales": [
    {
      "name": "color",
      "type": "ordinal",
      "domain": {"data": "table", "field": "id"},
      "range": {"scheme": "category20"}
    }
  ],

  "marks": [
    {
      "type": "arc",
      "from": {"data": "table"},
      "encode": {
        "enter": {
          "fill": {"scale": "color", "field": "id"},
          "x": {"signal": "width / 2"},
          "y": {"signal": "height / 2"}
        },
        "update": {
          "startAngle": {"field": "startAngle"},
          "endAngle": {"field": "endAngle"},
          "padAngle": {"signal": "padAngle"},
          "innerRadius": {"signal": "innerRadius"},
          "outerRadius": {"signal": "width / 2"},
          "cornerRadius": {"signal": "cornerRadius"}
        }
      }
    }
  ]
}

  • Vega-Lite example:
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "description": "Plots two functions using a generated sequence.",
  "width": 300,
  "height": 150,
  "data": {
    "sequence": {
      "start": 0,
      "stop": 12.7,
      "step": 0.1,
      "as": "x"
    }
  },
  "transform": [
    {
      "calculate": "sin(datum.x)",
      "as": "sin(x)"
    },
    {
      "calculate": "cos(datum.x)",
      "as": "cos(x)"
    },
    {
      "fold": ["sin(x)", "cos(x)"]
    }
  ],
  "mark": "line",
  "encoding": {
    "x": {
      "type": "quantitative",
      "field": "x"
    },
    "y": {
      "field": "value",
      "type": "quantitative"
    },
    "color": {
      "field": "key",
      "type": "nominal",
      "title": null
    }
  }
}

Network Sequence

It's implemented in showdown-sequence.js, render diagrams of sequence using js-sequence-diagrams.

Markdown Syntax

The <theme name> of json's "theme" field value is "hand" or "simple" in syntax language attribute;

```sequence {"theme": "<theme name>", "align": "<align>"}
<code content>
```

Network Sequence example

  • Sequence example with hand theme:
Alice->Bob: Hello Bob, how are you?
Note right of Bob: Bob thinks
Bob-->Alice: I am good thanks!

  • Sequence example with simple theme:
Alice->Bob: Hello Bob, how are you?
Note right of Bob: Bob thinks
Bob-->Alice: I am good thanks!

ABC

Markdown Syntax

```abc {"align": "<align>"}
<code content>
```

ABC example

T: Cooley's
M: 4/4
Q: 1/4=120
L: 1/8
R: reel
K: Emin
|:{E}D2|EB{c}BA B2 EB|~B2 AB dBAG|FDAD BDAD|FDAD dAFD|
EBBA B2 EB|B2 AB defg|afe^c dBAF|DEFD E2:|
|:gf|eB B2 efge|eB B2 gedB|A2 FA DAFA|A2 FA defg|
eB B2 eBgB|eB B2 defg|afe^c dBAF|DEFD E2:|

X: 24
T: Clouds Thicken (云层变厚)
C: Paul Rosen
S: Copyright 2005, Paul Rosen
M: 6/8
L: 1/8
Q: 3/8=116
R: Creepy Jig
K: Em
|:"Em"EEE E2G|"C7"_B2A G2F|"Em"EEE E2G|\
"C7"_B2A "B7"=B3|"Em"EEE E2G|
"C7"_B2A G2F|"Em"GFE "D (Bm7)"F2D|\
1"Em"E3-E3:|2"Em"E3-E2B|:"Em"e2e gfe|
"G"g2ab3|"Em"gfeg2e|"D"fedB2A|"Em"e2e gfe|\
"G"g2ab3|"Em"gfe"D"f2d|"Em"e3-e3:|