Headings in R markdown and how to remove some from the table of contents

[kellijohnson-NOAA]

Header types

Typically, users of R markdown use ATX-style headings, i.e., one to six hash symbols; but another option is to use Setext-style headers. The latter only allows for two delineations, either a header identified with a row of equal signs or a row of dashes below it, e.g.,

A First Level Header
====================

A Second Level Header
---------------------

The remainder of this tip will focus on ATX-style headers, which is preferred when using {sa4ss}. The same headings in the above example can be generated with

# A first level header
First-level headers are equivalent to <h1>.

## A second level header

and additional headings, up to six levels, can be generated by just adding more hash symbols. You do not have to use a first-level header prior to using a second-level header.

There should always be a blank line before a header so markdown can distinguish between a carriage return with text that starts with a hash and an actual header, e.g.,

#A real header
The start of a paragraph
#more text that follows the previous line and will be in the first paragraph.

Headers can be wrapped with trailing hashes though they do not need to be and the trailing hashes do not have to match the number of leading hashes and they will be ignored. For example, # my header # is the same as # my header or # my header ###.

Additional information in a header

Additional information can be supplied to the header after designating it; but, not all information types are used in every output type. For example, identifiers, classes, and key/value attributes are used in HTML but LaTeX only uses identifiers.

{#identifier .class .class key=value key=value}

Identifier

The identifier is typically auto generated but you can specify them. For example, the identifier for our first-level header above would be #a-first-level-header. But, you can also specify it directly, which can be helpful when you have sections that are named the same and you want to reference each of them in different places. Identifiers are case-insensitive regardless of how they are generated.

# A first level header {#a-first-level-header-first-instance}

You could reference this header later in your document using [a-first-level-header-first-instance]. Headers can include formatting and/or links but much of that will be removed in the auto-generated identifier.

Unnumbered

People often use .unnumbered when they want to remove a header from the count system in their table of contents but still have the header displayed. This can be done one of two ways.

# My heading {-}
is just the same as

# My heading {.unnumbered}

The former is preferred and used in {sa4ss} because it is language-agnostic. See the executive summary for an example.

Unlisted

If the unlisted class is present in addition to unnumbered, the heading will not be included in the table of contents.

# Section heading {.unlisted .unnumbered}

References

• Pandoc
• bookdown book