title

Titles define the structure of a Mechdown document and drive generated navigation such as the table of contents.

Mechdown supports hierarchical titles:

  • Document title: the file's top heading

  • Section titles: numbered headings such as 1. Section

  • Subsection titles: headings such as (1.1) Subsection

  • Sub-subsection titles: headings such as (1.1.1) Topic

It also supports optional front matter directly beneath the document title. Front matter ends with a second === separator and can include:

  • optional K:V front matter fields (author, date, hero, kicker, summary, next, previous)

  • optional hero media (![caption](src) or a | ... | figures row/table)

  • optional summary paragraph

Rules and conventions

  • Use one document title per file. The document can have optional K:V front matter immediately following the title.

  • Keep section numbering sequential.

  • Keep subsection numbering aligned with the parent section.

  • Prefer short, descriptive titles so generated navigation remains readable.

Examples

Mechdown Title Guide
===============================================================================

1. Section Title
-------------------------------------------------------------------------------

(1.1) Subsection Title

(1.1.1) Sub-subsection Title

Section and first-level subsection titles are included in the generated table of contents.

To add a byline, place it immediately after the title and conclude with a second === separator:

My Document
===============================================================================
By Mika the Mech
===============================================================================

Front matter with byline, hero, and summary:

This is my title
===============================================================================
Foo Bar January 1 2026
![my hero](hero.png)
This is my blog and it's good.
===============================================================================

%% abstract blocks and unsectioned introduction content can appear before the first numbered section. The generated contents begin at the first numbered section (for example, 1. Section), while pre-section material can be rendered separately via template placeholders.

Template placeholders

In HTML shims, these placeholders are available:

  • {{STYLESHEET}}

  • {{TITLE}}

  • {{AUTHOR}}

  • {{DATE}}

  • {{KICKER}}

  • {{NEXT}}

  • {{PREVIOUS}}

  • {{HERO}}

  • {{SUMMARY}}

  • {{TOC}}

  • {{ABSTRACT}}

  • {{INTRO}}

  • {{CONTENTS}}

  • {{CONTENT}} (alias for sectioned contents)

  • {{CITED}} (renders Works Cited only where this placeholder appears)

  • {{SECTION#}} where # is the 1-indexed numbered section (for example, {{SECTION1}}, {{SECTION2}})

See Template Placeholders for the complete placeholder reference, including interactive placeholders such as {{CODE}} and {{REPL}}.