Heading link compatibility

Obsidian links to headings don’t work on Github and Github flavor markdown links to headings don’t work in Obsidian.

Things I have tried

- [Pokémon Overview](#pokémon-overview)
- [Pokémon Overview](#Pokémon%20Overview)

## Pokémon Overview

The first link works in Github but not in Obsidian. The second works in Obsidian but not on Github (at least not in Firefox on Linux).

What I’m trying to do

I am trying to write markdown that can be viewed successfully in Obsidian while also being viewed successfully on Github in a browser.

Is there a CommonMark specification or some generic markdown that all viewers support for heading links?


The Markdown is the same — GitHub and Obsidian are using different formats for the IDs they automatically assign to headings. To make links that work in both places you’ll need to manually assign IDs for one of the formats yourself. I’m not sure what the best way to do that is; my first thought would be to add an empty div above the heading,

- [Pokémon Overview](#Pokémon%20Overview) links to the heading in Obsidian and (if GitHub processes it) to the div in GitHub.

<div id="Pokémon%20Overview}></div>

## Pokémon Overview

This seemed like a pretty good suggestion but I couldn’t get it to work yet.

I also tried setting the heading id with an HTML anchor tag but that also is not yet working.

Obsidian doesn’t seem to recognize either <div> or <a> id’s. For me anyway. Even when I go into edit mode and type in [[# the id in the <div> does not show up in the list.

Maybe some mucking through the elements in the console will reveal what the <div> id is in Obsidian.

It appears it is only the space in a heading that causes the incompatibility between Obsidian and Github heading links. Obsidian seems to insist on a %20 for a space in the heading link while Github insists on using a -. Using all lower case as Github requires does not seem to bother Obsidian. Maybe there are other incompatibilities but the space is what is causing an issue in my heading links.

The workaround I am currently employing is to not use spaces in headings. That’s a pretty lame workaround. I am still experimenting with ways to insert a custom id for headings. Nothing yet works. I’ve tried the above suggested empty <div>, an HTML anchor in the heading, and placing the ID in curly brackets after the heading:

## My Heading  {#put-id-here}

None of those are working yet but I would really like to come up with some way to provide heading link compatibility other than headings with no spaces.

I do not know how many markdown documents are hosted on Github or what percentage of all the markdown in the world resides on Github but I would guess it is a large majority. If your markdown viewer/editor does not support the basics of Github flavor markdown then you are kind of in the same situation as a small fry doing something different than Microsoft in 1995.

[Edit:] I don’t want to sound like I am faulting Obsidian for their adoption of a heading link id that is incompatible with Github. It may very well be that the fault is Github’s for adopting some non-standard heading link id. I don’t know. It does remind me of Microsoft in the 90s when they controlled an overwhelming majority of desktops and would do all kinds of non-standard stuff then everybody in the world would have to conform to that. And guess who owns Github?

There is a feature request for Github style implicit heading id generation:

Is there any support in Obsidian for custom heading id’s ? The extended Markdown syntax for this is:

### My Great Heading {#custom-id}

I can’t get that to work in Obsidian.

Did you try it the other way, with the GitHub style ID in the div?

Yes, I’ve tried it both ways - using a Github flavor heading id with an empty <div> id equal to the Obsidian heading id as well as an Obsidian heading id with an empty <div> id equal to the Github flavor heading id. And I tried it with the <div> before and after the heading.

Here is my latest test, using the Obsidian heading id with an empty <div> after the heading for Github. This works in Obsidian, as you would expect, but Github doesn’t pick up the <div> id like you would hope:

- [Pokemon Overview](#Pokemon%20Overview)
- [See Also](#See%20Also)

## Pokemon Overview
<div id="#Pokemon%20Overview"></div>

## See Also
<div id="#See%20Also"></div>

If I put the empty <div> before the heading then it doesn’t work in Obsidian. It seems like it should but Obsidian isn’t seeing the <div> id. I don’t think Github is either.

Thanks for trying to help me. Until a solution is conceived I am using the workaround of:

  • Reduce headings to a single word where that makes sense
  • Replace spaces with underscores in headings with spaces
  • Use Github flavor heading ids in internal links

That workaround isn’t so bad. I realized that many of my headings were actually clearer as a single word and those that are better with multiple words do not suffer that much using underscores.

But, it is a mess. Even the CommonMark spec is not clear on this. Everybody is just doing whatever they want. There should be a standard.

This might not help, but put a blank line between the heading and the div. You generally want blank lines between blocks, and sometimes it can affect how things are processed.

I can’t quickly find Obsidian documentation about this regarding HTML, but the original Markdown description says,

block-level HTML elements — e.g. <div> , <table> , <pre> , <p> , etc. — must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces. Markdown is smart enough not to add extra (unwanted) <p> tags around HTML block-level tags.

Good find but it didn’t work. At least not in my first few tests.

I did a little more digging in the developer console in Firefox with Github.

Github prepends a “user-content” string to the <div> id I assign. I hate the developer console. I hate how the font is so small and navigation is so hard. Remarkably, Obsidian’s developer console is much easier to navigate than Firefox. But it still sucks.

Anyway, back to reality, I don’t understand what Github is doing. It is, of course, possible that I am just ignorant and stupidly doing something wrong. Or, maybe Github is stupid.

I have not yet been able to identify what Obsidian thinks the <div> id is. Neither Github or Obsidian seem to recognize any custom <div> id that I assign.

I’m having this same issue, and snake-cased auto-generated links for headers seem to be more widely accepted than whatever Obsidian is doing with it’s “%20” thing. Even ignoring Github.

Is there any way Obsidian could offer a setting to decide which header → link creation format we’d prefer to use? That way, existing user notes using %20 format don’t brake, while the ones interested in the more consistent snake-cased style can opt-in for it.


What Obsidian is doing is URL encoding - Wikipedia.