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. These 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.


This would be a much appreciated feature, at the very least to remove the horrible percent encoding in header links.

I regularly use obsidian for writing blog posts (Hugo, Zola) and documents (mdBook) and all of the parsers I’ve seen use nearly the same system of converting headers names into ids, however, none of them use percent encoding. This makes it really frustrating to write links because I have to write one that will work when deployed but doesn’t work in obsidian and disrupts my personal workflow.

I feel like a feature like this is really necessary for cross compatibility. Maybe it’ll create some issues with backwards compatibility but having it as an optional feature in the settings would be great.


I third this feature, as parsing between Github and Obsidian is inconsistent at this point. Next to ‘Strict linebreaks’ there may be room to provide an option for ‘Strict header parsing’ and/or ‘Header Bracket IDs’.


I’m having a related issue, and this solution might allow me to work around it at least.

So +1 for me!

I would also really appreciate this feature. I use Obsidian for exporting documentation to DOCX format (using Pandoc), for converting to RTF. Word recognizes heading links using a dash, but not a space or encoded space (%20), so this feature would make the links in my notes also work in Obsidian.

1 Like

I second this. It makes it more compatible with other Markdown engines like Kramdown (used by Jekyll).

1 Like

I also agree. GitHub/Gitea/Gitlab compatible links would be great.

Obsidian is a way better Markdown editor than most other solutions.

1 Like

I agree, Obsidian is way better Markdown editor, and it really hurts that I can’t directly use it with github readme files with table of content. I would really appreciate this feature (even as an option) in Obsidian. Really hoping to see this feature soon InshaAllah~

1 Like