Need AI Training/Help?CloudYeti.io/meet
MarkdownMe
Obsidian to Markdown guide

Export Obsidian Notes to GitHub Without Broken Links

A vault file copied straight into a repository shows literal wikilinks, unrendered callouts, and ==highlight== markers. Convert the Obsidian syntax first, then commit.

Direct answer

Obsidian stores plain .md files, so the files themselves need no export step, but four pieces of syntax are Obsidian-only and break on GitHub: wikilinks, embeds, callouts, and highlights. Convert each note with the tool above before committing. It rewrites links and embeds to inline Markdown, maps callouts to GitHub alerts, converts ==highlight== to a <mark> element, and removes %%comments%% and ^block-ids.

Open the Obsidian ↔ Markdown converter

When to use this

  • You keep documentation in a vault and publish it as a repository README or docs folder.
  • A note rendered correctly in Obsidian and looked broken on GitHub.
  • You are handing notes to people who do not use Obsidian.

Steps

  1. Open the note in Obsidian and copy the raw Markdown, not the reading view.
  2. Paste it into the converter above with the direction on Obsidian → standard Markdown.
  3. Choose Strip for frontmatter if the YAML block is vault metadata that does not belong in the repository.
  4. Choose Strip for #tags if the tags are vault-only organisation.
  5. Download the .md file, place it in the repository, and fix any relative paths that differ from the vault layout.

Example conversion

Input
---
tags: [ops]
---

See [[Runbook]] and ![[architecture.png]].

The ==retention window== is 30 days. ^ref-1
Converted output
See [Runbook](Runbook.md) and ![](architecture.png).

The <mark>retention window</mark> is 30 days.

(frontmatter kept or stripped, your choice)

Common mistakes

  • Do not commit attachments by name alone. An embed becomes ![](architecture.png), so the image file must be copied into the repository at that path or the image will not load.
  • Do not rely on <mark> everywhere. GitHub renders it, but renderers that block raw HTML will show the text unhighlighted.
  • Do not convert Dataview queries and expect results. They are plugin features with no Markdown equivalent and pass through unchanged.
  • Do not paste one note at a time if you have hundreds; this tool converts the text you paste and has no folder or batch mode.

FAQ

Does Obsidian need an export plugin for this?
No. Vault files are already .md on disk. The problem is Obsidian-specific syntax inside them, which is what this converter rewrites.
Can it convert a whole vault at once?
No. It converts the text you paste, one note at a time. For a full vault, a scripted pass over the files is a better fit; this tool is for the notes you publish by hand.
Will my images work after the move?
Only if you copy the attachment files into the repository at the same relative path. The converter rewrites the link syntax; it cannot move files.

Related Obsidian guides

How to Convert Obsidian Wikilinks to Standard Markdown

Obsidian writes links as [[Note]] and [[Note|alias]]. Only Obsidian reads that syntax. Convert each one to [alias](Note.md) so the link works on GitHub and any other renderer.

Convert Obsidian Callouts to GitHub Markdown Alerts

Obsidian callouts use > [!note] Title. GitHub supports five alert types with uppercase names and no inline title. Here is the mapping the converter applies.

Obsidian Frontmatter and Tags: What to Keep When You Export

YAML frontmatter drives properties in Obsidian and drives nothing on GitHub. Inline #tags are vault navigation. Decide per destination, then keep or strip both with one option each.

Turn an Obsidian Vault Note Into Portable Markdown

Portable Markdown is text that renders the same in every reader. This is the list of Obsidian-only syntax that stops a note being portable, and what each piece becomes.