---
title: HTML Converter
---
# HTML Converter

## Introduction

This converter converts a kramdown element tree into an HTML fragment and supports all available
element types. Below is a list of additional features of the HTML converter as well as some
additional information.


## Automatic Generation of Header IDs    {#auto-ids}

kramdown supports the automatic generation of header IDs if the option `auto_ids` is set to `true`
(which is the default). This is done by converting the untransformed, i.e. plain, header text (or,
if the option `auto_id_stripping` is set, only the text from real text elements) via the following
steps:

* All characters except letters, numbers, spaces and dashes are removed.
* All characters from the start of the line until the first letter are removed.
* Everything except letters and numbers is converted to dashes.
* Everything is lowercased.
* If nothing is left, the identifier `section` is used.
* If a such created identifier already exists, a dash and a sequential number is added (first `-1`,
  then `-2` and so on).

Note that the option `auto_id_stripping` will be removed in version 2.0 because this will be the
default behaviour!

Following are some examples of header texts and their respective generated IDs:

| Sample header | generated ID | generated ID with `auto_id_stripping` |
| `# This is a header` | this-is-a-header | this-is-a-header |
| `## 12. Another one 1 here` | another-one-1-here | another-one-1-here |
| `### Do ^& it now` | do--it-now | do--it-now |
| `# Hallo` | hallo | hallo |
| `# Hallo` | hallo-1 | hallo-1 |
| `# 123456789` | section | section |
| `# <i>test</i>` | itesti | test |

> The automatic creation of header IDs is not part of standard Markdown. The rules on how header
> text is converted to an identifier are based on the rules specified by [Pandoc].
{: .markdown-difference}

Such generated IDs are only used if no ID has been set manually before.

## Standalone Images

By assigning the reference name "standalone" to an image that is the sole content of a paragraph,
the image will be rendered inside a `<figure>` element instead of an image inside a paragraph.

## Code Blocks

A code block is wrapped in both `<pre>` and  `<code>` tags.

### Showing Whitespace in a Code Block

It is sometimes useful to visualize whitespace within a code block. This can be achieved by adding
the class `show-whitespaces` to a code block (using a [block IAL](../syntax.html#block-ials)).

Here is an example where the whitespaces are shown:

    	  leading tab	and space
    trailing   tab and space    	
{: .show-whitespaces}

When showing whitespace in a code block, all spaces are replaced with the entity `&sdot;` and
additionally spaces and tabs in the code block are marked up using HTML `span` tags and the
following CSS classes:

* `ws-space-l`, `ws-tab-l`: leading spaces/tabs
* `ws-space-r`, `ws-tab-r`: trailing spaces/tabs
* `ws-space`, `ws-tab`: spaces/tabs in between


## Automatic Syntax Highlighting   {#syntax-highlighting}

kramdown supports setting a code language for code blocks and code spans, see [Language of Code
Blocks](../syntax.html#language-of-code-blocks). This language will be used for highlighting code
blocks and spans.

The actual syntax highlighting is configurable via the [option
'syntax_highlighter'](../options.html#option-syntax-highlighter). The default value is 'coderay'
which implies that the [Coderay syntax highlighter](../syntax_highlighter/coderay.html) is used.

Another syntax highlighter is [Rouge](../syntax_highlighter/rouge.html) which is Pygments
compatible, i.e. it supports all of Pygments CSS themes.


## Math Support

kramdown supports the use of various math engines. The default math engine is
[MathJax](../math_engine/mathjax.html) (which can also be used with
[KaTeX](https://khan.github.io/KaTeX/)).

For proper functionality, the HTML template must be configured to link to the engine's Javascript
and CSS. Note that the CSS includes references to webfonts.

Also available are precompiling versions to eliminate the need for client-side Javascript. Those are
[Mathjax-Node](../math_engine/mathjaxnode.html), [KaTeX](../math_engine/katex.html), and
[SsKaTeX](../math_engine/sskatex.html). Each one requires a Javascript engine installed where
kramdown runs, in order to perform the precompilation. The resulting pages still require CSS and
fonts, but no Javascript anymore.

Alternative math engines are [Ritex](../math_engine/ritex.html) and
[itex2MML](../math_engine/itex2mml.html) both of which output MathML.


## Emphasis

kramdown uses the HTML element `em` to style light and the element `strong` to style strong
emphasized text parts.


## Definition Lists

kramdown allows the automatic generation of element IDs for terms of a definition list. The
algorithm is the same as with headers (see [above](#auto-ids) except that the last two points about
adding "section" and unique IDs is not respected. Also, the algorithm works only on the real text as
if `auto_id_stripping` was activated.

The automatic generation of IDs is activated by assigning the reference name "auto_ids" to a
definition list. This will generate plain IDs without a prefix. By using a reference name of the
format "auto_ids-PREFIX", the prefix is used.

Such generated IDs are only used if no ID has been set manually.

Here are examples:

{kdexample::}
{:auto_ids}
term
: definition
{kdexample}

{kdexample::}
{:auto_ids-prefix}
term
: definition
{kdexample}



## Footnotes

If a document contains footnotes, they are automatically placed at the end of the document.

By assigning the reference name "footnotes" to an ordered or unordered list, the list will be
replaced with the footnotes, instead of placing the footnotes at the end of the document.


## Automatic "Table of Contents" Generation    {#toc}

kramdown supports the automatic generation of the table of contents of all headers that have an ID
set. Just assign the reference name "toc" to an ordered or unordered list by using an IAL and the
list will be replaced with the actual table of contents, rendered as nested unordered lists if "toc"
was applied to an unordered list or else as nested ordered lists. All attributes applied to the
original list will also be applied to the generated TOC list and it will get an ID of `markdown-toc`
if no ID was set.

When the `auto_ids` option is set, all headers will appear in the table of contents as they all will
have an ID. Assign the class name "no_toc" to a header to exclude it from the table of contents.

Here is an example that generates a "Table of Contents" as an unordered list:

    # Contents header
    {:.no_toc}

    * A markdown unordered list which will be replaced with the ToC, excluding the "Contents header" from above
    {:toc}

    # H1 header

    ## H2 header

For a "Table of Contents" as an ordered list:

    1. The generated Toc will be an ordered list
    {:toc}

    # H1 header

    ## H2 header


## Options

The HTML converter supports the following options:

{options: {items: [auto_ids, auto_id_prefix, auto_id_stripping, transliterated_header_ids, template, footnote_nr, entity_output, smart_quotes, toc_levels, syntax_highlighter, syntax_highlighter_opts, math_engine, math_engine_opts, footnote_backlink, footnote_backlink_inline, typographic_symbols]}}


{include_file: doc/links.markdown}
