GitHub-friendly header links

Feature requests
1

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)

12 Likes
2

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
3

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

1 Like
4

There is a solution to this with the open source markdown editor “QOwnNotes” see . It requires switching to standard markdown links though.

  1. Install Obsidian Community Plugin “Better Markdown Links”. Conver your vault to standard markdown notation
  2. Open QOwnnotes. Install the community script LInk “Import and Converter” as described on the QOwnNotes Website.
  3. Press ObsidianImport
  4. Press GFMExport (Github flavoured markdown export)

Now the whole Vault is in github friendly style ready for uploading to github.
The button: GFM Import will convert everything back to Obsidian Style.

I use both editors side by side. Everytime i use Obsidian I just click the ObsidianImport button in QN to adapt minor syntax changes.

6

There are Obsidian Plugins such as “Obsidian markdown export” or there is also a commandline tool “https://github.com/avcton/obsidian-exporter“. Another Commonmark Exporter: GitHub - zoni/obsidian-export: Rust library and CLI to export an Obsidian vault to regular Markdown .