DEV Community: Usman

Moving Word Docs into Obsidian Without Breaking Your Vault

Usman — Tue, 13 Oct 2026 13:30:00 +0000

Most of my notes live in Obsidian, but a lot of what I need to keep arrives as Word documents: specs, meeting notes, policies. Dropping a .docx into the vault does nothing useful, and a naive conversion gives you a file that sits outside the graph with no backlinks.

This is the workflow I use to get Word documents into a vault properly, including the Obsidian-specific cleanup that most conversion guides skip.

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\
Callouts / admonitions	{% raw %}`> 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 .docx file 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 .docx file 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 .md file using the Download button, or copy the Markdown and paste it into a new file in your vault.
Move the .md file 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. MDTool keeps them, but inline: each image becomes a long base64 data: link (![](data:image/png;base64,...)) instead of a separate file in your vault. That makes the note heavy and awkward to edit, so swap them for real attachment files:

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 ![alt text](attachments/image.png) (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?

They aren't lost: the converter turns Word footnotes into a numbered list at the end of the note, with [1]-style links where each one was referenced. Obsidian also supports Markdown footnote syntax ([^1]), which renders as proper footnotes in reading view, so you can convert the list to that syntax by hand if you prefer.

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 Markdown to Word converter handles the reverse direction.

I build MDTool, the free browser converter used in this post. It's open source (MIT), so if something breaks in it, open an issue or tell me in the comments.

How to Download a GitHub README as PDF (Badges, Tables and Mermaid Included)

Usman — Tue, 06 Oct 2026 13:30:00 +0000

Every so often someone asks me for "the docs as a PDF": a client, a reviewer, a manager who wants to read it on a plane. The docs are a GitHub README, and GitHub has no "Download as PDF" button. Printing the page from the browser drags in GitHub's navigation, and most converters quietly break the parts that matter: badges vanish, tables collapse and Mermaid diagrams come out as raw code.

Here's the workflow I use, plus fixes for the three things that usually go wrong: private repos, relative image paths and wide tables.

The short version: open README.md, click Raw, copy everything, paste it into a GFM-aware Markdown to PDF converter, pick a GitHub-style theme and download.

What Makes GitHub READMEs Different from Ordinary Markdown

A typical README contains several elements that generic Markdown parsers struggle with:

Badge images. Lines like ![Build](https://img.shields.io/github/actions/workflow/status/...) fetch images from shields.io and similar external URLs. Server-side converters often block external requests; browser-based tools load them normally.

Fenced code blocks with language tags. GitHub renders these with syntax highlighting. A PDF converter needs to do the same, not just preserve the raw text.

GFM tables. Pipe-delimited tables (| Col1 | Col2 |) only work if the parser has GFM mode enabled. Standard CommonMark parsers ignore them entirely.

Task lists. - [x] Done and - [ ] Todo syntax renders as checkboxes on GitHub. A GFM-aware converter renders them as actual checkbox characters; others render them as literal brackets.

Mermaid diagrams. GitHub natively renders mermaid code fences as diagrams. Most PDF tools don't support this at all.

Step-by-Step: GitHub README to PDF

Step 1: Get the Raw Markdown

On any GitHub repository page, click the file name of README.md (or README.mdx), then click Raw in the top-right toolbar. You'll see the plain Markdown source. Select all (Ctrl+A) and copy it.

Alternatively, you can download the raw file directly:

curl -o README.md https://raw.githubusercontent.com/user/repo/main/README.md

Step 2: Paste Into MDTool

Open a browser-based converter such as MDTool's Markdown to PDF and paste your README. The live preview on the right renders immediately, and you'll see headings, tables, code blocks, and badges appear in real time.

Step 3: Check Badges and External Images

Badges (shields.io, github.com/actions/...) are standard <img> tags in the rendered HTML. Because MDTool runs in your browser, those images load normally from their external URLs, the same way they load on GitHub. You should see them in the preview.

If a badge doesn't appear, it's usually because:

The image URL requires authentication (private repo badges)
The external server is rate-limiting requests

In those cases, either remove the badge row before converting or replace the URL with a static image URL that doesn't require auth.

Step 4: Select a Theme

The GitHub theme in MDTool follows GitHub's own rendering style: dark body text, blue links, light-gray code backgrounds, and bordered tables. If you want the PDF to look as close to GitHub's rendered view as possible, use the GitHub theme. The other themes are Academic, Minimal and Dark, and every theme works with A4 or Letter paper.

Step 5: Download the PDF

Click Download PDF. The entire conversion runs in your browser, so your README content is never uploaded to any server.

Mermaid tip: MDTool renders Mermaid diagrams before it builds the PDF, so the flowchart, sequence diagram or ER diagram you see in the preview appears in the PDF output.

Handling Common README Elements

Code Blocks

GitHub READMEs frequently include multi-language code blocks. MDTool uses highlight.js with GFM mode, supporting JavaScript, TypeScript, Python, Bash, Go, Rust, SQL, JSON, YAML, HTML, CSS, Dart and more.

A block like this:

```typescript
export async function fetchRepo(owner: string, repo: string) {
  const res = await fetch(`https://api.github.com/repos/${owner}/${repo}`);
  if (!res.ok) throw new Error(`GitHub API error: ${res.status}`);
  return res.json();
}
```

Renders with full syntax coloring: keywords, strings, types, and function names each get distinct colors, exactly as they appear on GitHub.

Tables

GFM tables convert cleanly. A README table like:

| Feature       | Status |
|---------------|--------|
| Code blocks   | ✅     |
| Mermaid       | ✅     |
| Badges        | ✅     |
| Task lists    | ✅     |

Will appear as a properly bordered, styled table in the PDF, not as a pipe-delimited text wall.

Mermaid Diagrams

Project architecture diagrams in READMEs are often written in Mermaid. MDTool initializes the Mermaid renderer in the browser before the PDF export step, so:

```mermaid
graph LR
  PR[Pull Request] --> CI[GitHub Actions]
  CI -->|Pass| Merge[Merge to main]
  CI -->|Fail| Fix[Fix & Re-push]
```

Renders as an actual diagram in the PDF, not as a code block with raw Mermaid syntax.

Task Lists

- [x] Set up CI pipeline
- [x] Write unit tests
- [ ] Add integration tests
- [ ] Deploy to production

MDTool's GFM parser recognizes task lists. In the PDF, each checkbox is drawn as a bold monospace [x] (done) or [ ] (to do), so the status stays readable even when printed in black and white.

Private repositories and READMEs with images

The three-step method works the same for a private repository, because you copy the Markdown while you're signed in to GitHub and nothing about the conversion needs repository access. Two things behave differently, though.

Getting the file from the command line. raw.githubusercontent.com URLs for private repos need authentication, so a plain curl returns a 404. Use the GitHub CLI, which calls the REST API's Get a repository README endpoint with your credentials:

gh api repos/OWNER/REPO/readme -H "Accept: application/vnd.github.raw+json" > README.md

Images. Images stored in a private repository can't be fetched by anyone who isn't signed in with access, and the image links GitHub generates for private content are short-lived signed URLs. An image URL you copy from the rendered page may work for a few minutes and then break. For a PDF that keeps its images:

Move the images somewhere public you control (a docs site, a public assets repo, or an object storage bucket) and point the Markdown at those URLs, or
Remove the images and describe them in text if the PDF is going to an audience that only needs the content.

Badges (shields.io and similar) are public images, so they usually load fine even for private repositories. Status badges that query a private repo's CI may show "unknown" or fail to load, and deleting the badge row before converting is the quickest fix.

Relative image paths: use raw.githubusercontent.com URLs

GitHub recommends relative links for images in READMEs, such as ![Architecture](docs/architecture.png). GitHub resolves those paths against the repository and branch you're viewing. Once you copy the Markdown out of GitHub, there's no repository to resolve against, so the image is missing from the preview and the PDF.

The fix is to turn each relative path into an absolute raw.githubusercontent.com URL:

<!-- Before: relative path, only works on GitHub -->
![Architecture](docs/architecture.png)

<!-- After: absolute raw URL, works anywhere -->
![Architecture](https://raw.githubusercontent.com/OWNER/REPO/main/docs/architecture.png)

The pattern is https://raw.githubusercontent.com/OWNER/REPO/BRANCH/PATH. These URLs send the cross-origin headers a browser needs to embed the image, which is why they work in a browser-based converter. Replace main with your default branch (or a tag, if you want the PDF to match a release). Paths that start with ./ or ../ work the same way once you resolve them from the README's folder.

To fix every image at once, a find-and-replace in your editor does the job. Replace ](docs/ with ](https://raw.githubusercontent.com/OWNER/REPO/main/docs/ and adjust for each folder your README uses. Images that already use absolute https:// URLs don't need changing.

If MDTool can't fetch an image (a broken path, a private URL, or a server that blocks cross-origin requests), the PDF shows a gray [image: alt text] placeholder in its place instead of failing. Search the PDF for "[image:" to find any you missed.

Privacy: Why Client-Side Conversion Matters for READMEs

Private repositories often have READMEs containing internal architecture decisions, credentials in example snippets, or unreleased feature documentation. When you use a server-side converter, that content passes through someone else's infrastructure.

MDTool converts your README entirely in the browser using pdfmake, which writes real, selectable text into the PDF. When you click Download, the PDF is assembled from the rendered HTML on your machine. Open the browser's Network tab while converting and you'll see zero requests carrying your Markdown content outbound. Your README stays on your device.

Comparing GitHub README to PDF Tools

Tool	GFM Tables	Code Highlighting	Mermaid	No Upload	Free
MDTool	✅	✅	✅	✅	✅
Dillinger	✅	✅	❌	❌ (PDF built on its server)	✅
CloudConvert	Partial	Partial	❌	❌	10 conversions/day
markdowntopdf.com	✅	✅	✅	Not stated	Watermark on free downloads

Competitor features checked against each tool's site and, for Dillinger, its open-source code, as of October 2026.

For a deeper comparison, see our best Markdown to PDF converters guide, or check the full Markdown syntax cheatsheet for every element a README might use.

Frequently Asked Questions

Q: How do I convert a README to PDF?

Open the README on GitHub, click Raw, copy the Markdown, paste it into a Markdown to PDF converter such as MDTool, and click Download PDF. Choose the GitHub theme if you want the PDF to look like the README on GitHub.

Q: Why are images missing from my README PDF?

Most READMEs use relative image paths like docs/screenshot.png, which only resolve on GitHub. Replace them with absolute https://raw.githubusercontent.com/OWNER/REPO/BRANCH/PATH URLs before converting. Images from private repositories also need to be hosted somewhere public.

Q: Can I convert a private GitHub README?

Yes. Copy the raw Markdown content and paste it into MDTool. Since conversion is client-side, your content never leaves your browser. You don't need to connect MDTool to your GitHub account.

Q: Badges are showing as broken images in the PDF. What do I do?

This usually means the badge URL is either rate-limited or requires authentication (common for private repositories). The simplest fix is to delete the badge row from the Markdown before converting. Alternatively, right-click the badge on GitHub, copy the image address, and replace the dynamic URL with the resolved static URL.

Q: My README has a very long table. Will it fit on the page?

Wide tables are the hardest element to handle in any Markdown-to-PDF workflow. MDTool lays the PDF out on A4 or Letter paper, and long words and URLs in cells are allowed to wrap. If your table has more than 5 to 6 columns, consider shortening cell content or splitting it into smaller tables before converting.

Q: Does MDTool support GitHub's custom > [!NOTE] alert syntax?

GitHub's alert extensions (> [!NOTE], > [!WARNING], etc.) are a recent addition that isn't yet part of the GFM spec. MDTool renders them as standard blockquotes. You'll see the content, but without the colored border and icon that GitHub adds.

Q: Can I automate README to PDF conversion?

MDTool is a browser-based tool designed for manual conversions; it has no CLI or API. For automated pipelines, such as generating PDFs in CI, see our guide to Markdown to PDF with Python, Pandoc and Node. For code with syntax highlighting and Mermaid support in CI, see our guide on Markdown to PDF code blocks.

Q: Does the PDF include anchor links (internal links within the README)?

Internal anchor links (e.g., [See Installation](#installation)) are preserved as links in the PDF. Whether they work depends on the PDF viewer, and most desktop PDF viewers support internal anchor navigation.

I build MDTool, the free browser converter used in this post. It's open source (MIT). If your README breaks in it, I'd like to see it: open an issue or drop it in the comments.

I got tired of paywalls for Markdown converters, so I built a free, 100% client-side alternative.

Usman — Thu, 25 Jun 2026 11:51:02 +0000

As a software engineer, I write almost everything in Markdown. It's fast, clean, and lives easily in Git. But sharing those documents with non-technical clients or teammates usually requires converting them into PDFs or Word documents.

When I went looking for tools to handle this, I hit two major roadblocks:

Privacy: Most free online converters require you to upload your files to a backend server. For private code documentation, internal wiki pages, or client notes, that's a real security risk.
Paywalls: The tools that actually handled clean formatting or two-way conversions (especially for Word .docx files) were almost entirely gated behind monthly subscriptions.

So I decided to build it myself.

MDTool is a free, browser-based Markdown conversion suite that processes everything locally on your machine. Zero server uploads. Zero sign-ups. And it's open source on GitHub under the MIT license, so you can check exactly what happens to your files.

The 7 tools included

Instead of making you jump between single-purpose websites, everything lives in one workspace:

Markdown to PDF: Real vector PDFs with selectable, searchable text (not a screenshot of the page). Renders Mermaid diagrams, highlights code blocks, and has 4 themes (GitHub, Academic, Minimal, Dark) on A4 or US Letter.
Markdown to Word (.docx): Builds a genuine Word document rather than a renamed HTML file. Headings map to Word's built-in Heading 1-6 styles, so the navigation pane and automatic table of contents work, and tables and nested lists stay editable.
Markdown to HTML: Clean, semantic HTML as a snippet or a full document.
Markdown to Plain Text: Strips the Markdown syntax while keeping paragraphs, lists and table rows readable.
Word (.docx) to Markdown: Drag in a Word file and get clean Markdown back, with the hidden proprietary styling stripped out.
HTML to Markdown: Paste raw HTML and get GitHub Flavored Markdown, handy for moving legacy web copy into docs.
Markdown Table Generator: A visual grid with column alignment and paste-from-Excel/Google Sheets.

How it works under the hood

To keep everything 100% client-side, the app is built with Next.js and a handful of open-source libraries that run in the browser:

marked parses the Markdown, with highlight.js for code and Mermaid for diagrams.
pdfmake lays out the PDF as real vector text, which is why the output stays selectable and searchable.
The docx library builds proper OpenXML Word files from the Markdown structure.
mammoth.js and turndown (with the GFM plugin) power the reverse direction, Word and HTML back to Markdown.

The heavy engines are only loaded when you actually convert something, so the pages stay fast, and your content never leaves your browser.

Try it out

I built this toolkit to solve my own workflow problems, but I'm hoping it saves some of you a few dollars and a few security headaches.

Everything is free at mdtool.dev, and the code is at github.com/usmankhan045/mdtool.

I'd love to hear your thoughts, especially if you throw heavy nested tables or complex multi-level lists at the Word engine. What tools do you keep in your formatting toolkit?