Why Obsidian Users Want Their Word Docs in Markdown
Obsidian stores every note as a plain .md file in a folder on your local filesystem, with no proprietary database, no lock-in, just text files you can open with any editor. That design choice is the reason Obsidian's knowledge graph, backlinks, and search all work without a server: the vault is just a directory. It has also driven the growth of the Obsidian community plugin directory, which lists over 1,000 third-party extensions as of 2026, all of them built on top of plain .md files precisely because the format can be extended without breaking compatibility.
Word's .docx format doesn't fit this model. A .docx file is a ZIP archive of XML, so it can't be opened in Obsidian, linked to from another note, or indexed by the graph view. Converting it to Markdown puts the content where Obsidian can reach it: in a plain .md file that participates in your vault's link structure and shows up in search.
The conversion is a one-way step. Once the note lives in your vault as a .md file, you maintain it there. If stakeholders or clients need a Word version later, the Markdown to Word converter handles the reverse direction.
What Obsidian-Flavored Markdown Needs
This is the part that most conversion guides skip: Obsidian uses a superset of standard Markdown. The converter outputs valid GitHub Flavored Markdown, which is correct and readable in Obsidian, but it doesn't produce the Obsidian-specific syntax that activates the features most users rely on.
Here's what standard converter output looks like vs. what Obsidian natively uses:
| Feature | What MDTool produces (GFM) | What Obsidian expects (native) |
|---|---|---|
| Internal note links | [Note Title](note-title.md) | [[Note Title]] wikilink |
| Link with display name | [Display Name](note.md) | [[Note Title\|Display Name]] |
| Callouts / admonitions | > plain blockquote | > [!note] Title |
| Tags | Not produced | Inline #tag or tags: in YAML |
| Properties / frontmatter | Not produced | YAML block at top of file |
| Highlights | Not produced | ==highlighted text== |
The important framing here: standard GFM links still work in Obsidian, and a [Note](note.md) link will navigate correctly. They just don't appear as connections in the graph view or show up as backlinks. Wikilinks ([[Note Title]]) are what Obsidian's graph draws edges for.
Whether you need wikilinks depends on how you use Obsidian. If you're importing standalone reference documents (a spec, a policy, a report) you'll reference but not heavily interlink, standard GFM output is fine as-is. If you're building a connected knowledge base where the graph view matters, plan to convert internal references to wikilinks after conversion.
Step-by-Step: Converting a Word Document With MDTool
The fastest path to a vault-ready .md file:
- Open your
.docxfile in Word and accept all tracked changes (Review → Accept → Accept All Changes). The converter outputs only the accepted text, so unresolved tracked changes will silently disappear. - Go to the word to markdown converter.
- Drag and drop the
.docxfile onto the left panel, or click the file picker. - The converter reads the document using mammoth.js, extracting heading styles, bold/italic, lists, tables, and hyperlinks, then renders GitHub Flavored Markdown via turndown.
- Download the
.mdfile using the Download button, or copy the Markdown and paste it into a new file in your vault. - Move the
.mdfile into your vault folder by dragging it in Finder/Explorer to the correct location in your vault's directory structure.
Alternative: The Docxer Plugin
If you want to convert Word documents without leaving Obsidian, the Docxer community plugin (83,988 downloads, v2.3.1, actively maintained as of May 2026) lets you open a .docx file directly inside a vault tab and convert it with a single click. It uses the same mammoth.js + turndown pipeline under the hood, so the output is equivalent to what MDTool produces.
Install from Settings → Community Plugins → Browse → search "Docxer". One limitation worth knowing: Docxer's output is standard Markdown, not Obsidian-flavored wikilinks, so the post-conversion steps below still apply.
Post-Conversion Cleanup for Obsidian
A converted .md file is readable in Obsidian immediately, but five steps make it a proper vault citizen:
1. Add YAML Frontmatter (Properties)
Obsidian 1.4+ renders a YAML properties block at the top of any note as an interactive panel. Add it at the very start of the file:
---
title: Your Document Title
tags:
- imported
- word
source: original-filename.docx
created: 2026-06-25
---
Obsidian will index the tags: values and make them searchable across your vault. The source: field is useful if you need to trace the note back to its origin.
2. Convert Links to Wikilinks (for Graph View)
Find any [text](filename.md) links in the converted output that point to other notes in your vault. Convert them to wikilink syntax: [[filename]] or [[filename|display text]]. This is what makes connections appear in Obsidian's graph view and backlinks panel.
If the document doesn't reference other vault notes (it's a standalone import), skip this step entirely.
3. Upgrade Blockquotes to Callouts (Optional)
The converter outputs Word text boxes and some formatting as plain Markdown blockquotes (> text). Obsidian supports 13 callout types that render as styled admonition boxes:
> [!note] Title
> Content here
> [!warning] Caution
> Something to watch out for
> [!tip]
> A helpful tip
If the original document had note boxes or warning panels, upgrading the corresponding blockquotes to callouts takes a few seconds per item and significantly improves readability in Obsidian's Live Preview mode.
4. Check Image Paths
Word embeds images as binary objects inside the .docx ZIP. They are not extracted by MDTool or Docxer in their default configuration. After conversion, any image that was in the original document will be absent from the Markdown output. Re-add images manually:
- Export images from the Word document (right-click → Save as Picture)
- Copy the image files into a subfolder in your vault (e.g.,
/attachments/or/assets/) - Add the image references in the Markdown:
![[image.png]](Obsidian wikilink embed) or(standard Markdown)
5. Add Inline Tags or a Folder Tag
For vault organization, either add #tags inline in the note body where relevant, or put the note in a folder and create a folder note (_index.md) that links to all imported documents in that folder. This helps avoid a pile of disconnected files after bulk imports.
Frequently Asked Questions
Q: Can I open a .docx file directly in Obsidian without converting it?
No. Obsidian only renders files in its supported formats: Markdown (.md), Canvas (.canvas), and a handful of image/audio/video/PDF types. A .docx file will appear in the vault's file list but will not render. You must convert it to .md first.
Q: Does the converted Markdown show up in Obsidian's graph view?
The note itself shows up in the graph once it's in the vault. Its links only appear as graph edges if the links use [[wikilink]] syntax. Standard [text](url) links are not drawn as connections. Convert internal note references to wikilinks if graph visibility matters.
Q: Is Obsidian Sync safe for vault files converted from Word?
Yes. Obsidian Sync uses AES-256 end-to-end encryption (confirmed on the official pricing page, $4/month billed annually). The converted .md files are treated identically to any other vault file: they sync the same way and are encrypted in transit and at rest.
Q: What happens to headers, bullet lists, and bold text after conversion?
These convert cleanly. Word's Heading 1 style becomes # H1 in Markdown, bullet lists become - item, and bold text becomes **bold**. The conversion preserves structural styles: it reads what Word explicitly marks as a heading, not what looks like a heading visually.
Q: What about footnotes in Word documents?
GFM has no standard footnote syntax, so Word footnotes are dropped by the converter. You can add Markdown extended footnote syntax ([^1]) manually, and Obsidian renders extended footnotes in reading view, though they're not part of strict GFM.
Q: Can I convert a batch of Word files at once?
Not through MDTool (one file at a time). The Docxer plugin also processes files individually. For bulk imports, the command line is the right tool: pandoc *.docx --to=markdown with a shell loop, or Microsoft MarkItDown (Python, batch-capable, MIT licensed) for programmatic pipelines.
Q: Will the converted file appear in Obsidian search?
Yes, immediately. Obsidian indexes all .md files in the vault on startup and re-indexes continuously. A freshly dropped .md file is searchable within seconds.
Q: My Word document used colors to indicate status (red = draft, green = approved). Will that survive?
No. Font color and highlight color are presentational properties with no Markdown equivalent. They are dropped during conversion. If status markup matters, add Obsidian tags (#draft, #approved) to the YAML frontmatter after conversion instead.
For Markdown syntax reference after importing, see the Markdown cheatsheet. If you need to convert back to Word for sharing with non-Obsidian users, the word to markdown converter handles the reverse direction.