Headings introduce and order content segments on a page. Heading levels need to descend without interruption. We can modify headings only visually when we want to skip some levels.

Syntax

Markdown headings are preceded by number signs # and a space. The six available headings are associated with the following meaning in Perplex:

  1. # Page TitleUsually not available!

  2. ## Section Heading

  3. ### Subsection Heading

  4. #### Sub-Subsection Heading

  5. ##### Paragraph Heading

  6. ###### Small Paragraph Heading

To alter the style of these headings, Perplex offers a few special Markdown attributes.

Visual paragraph headings

On moderately sized pages, we usually don’t want to apply the full heading hierarchy because too much structure is as confusing as too little. We may like to skip one or two levels and use paragraph headings in normal sections for example.

However, this would violate official HTML guidelines and mess up the table of contents (TOC). Heading tags always need to descend strictly also because screen readers and other automatic interpreters get confused otherwise.

To abide by this rule, we can skip headings only visually. Any heading does look like a paragraph heading with the attribute {.h-p} or {.h-p-s} for a small paragraph heading.

Highlighted headings

To emphasize especially important text segments, we can start them with a highlighted heading. This is a more subtle option than annotation boxes.

To mark a section about some danger, warning, information, or success, we apply the attributes {.h-danger}, {.h-warn}, {.h-info}, or {.h-success}.

A warning paragraph for example starts with a heading like this:

##### Warning Paragraph {.h-warn}
Six big devils from Japan quickly forgot how to waltz.

Very long headings with complicated topics stretching over more than one line

CommonMark offers no possibility to break a heading line because every line starting with the number sign # starts a new heading.

When a heading exceeds the line length of the layout, it automatically reflows into the next line. That may occur at an unfortunate place: Before the last word or between tightly related words. To introduce a manual break of our own choosing we can put the replacement code {‍/} between two words without any spacing character like this:

### Nice long heading with a complicated topic{‍/}stretching over more than one line

and we get:

Nice long heading with a complicated topic 
stretching over more than one line

This line break is displayed only when the viewport allows for the full-text width. On small screens, the manual break is hidden, because manual line breaks tend to come out even worse on small viewports with additional automatic breaks.

Layout

Headings are not only recognized by their font styling but also by the space surrounding them. That’s why the following examples are shown in the way they usually appear: In front and in between some text.


Page Title

The first heading is reserved for titles. Only one <h1> tag should occur on any webpage. We may want to compose a title in Markdown on special pages but in all theme templates, the title section is rendered from meta-data in the frontmatter.

Section

Junk MTV quiz graced by fox whelps. Quick brown fox jumps over the lazy dog. Quest judge wizard bonks foxy chimp love. Public junk dwarves hug my quartz fox.

Subsection

How quickly daft jumping zebras vex. Jackdaws love my big sphinx of quartz. Quick fox jumps nightly above wizard. A quivering Texas zombie fought republic linked jewelry.

Sub-Subsection

Public junk dwarves hug my quartz fox. Hick dwarves jam blitzing foxy quip. Woven silk pyjamas exchanged for blue quartz. Foxy parsons quiz and cajole the lovably dim wiki-girl.

Paragraph

Jackdaws love my big sphinx of quartz. Kvetching, flummoxed by job, W. zaps Iraq. Sex-charged fop blew my junk TV quiz. GQ jock wears vinyl tuxedo for showbiz promo.

Small paragraph

Waxy and quivering, jocks fumble the pizza. A quivering Texas zombie fought republic linked jewelry. Go, lazy fat vixen; be shrewd, jump quick. Five hexing wizard bots jump quickly.

Paragraph attribute

Bored? Craving a pub quiz fix? Why, just come to the Royal Oak! Nymphs blitz quick vex dwarf jog. A quick brown fox jumps over the lazy dog. My jocks box, get hard, unzip, quiver, flow.

Danger

Watch “Jeopardy!”, Alex Trebek’s fun TV quiz game. Crazy Frederick bought many very exquisite opal jewels. By Jove, my quick study of lexicography won a prize. Both fickle dwarves jinx my pig quiz.

Warning

Levi Lentz packed my bag with six quarts of juice. The five boxing wizards jump quickly. Vexed nymphs go for quick waltz job. Bright vixens jump; dozy fowl quack.

Info

Quilt frenzy jackdaw gave them best pox. Quizzical twins proved my hijack-bug fix. Vex quest wizard, judge my backflop hand. The quick brown fox jumps over a lazy dog.

Success

Quick blowing zephyrs vex daft Jim. Foxy parsons quiz and cajole the lovably dim wiki-girl. Jackie will budget for the most expensive zoology equipment. Vamp fox held quartz duck just by wing.