Headings
========

Oatcake attempts to style `<h1>`, `<h2`> and `<h3>` headings to be clearly distinct from
each other so that readers can easily orient themselves within the structure of
the document. The headings vary in their size (based on the Perfect Fifth
modular scale), in their font weight, and in the vertical space above and
below.  Headings have more vertical space above them than below so that they're
visually closer to the text below (that belongs to the heading) than to the
unrelated text above.

Here's a demo of the three levels of headings:

<div class="headings-demo" markdown="1">
# Level 1 Heading
{:.no_toc}

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer malesuada,
justo tincidunt mattis gravida, velit orci facilisis nibh, at hendrerit risus
sem eu arcu. Cras sollicitudin aliquam libero, in vestibulum velit vestibulum
sed. Praesent ullamcorper est eget velit aliquet pretium. Maecenas tempus mi
pellentesque congue ultrices. Ut pharetra mattis sem ac vestibulum. Mauris ut
hendrerit mi. Phasellus ligula eros, ullamcorper eu odio ac, porttitor aliquam
ex. Duis imperdiet risus a elementum placerat. Suspendisse efficitur ac metus
nec tempor. Etiam eu gravida sapien. Integer sollicitudin vehicula ex et
tempus. Fusce sit amet blandit lectus. Fusce at leo arcu. Morbi eget tellus
elit. Duis efficitur volutpat laoreet.

## Level 2 Heading
{:.no_toc}

Suspendisse vitae bibendum libero. In in lorem lacus. Proin pharetra neque
venenatis, fringilla justo id, elementum magna. Maecenas vestibulum tortor
urna, vel pharetra nisi commodo vel. Sed ultrices auctor nunc. Nunc hendrerit,
nunc at euismod cursus, ligula dolor fermentum ligula, quis dictum neque velit
sit amet elit. Integer vel justo ac augue blandit porta euismod at nisl.

### Level 3 Heading
{:.no_toc}

Suspendisse dignissim tempor ultricies. Phasellus in sollicitudin felis, eget
fringilla quam. Vestibulum suscipit arcu dapibus placerat cursus. Suspendisse
dignissim orci in nibh convallis, sit amet tempus dui tincidunt. Sed
sollicitudin sollicitudin quam, quis dictum ante lacinia non. Proin bibendum,
sem id pulvinar sodales, diam elit euismod nibh, vel vehicula dolor erat
placerat est. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam
facilisis purus et sapien aliquam consequat. Aenean mattis in risus sed
faucibus. Vivamus luctus pulvinar orci, ut posuere est. Mauris vitae volutpat
est. Curabitur dapibus felis quis lorem volutpat tincidunt. Aenean consectetur
lorem quis aliquam consequat. Praesent elementum mattis lorem, a pharetra odio
vestibulum nec. Donec at rutrum tortor.
</div>

Fourth, fifth and sixth-level headings
--------------------------------------

HTML provides six levels of headings but too many levels of headings in a
document are exhausting and confusing to the reader and difficult for the design to visually
distinguish clearly enough without resorting to desperate measures. It's better
to use only two or three levels of headings.
So Oatcake styles `<h4>`'s, `<h5`>'s and `<h6>`'s the same as `<h3>`'s.
If you really want to use more than three levels of headings you can denote
the structure of the document by numbering the headings yourself:

<div class="headings-demo" markdown="1">
# 1. First-Level Heading
{:.no_toc}

## 1.2 Second-Level Heading
{:.no_toc}

### 1.3 Third-Level Heading
{:.no_toc}

#### 1.4 Fourth-Level Heading
{:.no_toc}

##### 1.5 Fifth-Level Heading
{:.no_toc}

###### 1.6 Sixth-Level Heading
{:.no_toc}
</div>

Heading anchor links
--------------------

If you hover the mouse over any heading in this post you'll notice that they
all have clickable `#anchor` links attached to them for deep linking.
For example here's a deep link to the [first sub-heading in this post](#fourth-fifth-and-sixth-level-headings).

Inline styles in headings
-------------------------

Headings can contain some inline styles:

<div class="headings-demo" markdown="1">
# A heading with _italics_ in it
{:.no_toc}
## A heading with `code()` in it
{:.no_toc}
### `an_all_code_heading()`
{:.no_toc}
# `code()` at the start of a heading
</div>

Headings that follow other headings
-----------------------------------

Headings that immediately follow other headings have less vertical space above
than they would otherwise:

<div class="headings-demo" markdown="1">
# First-Level Heading
{:.no_toc}

## Second-Level Heading
{:.no_toc}

### Third-Level Heading
{:.no_toc}

#### Fourth-Level Heading
{:.no_toc}

##### Fifth-Level Heading
{:.no_toc}

###### Sixth-Level Heading
{:.no_toc}
</div>

Headings in blockquotes
-----------------------

Headings that begin a blockquote have less vertical space above them:

> # An `<h1>` at the start of a `<blockquote>`
>
> This is the body of the blockquote.
>
> ## An `<h2>` within the blockquote
>
> ^ Further headings within a blockquote do have the usual vertical spacing.

> ## An `<h2>` at the start of a `<blockquote>`
>
> This is the body of the blockquote.
>
> ### An `<h3>` within the blockquote
>
> ^ Further headings within a blockquote do have the usual vertical spacing.

> ### An `<h3>` at the start of a `<blockquote>`
>
> This is the body of the blockquote.
>
> # An `<h1>` within the blockquote
>
> ^ Further headings within a blockquote do have the usual vertical spacing.

Headings in alerts
------------------

The same also applies to headings that start
[alerts](/jekyll-theme-oatcake/{% post_url 2019-09-09-alert-boxes %}):

<div class="note" markdown="1">
# An `<h1>` at the start of an alert

This is the body of the alert

## An `<h2>` within the alert

^ Further headings within an alert do have the usual vertical spacing.
</div>

<div class="todo" markdown="1">
## An `<h2>` at the start of an alert

This is the body of the alert.

### An `<h3>` within the alert

^ Further headings within an alert do have the usual vertical spacing.
</div>

<div class="seealso" markdown="1">
### An `<h3>` at the start of an alert

This is the body of the alert.

# An `<h1>` within the alert

^ Further headings within an alert do have the usual vertical spacing.
</div>

Headings in disclosure boxes
----------------------------

And the same _also_ applies to headings that start
[disclosure boxes](/jekyll-theme-oatcake/{% post_url 2019-08-09-disclosure-boxes %}),
with and without `<summary>`'s:

<details>
  <summary>A disclosure box with a summary</summary>
  <h1>A first-level heading</h1>
  <p>A paragraph.</p>
  <h2>A second-level heading</h2>
  <p>^ Further headings within a disclosure box do have the usual vertical spacing.</p>
</details>

<details>
  <h2>A disclosure box <i>without</i> a summary</h2>
  <p>A paragraph.</p>
  <h3>A third-level heading</h3>
  <p>^ Further headings within a disclosure box do have the usual vertical spacing.</p>
</details>

Multiline headings
------------------

Multiline headings are supported, including with inline elements like `<code>`,
`<kbd>` and `<samp>`. This is a multiline `<h1>` heading:

<div class="headings-demo" markdown="1">
# Lorem ipsum dolor sit amet, `consectetur` <samp>adipiscing</samp> <kbd>elit</kbd>, sed do `eiusmod` <samp>tempor</samp> <kbd>incididunt</kbd> ut labore
{:.no_toc}
</div>

This is a multiline `<h2>` heading:

<div class="headings-demo" markdown="1">
## Lorem ipsum `dolor` sit amet, consectetur <samp>adipiscing</samp> elit, sed do eiusmod `tempor` <kbd>incididunt</kbd> ut labore <samp>et dolore</samp> magna aliqua. Ut enim ad <kbd>minim</kbd> veniam
{:.no_toc}
</div>

This is a multiline `<h3>` heading:

<div class="headings-demo" markdown="1">
### Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod `tempor` incididunt ut <samp>labore</samp> et <kbd>dolore</kbd> magna aliqua. Ut enim ad `minim` veniam, quis <samp>nostrud</samp> <kbd>exercitation</kbd> ullamco
{:.no_toc}
</div>