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:
# Page Title
Usually not available!## Section Heading
### Subsection Heading
#### Sub-Subsection Heading
##### Paragraph Heading
###### 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:
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.