Adding a table of contents

Documentation & Support Forum
1

This topic is a linked part of a larger work: “Discourse Website Manual for edgeryders.eu”

Content

1. Introduction

2. Adding headings and link targets

3. Adding the table of contents

1. Introduction

Any long post with well-structured content can benefit from a table of contents. It provides a quick way to jump down to the desired section.

While a table of contents is good for navigability and general user experience, it is a bonus: not having it doesn’t ruin your post.

For good examples of Tables of Contents according to the instructions below, you can look at the following topics:

2. Adding headings and link targets

Before you can add a table of contents, you need elements in your content to jump to. Our convention is to use use headings and sub-headings, with a decimal classification scheme for numbering. In your post you would enter it like this:

## <h2 id="heading--1">1. Heading of first chapter</h2>

[Other content, probably paragraphs of text and stuff.]

### <h3 id="heading--1-1">1.1. Heading of first sub-chapter</h3>


## <h2 id="heading--2">2. Heading of second chapter</h2>

[Other content, probably paragraphs of text and stuff.]

Usage hints:

  • No H1 headings. For the headings in your text, start with the H2 headings (## Heading title) because this is also done when using the “Heading” button in the integrated editor. (Means, do not use H1 headings (# <h1 id="heading--…">…</h1>) at all, even though they do work.)

  • Subpart markers in Discourse. Discourse is picky about what subpart markers will work in links. You can only use the following. In all cases, the id and name attribute values must not contain space characters, and it is a common convention to use only lowercase letters and dashes.

    • <h2 id="heading--…"></h2> and similarly for H3 to H5 (source)
    • <h6 id="heading--…"></h6> element for invisible link target, not showing the content of the heading element; this is our own CSS hack to use for link targets independent of a table of contents, and you’re welcome to use non-numerical ID values here
    • <a name="…"></a> elements but better not as these only work when clicking a link in the same post as the target – so inside a table of contents it works, but you cannot send a working link with a subpart marker to a friend. The <h… id="heading--…"> mechanism, in contrast, works everywhere.

  • Subpart markers for ToC. We have based the names for the subpart markers on the chapter numbers. In practice, this is nicer to work with than creating arbitrary names for the subpart markers, even though you have to adapt them when chapter numbers change of course.

  • Combining Markdown and HTML headings. Technically we would not need the ## or ### Markdown formatting for headings, as the same is provided by the HTML tags afterwards. (The Markdown formatting even creates empty, invisible heading tags on its own.) However, by convention we keep the source code as close as possible to what the Discourse editor’s buttons would produce, and that’s headings in the ##, ### etc. scheme. Markdown does not yet allow to create subpart markers, so we use the HTML heading tags as a workaround until it does one day.

  • Linking to subpart markers. When linking inside the same topic, a relative link with just the subpart marker such as [link text](#heading--1-1) works fine and is the shortest possible option as well.

    However, when linking from other posts, other topic, and external websites to subpart markers in a Discourse topic, there is a Discourse quirk (or bug) to consider. In that case, use a URL format such as https://example.com/t/id/1234#heading--1-1 or, from within the same Discourse site, /t/id/1234#heading--1-1. Instead of “id”, you can also keep the original title slug of a topic URL in place, at the expense of a longer URL. You cannot, however remove the title slug path element (here id/) completely, unlike with all other links to topics and posts in Discourse; because here it causes Discourse to not jump to the subpart marker!

    Even with the https://example.com/t/id/1234#heading--1-1 URL format, there is a quirk: Discourse will navigate and jump to the subpart marker alright, but will only display the subpart marker in the URL if you open the link in a new tab, or from an external website.

    If anyone likes to: please report these quirks to Discourse. We seem to be the only ones using subpart markers with Discourse?

3. Adding the table of contents

While you can format your table of contents in your own way, for consistency across topics we recommend using the following example as your style guide:

## Content

**[1. Markdown](#heading--1)**

  * [1.1. Markdown formatting cheatsheet](#heading--1-1)
  * [1.2. Markdown formatting details](#heading--1-2)

**[2. BBCode formatting](#heading--2)**

  * [2.1. Basic text formatting](#heading--2-1)
  * [2.2. Lists, Images, Code](#heading--2-2)
  * [2.3. Special features](#heading--2-3)

----

This will create a table of contents looking like this (just without the quotation background coloring):

Content

1. Markdown

2. BBCode formatting

Usage hints:

  • Basic idea. The basic principle is that a hyperlink that you create in your text, for example [1. Heading of first chapter](#heading--1), will appear in your text as “1. Heading of first chapter” and on click will make the document jump to section 1. These links use the link target names defined in the previous section.

  • Section title. Use “Content” as section title with a H2 header (## in Markdown). Because this is the default header for the first header level produced by the Discourse editor.

  • Vertical spacing. For good looks and readability, use one empty line between each two top-level chapters and between a top-level chapter and a block of sub-level chapters.

  • Separator line. Note the horizontal line below the table of contents. We propose to use it as it produces a nice separation to the start of the actual content.

2 Likes