Table of Contents

Title, Headings, and Table of Contents

All documents must have a single rank-1 heading (<h1>, or # Foo in Markdown), which is the document title. Using only a single h1 departs from common Markdown practice, but is a common accessibility recommendation. Coursage enforces it.

By default, the contents of the h1 show up as the document’s title in links throughout the site (in assignment lists, in the timeline, etc). Documents can override this: a name value in the front matter becomes the title for links, and the h1 remains the title visible when viewing the document itself. This is useful for long titles:

---
name: "Funkytown"
---

# Funkytown: Won’t you take me? (An exciting activity with an over-long title)

For longer documents, generate a table of contents in the site’s standard format using {:standard_toc}. The TOC usually follows immediately after the top heading, but does not need to; prefatory text or imagery is OK. However, the table of contents should appear near enough to the top of the page that a reader can jump to it immediately by scrolling to the top of the document.

You can make links to specific headings in a document by setting a custom anchor on the heading with {#your-anchor-name}. The {#...} markup only works on headings. You can link to these anchors within a document, from other docs on the course site, or from external sites.

A concrete example: the “Task 3: Extra fun chaos!” heading in the maps_intro document has this source:

## Task 3: Extra fun chaos! {#map-keys-chaos}

and is linked to from the “contracts and breaking changes” reading with:

...the ["Extra fun chaos" in the Introduction to Maps exercise](/activities/maps_intro/#map-keys-chaos). One...

Note that you can just use the auto-generated anchors from the table of contents, too, but those depend on (1) the precise wording of the heading, and (2) the details of how the table of contents generates the actual anchor. (For example, what does it do with various forms of punctuation, spacing, special characters?) By specifying your own anchor, you can guarantee referential integrity even if the heading text or TOC generation change.