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.
Direct answer
A wikilink is Obsidian syntax, not Markdown. GitHub, GitLab, and CommonMark renderers print [[Note]] as literal text with no link. Run the note through the converter above with the direction set to Obsidian → standard Markdown. It rewrites [[Note]] to [Note](Note.md) and [[Note|alias]] to [alias](Note.md), percent-encodes spaces in the target, and turns a #Heading part into a URL fragment.
Open the Obsidian ↔ Markdown converterWhen to use this
- You are moving a note out of a vault into a repository, a blog, or a wiki.
- A published note shows double square brackets instead of links.
- A teammate opened your file outside Obsidian and every link was dead.
Steps
- Open the converter above and keep the direction on Obsidian → standard Markdown.
- Paste the note, or the section of it that contains the links.
- Decide the frontmatter and #tags options; links convert either way.
- Read the output: each [[...]] is now an inline Markdown link ending in .md.
- Copy or download the file, then check that the target file names match the paths in your destination folder.
Example conversion
See [[Setup Guide|the setup steps]] before [[Runbook]]. Details live in [[Runbook#Rollback]].
See [the setup steps](Setup%20Guide.md) before [Runbook](Runbook.md). Details live in [Runbook Rollback](Runbook.md#rollback).
Common mistakes
- Do not assume the link targets resolve after the move. The converter writes Note.md next to the current file; if your repository puts notes in subfolders, the relative paths need editing.
- Do not expect a heading link to always land in the right place. [[Note#Some Heading]] becomes Note.md#some-heading, which matches GitHub's slug rules but not every renderer's.
- Do not run the reverse direction on a file full of web links expecting wikilinks. Only targets that look like a local .md file are converted back.
FAQ
- Does GitHub render Obsidian wikilinks?
- No. GitHub renders GitHub Flavored Markdown, which has no wikilink syntax. [[Note]] appears as literal brackets. Converting to [Note](Note.md) produces a working link in the repository file view.
- What happens to a link with an alias?
- [[Note|alias]] becomes [alias](Note.md). The alias becomes the visible link text and the note name becomes the target file.
- What about spaces in note names?
- Spaces are percent-encoded as %20 in the link target, which is what a Markdown renderer needs. The visible text keeps the readable spelling.
- Can it convert standard links back into wikilinks?
- Yes, in the reverse direction, but only for targets that look like local notes — a relative path ending in .md. Web URLs, mailto links, and same-page anchors are left as standard Markdown, which is what Obsidian expects for those.
Related Obsidian guides
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.
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.
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.