docs/docs/markdown2html/markdown-format.md

title, layout, breadcrumb

title	layout	breadcrumb
Markdown Format | markdown2html | doc-utils	main.html	[doc-utils](../) [markdown2html](./)

Markdown Format

This document describes the extensions added on top of Marked {:external-link:} by markdown2html.

KaTeX

Math typesetting can be done using KaTeX {:external-link:}, wrapped in a back-tick-fenced block.

```katex "_fig. 1: an example math block_"
a^2 + b^2 = c^2
```

!!! {.markdown-example-output}

a^2 + b^2 = c^2

!!!

Inline expressions can also be wrapped in $, for example:

$x$ to the second power is written as $x^2$

!!! {.markdown-example-output} x to the second power is written as x^2 !!!

Prism Highlighting

Prism {:external-link:} is used to provide syntax highlighting for 290+ languages.

Highlighted code blocks can be displayed in the usual way using a fenced block:

```ts "_fig. 2: some example TypeScript code_"
function say_hello() {
  console.log('Hello, World!');
}
```

!!! {.markdown-example-output}

function say_hello() {
  console.log('Hello, World!');
}

!!!

As is done throughout this document to show examples, you can also nest code blocks by adding additional back-ticks to the outer levels. For example, the sample above is created like this:

````md
```ts "_fig. 2: some example TypeScript code_"
function say_hello() {
  console.log('Hello, World!');
}
```
````

Definition / Description Lists

Definition lists or description lists (<dl> elements) can be rendered using lines that being with a colon (:) character.

An unindented line starting with a colon is a <dt>, and an indented line starting with a colon is a <dd>. Indentation without a starting colon can be used to have multiple lines of content in either type of block. These lists can be nested.

Indentation in <dl> blocks must two consecutive spaces; Other indentation styles are not allowed.

: First Term
  : First Definition
  : Second Definition

: Second Term
  with multiple lines
  of content
  : Third Definition

    : Nested List, First Term
      : Nested List, First Definition
    : Nested List Second Term
      : Nested List, First Definition
        with a _second_ line inside a definition, indicated by indenting again with no colon
  
  : Fourth Definition

: Third Term
  : Fifth Definition

!!! {.markdown-example-output}

First Term

First Definition

Second Definition

Second Term

with multiple lines

of content

Third Definition

Nested List, First Term

Nested List, First Definition

Nested List Second Term

Nested List, First Definition with a second line inside a definition, indicated by indenting again with no colon

Fourth Definition

Third Term

Fifth Definition !!!

Section Blocks

HTML <section> elements can be rendered around portions of your document by fencing them in triple-bang blocks (i.e. preceded and followed by !!!).

!!!
This is inside a `<section>` element
!!!

!!!! {.markdown-example-output} !!! This is inside a <section> element !!! !!!!

Similarly to fenced code blocks, you can nest these fenced blocks by adding additional bang (!) characters to the opening and closing lines.

These blocks also support attribute annotations on the first line:

!!! {.editors-note :role=note}
**Editor's Note:**
Section blocks can be used to create special call-out blocks
!!!

Feather Icons

Feather Icons {:external-link:} can be rendered using tokens that look like {:icon-name:}.

{:feather:} {:external-link:} {:alert-triangle:}

!!! {.markdown-example-output} {🪶} {:external-link:} {:alert-triangle:} !!!

Highlighting

Text can be highlighted with the <mark> tag {:external-link:} by wrapping it in double equals signs (==):

This is some ==highlighted text==.

!!! {.markdown-example-output} This is some ==highlighted text==. !!!

Pikchr Diagrams

Pikchr {:external-link:} can be used to render diagrams, which is also written using fenced blocks.

```pikchr "_fig. 6: an example diagram rendered with Pikchr, based on the docs2website flow_"
MD:     box wid 1.2 ht 0.5 "Markdown"
HTML:   box same at 2.5 east of MD "HTML Fragments"
COLOR:  box same at 0.75 north of HTML "Color Themes"
ASSET:  box same at 0.75 south of HTML "Static Assets"
WEB:    box same at 2 east of HTML "Static Website" fill green color green

arrow from MD .e to HTML .w \
  "markdown2html" italic aligned above small

arrow from COLOR .e to WEB .nw color green
arrow from HTML .e to WEB .w color green
arrow from ASSET .e to WEB .sw color green
```

!!! {.markdown-example-output}

MD:     box wid 1.2 ht 0.5 "Markdown"
HTML:   box same at 2.5 east of MD "HTML Fragments"
COLOR:  box same at 0.75 north of HTML "Color Themes"
ASSET:  box same at 0.75 south of HTML "Static Assets"
WEB:    box same at 2 east of HTML "Static Website" fill green color green

arrow from MD .e to HTML .w \
  "markdown2html" italic aligned above small

arrow from COLOR .e to WEB .nw color green
arrow from HTML .e to WEB .w color green
arrow from ASSET .e to WEB .sw color green

!!!

The following color names are mapped to CSS variables to enable theming:

• red \mapsto --theme-chart-shape-red-fill and --theme-chart-shape-red-line
• orange \mapsto --theme-chart-shape-orange-fill and --theme-chart-shape-orange-line
• yellow \mapsto --theme-chart-shape-yellow-fill and --theme-chart-shape-yellow-line
• green \mapsto --theme-chart-shape-green-fill and --theme-chart-shape-green-line
• teal \mapsto --theme-chart-shape-teal-fill and --theme-chart-shape-teal-line
• pink \mapsto --theme-chart-shape-pink-fill and --theme-chart-shape-pink-line
• purple \mapsto --theme-chart-shape-purple-fill and --theme-chart-shape-purple-line
• blue \mapsto --theme-chart-shape-blue-fill and --theme-chart-shape-blue-line
• indigo \mapsto --theme-chart-shape-indigo-fill and --theme-chart-shape-indigo-line
• magenta \mapsto --theme-chart-shape-magenta-fill and --theme-chart-shape-magenta-line
• brown \mapsto --theme-chart-shape-brown-fill and --theme-chart-shape-brown-line
• black \mapsto --theme-text-body, --theme-bg-heavy, and --theme-line

nomnoml Diagrams

todo

Bytefield Diagrams

todo

QR Codes

QR Codes can be rendered using fenced blocks.

```qrcode :small
https://doc-utils.jbrumond.me/markdown2html/markdown-format.html
```

!!! {.markdown-example-output}

https://doc-utils.jbrumond.me/markdown2html/markdown-format.html

!!!

Footnotes

todo

Vega Charts

todo

Sample Output

Fenced blocks with the samp "language" tag output contents in a <samp> {:external-link:} tag rather than the typical <code> tag, to more semantically markup output examples from code.

```samp "_fig. 4: some sample output, rendered with a <samp> tag_"
This is some sample output
```

!!! {.markdown-example-output}

This is some sample output

!!!

A combination bash:samp fenced block can be used to include shell commands followed by sample output:

```bash:samp "_fig. 5: a combination bash:samp block that outputs a <code> and <samp> together_"
echo 'This is some sample output' && \
  echo 'This is another line of sample output'
This is some sample output
This is another line of sample output
```

!!! {.markdown-example-output}

echo 'This is some sample output' && \
  echo 'This is another line of sample output'
This is some sample output
This is another line of sample output

!!!

Attribute Annotations

Some markdown elements allow for attributes to be appended in a curly-brace ({ }) wrapped block.

The braces contain a space-delimited list of attributes to assign to the rendered element, identified as either:

• An id attribute, prefixed by a # character,
• A class attribute value, prefixed by . character,
• Or, another, named attribute prefixed by a : character

# Heading {#new-id .some .class .names :data-foo=bar}