GitHub-friendly header links

Use case or problem

Since most people use GitHub to store their Obsidian Vaults, compatibility with GitHub’s markdown conventions should be paramount. Ensuring maximum compatibility with GitHub makes it much easier to share vault contents with others. Instead of needing to download and install Obsidian, clone the repository and open the vault locally, they can just view the contents in GitHub’s native UI.

Obsidian markdown is already extremely GitHub-friendly, but internal links to headers are not compatible. GitHub will render a markdown header into HTML like so:

# Some Header

Rendered HTML:

<h2><a id="some-header">...</a>Some Header</h2>

To properly link to this header in GitHub markdown, you’d write a link like this:

[My Link](#some-header)

However, Obsidian does not generate links the same way. Obsidian generates links that look like this:

[My Link](#Some%20Header)

Thus, Obsidian-generated header links do not work in the GitHub UI. They only work properly when the header does not include any spaces or symbols.

Proposed solution

Instead of using HTML URL encoding for headers in Obsidian, provide the option to use GitHub-friendly encoding that converts whitespace and symbols to hyphens. (“Some Header” becomes some-header instead of Some%20Header)


I agree, I wish this were a feature. I’d like to buy Obsidian to use at work so we can edit our team wiki, but the incompatibility with GitHub links is a dealbreaker. Gitea (which we use) uses the same link conventions as GitHub

Related feature request: Unique links to headings (no Wikilinks)

1 Like

Same here. It’s kind of a dealbreaker for me. Such an inconvenience.

1 Like