Unique links to headings (no Wikilinks)

Use case or problem

I use Markdown links (no Wikilinks) within my vault. I often create a TOC (Table of Content) to link to specific headings in the same file. I start typing [[, followed by # to see a list of headings in that file. This relative links work in general, but there are some cases when they don’t.

For example, if the note headings are:

## Header - Example

### A subtitle?

## Another Topic

### A subtitle

the links I get are:

- [Header - Example](#Header%20-%20Example)
    - [A subtitle](#A%20subtitle)
- [Another Topic](#Another%20Topic)
    - [A subtitle](#A%20subtitle)

As you can see, level 3 headers use the same anchor! So both links point to the first heading “A subtitle?”.

Proposed solution

Implicit heading id generation: This process defines a unique id for each MD heading that can be used as an anchor for links.

I’ve seen it in multiples places (StackOverflow, GiHub Gist, GitLab, VS Code) a mostly standardized set of rules to create this ids automatically from the heading text.

  1. punctuation marks will be dropped (Remove anything that is not a letter, number, space or hyphen, like :, ,, ', )
  2. leading white spaces will be dropped
  3. upper case will be converted to lower
  4. spaces between letters will be converted to hyphen -
  5. If the same id has already been generated, a hyphen - and a unique incrementing number (starting at 1) are appended.

The TOC for the example use case with implicit heading ids should be:

- [Header - Example](#header---example)
    - [A subtitle?](#a-subtitle)
- [Another Topic](#another-topic)
    - [A subtitle](#a-subtitle-1)

Current workaround (optional)

Renaming them to make each clearly different for Obsidian is an alternative. Nevertheless, I also dislike the %20 replacing every space character. I’d prefer the hyphen because it creates a more readable id.

I can get a TOC with an appropriate and unique id for every heading pasting the full MD content in nGitHubTOC. But Obsidian doesn’t support them (I’ve tried it in VS Code and it worked!).

Check the nGitHubTOC.js file for the implementation.