Links to headings and table of contents

Every heading in a document is an address. You can link to it, a chat answer can cite it, and a table of contents can list all of them - using the same link syntax Obsidian and GitHub use, so what you write here keeps working when the file is opened elsewhere.

The address of a heading

A heading’s address is its text, lowercased, with spaces turned into hyphens:

Accented characters are kept as they are - #odpowiedzialność, not #odpowiedzialnosc - so the address reads like the heading it points at.

If the same heading text appears twice, the second one gets -1, the third -2, and so on, in the order they appear in the document. Every heading in a document has its own address; no two share one.

Linking

Write a normal markdown link whose target starts with #:

See [Termination](#11-term-and-termination) for what survives.

Click it and the document scrolls to that heading. To edit a link’s text instead of following it, double-click the word - that selects it and puts you in the text.

To point at a heading in another file, put the file first:

See [the annex](annex.md#scope) and [the schedule](sub/schedule.md).

The file opens and scrolls to the heading. Paths are relative to the document you are writing in, or to its workspace folder - the same rule images follow. A link that points outside the folder, or at a file that isn’t there, does nothing and says so.

If you prefer, you can point at the heading text instead of the address. A link target cannot contain bare spaces (that is standard markdown, and GitHub follows it too), so write them as %20 - [Termination](#Term%20and%20Termination), which is also what Obsidian writes when it creates a link - or wrap the target in angle brackets: [Termination](<#Term and Termination>). Return finds the heading either way. The address form is the one that travels to other apps.

Citations in chat

When an answer cites a section of the document you are working on, the citation is a link. Click it and the document scrolls to that clause, so you can check the wording the answer is describing. Internal links are marked with a dotted underline to tell them apart from links that open your browser.

Inserting a table of contents

Press + in the margin or type /toc, choose Table of contents, and pick how deep it should go - one, two or three levels.

The list covers the document’s headings, with one exception: the heading you are standing directly under is left out, because a row linking to the heading right above the list goes nowhere. Put the list under the document’s title and you get its sections, cleanly.

What lands in the document is plain markdown:

- [Definitions](#definitions)
  - [Affiliate](#affiliate)
- [Term and Termination](#term-and-termination)

That is deliberate. It is readable in any editor, it survives export to PDF or Word, and you can edit it - delete a row, reword a label. The trade is that it does not update itself: rename a heading afterwards and the table of contents still shows the old wording. Delete it and insert it again to refresh.