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

# Markdown Format {#/}

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

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




## 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 {: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!');
}
```
````
`````




## Feather Icons

[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

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 {: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

_todo_





## Bytefield Diagrams

_todo_





## QR Codes

_todo_




## Footnotes

_todo_




## Vega Charts

_todo_






## Sample Output

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

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

The braces contain a space-delimeted list attributes to assign to the rendered attribute, 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/index.html
[markdown2html]: markdown2html/index.html

