Text Headings

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 Title Usually 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}
Jackie will budget for the most expensive zoology equipment.

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

Five jumping wizards hex bolty quick. Both fickle dwarves jinx my pig quiz. Quirky spud boys can jam after zapping five worthy Polysixes. The job of waxing linoleum frequently peeves chintzy kids.

Subsection

Sex-charged fop blew my junk TV quiz. Quads of blowzy fjord ignite map vex’d chicks. Grumpy wizards make a toxic brew for the jovial queen. Public junk dwarves quiz mighty fox.

Sub-Subsection

The quick onyx goblin jumps over the lazy dwarf. The quick brown fox jumped over the lazy dogs. Big fjords vex quick waltz nymph. Quads of blowzy fjord ignite map vex’d chicks.

Paragraph

Glib jocks quiz nymph to vex dwarf. Cozy sphinx waves quart jug of bad milk. Schwarzkopf vexed Iraq big-time in July. Few quips galvanized the mock jury box.

Small paragraph

When zombies arrive, quickly fax judge Pat. Brawny gods just flocked up to quiz and vex him. Quirky spud boys can jam after zapping five worthy Polysixes. Go, lazy fat vixen; be shrewd, jump quick.

Paragraph attribute

Jack, love my big wad of sphinx quartz! Battle of Thermopylae: Quick javelin grazed wry Xerxes. Sex-charged fop blew my junk TV quiz. Crazy Frederick bought many very exquisite opal jewels.

Danger

Who packed five dozen old quart jugs in my box? Five hexing wizard bots jump quickly. Just poets wax boldly as kings and queens march over fuzz. DJs flock by when MTV ax quiz prog.

Warning

“Who am taking the ebonics quiz?”, the prof jovially axed. Schwarzkopf vexed Iraq big-time in July. Quick blowing zephyrs vex daft Jim. Woven silk pyjamas exchanged for blue quartz.

Info

JCVD might pique a sleazy boxer with funk. Jacky can now give six big tips from the old quiz. Waxy and quivering, jocks fumble the pizza. Quizzical twins proved my hijack-bug fix.

Success

Waxy and quivering, jocks fumble the pizza. Junk MTV quiz graced by fox whelps. Cozy lummox gives smart squid who asks for job pen. Quizzical twins proved my hijack-bug fix.

See Also