docs/docs/markdown2html/markdown-format.md

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

# Markdown Format

This document describes the extensions added on top of [Marked {:external-link:}](https://marked.js.org/) by [markdown2html].

<outline-inline content-root="body > main"></outline-inline>




## KaTeX {#katex}

Math typesetting can be done using [KaTeX {:external-link:}](https://katex.org/), wrapped in a back-tick-fenced block.

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

!!! {.markdown-example-output}
```katex "_fig. 1: an example math block_"
a^2 + b^2 = c^2
```
!!!

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

```md
$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}

[Prism {:external-link:}](https://prismjs.com/) is used to provide syntax highlighting for 290+ languages.

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

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

!!! {.markdown-example-output}
```ts "_fig. 2: some example TypeScript code_"
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
````md
```ts "_fig. 2: some example TypeScript code_"
function say_hello() {
  console.log('Hello, World!');
}
```
````
`````



## Definition / Description Lists {#dl}

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.

```md
: 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 {#sections}

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

```md
!!!
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](#attribute-annotations) on the first line:

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




## Feather Icons {#feather}

[Feather Icons {:external-link:}](https://feathericons.com/) can be rendered using tokens that look like `{:icon-name:}`.

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

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




## Highlighting {#highlight}

Text can be highlighted with the [`<mark>` tag {:external-link:}](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark) by wrapping it in double equals signs (`==`):

```md
This is some ==highlighted text==.
```

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







## Pikchr Diagrams {#pikchr}

[Pikchr {:external-link:}](https://pikchr.org/home/doc/trunk/homepage.md) can be used to render diagrams, which is also written using fenced blocks.

````md
```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}
```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
```
!!!

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 {#nomnoml}

_todo_





## Bytefield Diagrams {#bytefield}

_todo_





## QR Codes {#qr-codes}

QR Codes can be rendered using fenced blocks.

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

!!! {.markdown-example-output}
```qrcode :small
https://doc-utils.jbrumond.me/markdown2html/markdown-format.html
```
!!!




## Footnotes {#footnotes}

_todo_




## Vega Charts {#vega}

_todo_






## Sample Output {#samp}

Fenced blocks with the `samp` "language" tag output contents in a [`<samp>` {:external-link:}](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/samp) tag rather than the typical `<code>` tag, to more semantically markup output examples from code.

````md
```samp "_fig. 4: some sample output, rendered with a &lt;samp> tag_"
This is some sample output
```
````

!!! {.markdown-example-output}
```samp "_fig. 4: some sample output, rendered with a &lt;samp> tag_"
This is some sample output
```
!!!

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

````md
```bash:samp "_fig. 5: a combination bash:samp block that outputs a &lt;code> and &lt;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}
```bash:samp "_fig. 5: a combination bash:samp block that outputs a &lt;code> and &lt;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
```
!!!





## Attribute Annotations {#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

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









[docs2website]: ../docs2website
[markdown2html]: ../markdown2html