Support GFM style #kebab-case-heading-slug anchor targets

Use case or problem

I’m trying to use Obsidian to browse and maintain a repository of related documents that link to each other in a way compatible with GitHub, Bitbucket, VS Code, and internal tools:

## This is an Internal Heading

[This is a link to the internal heading](#this-is-an-internal-heading)

If I try to follow such a link in Obsidian, it fails:

Unable to find selection in this-document-filename

If I alter the links to use Obsidian’s preferred anchor target, users of other tools can’t follow the links:

[This link to the internal heading works in Obsidian only](#This%20is%20an%20Internal%20Heading)

Proposed solution

I’d like a repository setting useSlugsForHeadingAnchors which, if set true, altered Obsidian’s behaviour to:

  • Generate a slug for each heading in a manner compatible with GitHub’s Markdown rendering
  • Render headings with an anchor using that slug
  • Render inserted links with a target using that slug

Example rendered output given our original Markdown might be:

<h2><a id="this-is-an-internal-heading">This is an Internal Heading</a></h2>

<a href="#this-is-an-internal-heading">This is a link to the internal heading</a>

Current workaround (optional)

I can’t find a workaround.

Related feature requests (optional)

I can’t find related feature requests.


So, basically, github-compatible links, right?

1 Like

Yes please! Can we have this?

Super convenient.

I would really appreciate this feature as well.

Hi, same here. Also would be great to have support for GFM, perhaps parallel to Obsidian native markdown and be able to choose which one to use.

This feature would be essential for integration with Docusaurus, too.

1 Like

I am adding one point to this topic.
Currently all markdown editors I am familiar with, including Github, Gitlab, Stackedit, IntelliJ, and Visual Studio Code, all support #dash-style-links.

That makes it very difficult for me to move my notes collection to Obsidian as I will loose the references in the process.

Maybe we can have a configuration that allows us to chose the format of the links.

1 Like

I too would find this extremely helpful. As a new user importing my collection of markdown files, none of my tables of contents within notes are usable in Obsidian, but they do work on github, gitlab, bitbucket etc. It seems most other markdown → html renders do automatic anchors to headings this way by default.

Another feature request also mentioned this a short while later: Publish: Support for lowercase and kebab-case slugs in URLs

I, too, would like this.

If this feature is implemented, I would love to see an add-on feature where the link is rendered as the original non-normalized heading/title etc. in preview mode?

That is, if linking to heading:

## The Rain in Spain Falls Mainly on the Plains


For more details see: [[doc2#the-rain-in-spain-falls-mainly-on-the-plains]]

we would see

For more details see: The Rain in Spain Falls Mainly on the Plains

(I know we can get the same effect by titling the link with an alias, so maybe I can just settle for that :slight_smile: )

1 Like


It would be nice if kebab-case header ids become the default for Markdown links, unlike Wikilinks.

Related feature requests:

Another related feature request:

Is implicit header identification in GFM documented somewhere? In GitHub Flavored Markdown Spec header id‑attributes are not documented.

In Pandoc’s markdown spec implicit header references are documented for example—although Obsidian is not intended to support Pandoc’s markdown. If only text is used without GUI−tools, then implicit header references are not optimal since you must write them verbosely. In such cases custom attributes offer really nice solution. Pandoc’s custom attributes syntax:

## heading etc {#identifier .class .class key=value key=value}

## my heading test test test test {#my-heading}

[link to my heading](#my-heading)

I think Obsidian’s block identifiers syntax ## heading ^block-id is similar to above although linking takes different syntax #^block-id and not #block-id.