Heading

Processor name: heading

This replaces the output of Markdown headings that begin with the # character (atx-style headings). This processor an ID to each heading which allows for linking to a heading, and adds the heading number before the heading text.

Note

This processor replaces the output of the standard markdown block processor for atx-style headings.

You may create a heading by using the following format:

# This is an H1

## This is an H2

###### This is an H6

The default HTML for headings is:

<{{ heading_type }} id="{{ title_slug }}">
<span class="section_number">
{% if heading_level >= 1 -%}
{{ "{{ chapter.number }}" }}
{%- endif -%}
{%- if heading_level >= 2 -%}
.{{ level_2 }}
{%- endif -%}
{%- if heading_level >= 3 -%}
.{{ level_3 }}
{%- endif -%}
{%- if heading_level >= 4 -%}
.{{ level_4 }}
{%- endif -%}
{%- if heading_level >= 5 -%}
.{{ level_5 }}
{%- endif -%}
{%- if heading_level >= 6 -%}
.{{ level_6 }}
{%- endif -%}
.
</span>
{{ title }}
</{{ heading_type }}>

Example

Using the following tag:

# This is an H1

## This is an H2

###### This is an H6

The resulting HTML would be:

<h1 id="this-is-an-h1">
<span class="section_number">
{{ chapter.number }}.
</span>
This is an H1
</h1>
<h2 id="this-is-an-h2">
<span class="section_number">
{{ chapter.number }}.1.
</span>
This is an H2
</h2>
<h6 id="this-is-an-h6">
<span class="section_number">
{{ chapter.number }}.1.0.0.0.1.
</span>
This is an H6
</h6>

Overriding HTML for Heading

When overriding the HTML for heading, the following Jinja2 placeholders are available:

  • {{ headling_level }} - A number representing the heading level.
  • {{ heading_type }} - The string of the heading tag i.e. h1 etc.
  • {{ title }} - The title of the heading.
  • {{ title_slug }} - A slug of the heading, useful for ids.
  • {{ level_1 }} - The current first level heading number.
  • {{ level_2 }} - The current second level heading number.
  • {{ level_3 }} - The current third level heading number.
  • {{ level_4 }} - The current fourth level heading number.
  • {{ level_5 }} - The current fifth level heading number.
  • {{ level_6 }} - The current sixth level heading number.

The level parameters are useful for generating levels trails so that users know where they are exactly within the document.

Example

For example, providing the following HTML:

<{{ heading_type }} id="{{ title_slug }}">
<span class="section_number">
{{ level_1 }}.{{ level_2 }}.{{ level_3 }}.{{ level_4 }}.{{ level_5 }}.{{ level_6 }}.
</span>
{{ title }}
</{{ heading_type }}>

with the following markdown:

# This is an H1

## This is an H2

#### This is an H4

# This is an H1

### This is an H3

###### This is an H6

# This is an H1

would result in:

<h1 id="this-is-an-h1">
<span class="section_number">
1.0.0.0.0.0.
</span>
This is an H1
</h1>
<h2 id="this-is-an-h2">
<span class="section_number">
1.1.0.0.0.0.
</span>
This is an H2
</h2>
<h4 id="this-is-an-h4">
<span class="section_number">
1.1.0.1.0.0.
</span>
This is an H4
</h4>
<h1 id="this-is-an-h1-2">
<span class="section_number">
2.0.0.0.0.0.
</span>
This is an H1
</h1>
<h3 id="this-is-an-h3">
<span class="section_number">
2.0.1.0.0.0.
</span>
This is an H3
</h3>
<h6 id="this-is-an-h6">
<span class="section_number">
2.0.1.0.0.1.
</span>
This is an H6
</h6>
<h1 id="this-is-an-h1-3">
<span class="section_number">
3.0.0.0.0.0.
</span>
This is an H1
</h1>