DEV Community: Usman

Excel or Google Sheets to a Markdown Table, the Fast Way

Usman — Tue, 03 Nov 2026 13:30:00 +0000

Hand-typing a Markdown table from a spreadsheet is the kind of task that takes ten minutes and produces one misaligned pipe you only notice after pushing. There's a much faster route, and it works because of how spreadsheets put data on your clipboard.

Converting an Excel or Google Sheets table to Markdown takes three steps: select and copy the cells in your spreadsheet, paste them into a Markdown table generator, and copy the generated Markdown. Spreadsheets place copied cells on the clipboard as tab-separated text, so a converter can rebuild the rows and columns exactly, with no add-in, export step, or upload required.

This guide covers that workflow end to end: why the clipboard trick works, what survives the conversion (and what doesn't), and how to fix the three things that most often break spreadsheet-sourced tables in Markdown.

Why Copy-Paste Works: The Tab-Separated Clipboard

When you copy a range of cells in Excel, Google Sheets, LibreOffice Calc, or Numbers, the spreadsheet writes two versions to your clipboard: a rich one (HTML) and a plain-text one. The plain-text version separates columns with tab characters and rows with newlines, a format called TSV (tab-separated values).

That plain-text version is what a Markdown table generator reads. Each tab becomes a column boundary, each line becomes a row, and the first row is treated as the header. Because tabs almost never appear inside spreadsheet cell content, TSV parsing is far more reliable than CSV parsing, where commas inside values (like "1,000" or "Portland, OR") routinely split cells in the wrong place.

The practical consequence: you don't need an Excel add-in or a file exporter to get Markdown out of a spreadsheet. The clipboard already contains everything the conversion needs.

The Workflow, Step by Step

Select the cells in Excel or Google Sheets (include the header row).
Copy them (Ctrl+C / Cmd+C).
Open the Markdown Table Generator and click Paste from Excel / CSV.
Paste. The grid fills with your data, first row as the header.
Adjust anything that needs it: click the alignment control above a column to align it left, center, or right (numbers usually read better right-aligned).
Copy the output as Markdown, or flip the toggle to HTML if the destination is a web page or CMS rather than a README.

The result is a GitHub Flavored Markdown table with padded columns, so the raw text stays readable in a code editor:

| Product   | Q1 Revenue | Growth |
|-----------|-----------:|-------:|
| Converter |    $12,400 |    18% |
| Generator |     $8,100 |    31% |

Everything happens in the browser. The cells you paste are parsed locally and never uploaded, which matters more for spreadsheets than for most documents: financial data, customer lists, and internal metrics are exactly the content you don't want passing through a stranger's server.

What Survives the Conversion (and What Doesn't)

Markdown tables are intentionally simpler than spreadsheets, so the conversion keeps the content but drops spreadsheet-specific machinery:

Spreadsheet feature	In Markdown
Cell text and numbers	Preserved exactly
Header row	Becomes the Markdown header
Column order	Preserved
Formulas	Only the computed value carries over: `=SUM(B2:B9)` pastes as its result
Cell formatting (colors, borders, fonts)	Dropped. Markdown tables have no styling syntax
Merged cells	Not supported. The value lands in one cell, the rest are empty
Multiple lines in a cell	Converted to `<br>`, which GitHub renders correctly

If you need merged cells or styling, generate the HTML output instead and edit the markup. Markdown's table syntax has no colspan or style attributes, and no generator can add what the format doesn't support. The Markdown table syntax guide covers these limits in detail.

The Three Fixes You'll Actually Need

1. Numbers columns look ragged. Spreadsheets right-align numbers automatically; Markdown defaults to left. After pasting, set numeric columns to right alignment. In the generated syntax that's a trailing colon in the separator row (---:), and it makes financial or metric tables dramatically easier to scan.

2. Pipe characters in cell content. A cell containing | would break the table's column structure. A good generator escapes them as \| automatically; if you're converting by hand, this is the first thing to check when a table renders with misplaced columns.

3. Thousands separators split cells in CSV. If you're importing a CSV file rather than pasting copied cells, values like 1,000 split into two columns because the comma is the delimiter. The fix is to copy the cells from the spreadsheet directly (tab-separated) instead of exporting to CSV first, one of several reasons paste-from-spreadsheet beats the export route.

When You Need More Than a Table

A table generator is the right tool when the table is the content: a comparison in a README, benchmark results in an issue, a pricing grid in documentation. When the table is embedded in a larger document, convert the whole document instead:

A full Word document with tables in it → Word to Markdown converter. Tables convert along with headings, lists, and links, as covered in the DOCX to Markdown guide.
A finished Markdown document going the other way, into a PDF → the Markdown to PDF converter renders GFM tables natively. If your tables have broken in PDF exports before, this guide explains why.
Markdown tables destined for a web page → the Markdown to HTML converter turns them into real <table> markup with thead and tbody.

Frequently Asked Questions

Q: How do I convert an Excel table to Markdown?

Select and copy the cells in Excel, then paste them into MDTool's free Markdown Table Generator using its "Paste from Excel / CSV" option. Excel copies cells as tab-separated text, so the grid rebuilds your rows and columns exactly, and you copy the result as a finished Markdown table.

Q: Does this work with Google Sheets?

Yes, identically. Google Sheets, LibreOffice Calc, and Apple Numbers all copy selected cells as tab-separated plain text, which is the format the importer reads.

Q: Do Excel formulas convert to Markdown?

No, only the computed values. The clipboard's plain-text version contains what the cell displays, not the formula behind it. A cell showing 42 from =A1*2 pastes as 42.

Q: Is my spreadsheet data uploaded when I convert it?

Not with MDTool. The paste import and table generation run entirely in your browser. The data never leaves your device, which you can verify by watching the Network tab in your browser's developer tools while converting.

Q: How do I keep merged cells from my spreadsheet?

Markdown tables can't represent merged cells. Switch the generator's output to HTML and add colspan/rowspan attributes by hand, or restructure the table so each cell holds its own value, usually the better option for READMEs.

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.

Migrating a CMS from HTML to Markdown: What Survives and What Breaks

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

Moving a site from a database-backed CMS to Markdown files sounds simple until you look at the HTML your old CMS has been storing: inline styles, page-builder divs, shortcodes, merged table cells. Some of it converts perfectly; some of it has no Markdown equivalent at all.

Here's what to expect before you migrate a content library, and the cleanup pass that saves you from fixing every page by hand.

Why Teams Migrate From HTML CMS to Markdown

Migrating away from an HTML-based CMS toward a Markdown workflow is one of the most common reasons people go looking for an HTML-to-Markdown converter. It's not because Markdown is trendy, but because the destination platforms specifically want it. Notion treats Markdown as its native import and export format. Ghost's post editor is Markdown-first under the hood, even though it renders HTML on the published page. Static site generators (Astro, Hugo, Jekyll, and others) build entire sites from Markdown (or MDX) files committed to a Git repository, with no database involved at all.

The draw is consistent across all of these destinations: content lives in version-controllable plain-text files instead of a database table, there's no plugin ecosystem to patch and maintain, and the files themselves are portable: a Markdown file isn't tied to one platform's theme CSS the way an HTML export can be.

The friction point is almost always the same, though: your existing content already exists as HTML, exported from WordPress, copied from a documentation site, or sitting in a CMS with no native Markdown export. That's the actual conversion this guide walks through.

What Converts Cleanly and What Does Not

Set honest expectations before you commit to converting an entire content library, because HTML is more expressive than Markdown and some things genuinely don't survive the trip.

Source HTML	Result	Notes
Headings, paragraphs, bold/italic	✅ Converts cleanly	Maps directly to Markdown syntax
Links and images	✅ Converts cleanly	`href`, `src`, and `alt` preserved as-is
Ordered/unordered lists, incl. nesting	✅ Converts cleanly	Indentation follows CommonMark rules
Straightforward GFM tables	✅ Converts cleanly	Simple row/column tables only
Fenced code blocks	✅ Converts cleanly	Language tag kept if source has `class="language-js"`
Inline styles, presentation-only `<span>`	❌ Dropped	No Markdown equivalent to preserve them in
`colspan`/`rowspan`, nested tables	⚠️ Flattened	GFM tables can't express merged cells
Embedded JS widgets, iframes, galleries	❌ Dropped	No Markdown representation exists
Expanded CMS shortcodes (e.g. WordPress galleries)	⚠️ Needs manual rebuild	Leaves div-based layout markup with no Markdown equivalent

If your source documents are actually Word files rather than HTML pages, the Word to Markdown converter handles that format directly rather than requiring an HTML export step first.

Step-by-Step Migration With MDTool

Get the HTML. Use View Source or Inspect Element on a live page, your CMS's HTML export feature, or a WordPress XML export converted to per-page HTML.
Convert. Paste the HTML into the HTML to Markdown converter, or upload the .html file directly via drag-and-drop.
Check the high-risk areas first. Tables and code blocks are where conversion most often needs a second pass, so verify those before trusting the rest of the page.
Save with the filename and structure your destination expects. Copy the Markdown or download it as .md. Note that MDTool converts body content only. Hugo, Jekyll, and Astro all expect YAML front matter (title, date, slug) at the top of the file, which you'll need to add separately since it isn't represented as visible page content in the source HTML.
Repeat per page. For a handful of pages, this paste-based workflow is the fastest path. For a migration spanning dozens or hundreds of pages, script the conversion against the underlying turndown library directly rather than pasting one page at a time. It's the same logic MDTool uses, but callable in a loop.

Cleaning Up the Output After Conversion

A few issues show up reliably enough across CMS migrations that it's worth checking for them specifically, the same way developers converting GitHub READMEs to PDF check badges and Mermaid diagrams before trusting a batch export:

Missing front matter. Every Markdown-based platform needs metadata MDTool doesn't generate, so add title, date, and slug fields manually or with a small script per platform.
Near-empty Markdown tables. Layout-only HTML tables from page-builder plugins sometimes convert into a pipe table with little real content, so delete these rather than trying to repair them.
Broken relative image paths. An image path that resolved correctly on the old CMS often won't resolve on the new platform's folder structure. Re-point these to wherever you're now hosting images; most static site generators expect them in a static/ or public/ folder.
Stray emphasis markers. HTML that applies bold via both a CSS class and a real <strong> tag can occasionally produce doubled-up ** characters. Proofread the first converted page closely before applying the same workflow across the rest of the migration.

Frequently Asked Questions

Q: Can MDTool migrate an entire WordPress site at once?

No. MDTool converts one page of HTML at a time, in your browser. For migrating an entire site, export each page's HTML, convert pages individually, or script the conversion against the underlying turndown library if you need to process many files programmatically.

Q: Does converted Markdown include front matter for Hugo or Jekyll?

No. MDTool converts the body content of the HTML (headings, text, tables, code), not metadata. You'll need to add YAML front matter (title, date, slug, tags) manually or with a separate script, since that data isn't represented as visible content in the source HTML.

Q: What happens to WordPress shortcodes during conversion?

Shortcode syntax itself ([gallery ids="1,2,3"]) is usually already expanded into plain HTML by the time you copy a rendered page, so the bracket syntax won't appear, but the resulting div-based layout markup has no Markdown equivalent and needs to be manually rebuilt using your new platform's image or component syntax.

Q: Can I convert HTML exported from Notion into Markdown for a different platform?

Notion already exports to Markdown natively, so for Notion content specifically you usually don't need an HTML-to-Markdown step at all. Reach for HTML conversion only when Markdown export isn't available for the specific content type you're working with.

Q: Does the converted Markdown work with MDX, for Astro or Gatsby?

Yes. Standard Markdown output is also valid MDX, since MDX is a superset of Markdown syntax. You may still need to manually convert any embedded interactive widgets into actual JSX components, since those have no Markdown representation to begin with.

Q: Will my page's CSS classes carry over?

No, and that's intentional. CSS classes are presentation, not content, and Markdown has no syntax to represent them. Your new platform applies its own styling to the converted Markdown.

Q: How do I handle internal links between migrated pages?

Links convert as-is, including their original href values. After migration, you'll likely need to update those hrefs to match your new platform's URL structure. That's a find-and-replace pass, not something the converter can infer automatically.

Q: Is it safe to convert pages with customer data or unpublished drafts?

Yes. MDTool's conversion runs entirely in your browser via JavaScript; nothing is uploaded to a server, so unpublished or sensitive content never leaves your device during conversion.

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.

Markdown to PDF Without Breaking Your Code Blocks

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

If you've exported technical docs from Markdown to PDF, you've probably seen it: code in a proportional font, no highlighting, lines running off the page, indentation gone. The prose comes through fine and the code, the part your readers actually need, doesn't.

Here's why that happens and how to get code blocks into a PDF intact.

How do you convert Markdown to PDF with syntax highlighting for code blocks?

Give every fenced code block a language tag (python `, `js), paste the Markdown into a converter that highlights code in the PDF itself, and download. In MDTool's Markdown to PDF converter that's three steps:

Paste your Markdown. Check that each code fence names its language.
Pick a theme: GitHub, Academic, Minimal or Dark. Each one has its own highlight palette, so keywords, strings, numbers and comments are colored differently in the PDF.
Click Download PDF. Code keeps its indentation and colors, Mermaid blocks (`mermaid) become real diagrams, and the whole conversion runs in your browser, so the code is never uploaded.

What you need	How MDTool handles it
Colored syntax	highlight.js tokens with a palette per theme
Languages	JavaScript, TypeScript, Python, Bash, CSS, HTML/XML, JSON, YAML, SQL, Rust, Go, Dart
Monospace font	Courier for code in standard Latin characters
Indentation	Leading spaces preserved
Long lines	Wrapped to the page instead of cut off
Diagrams	mermaid ` blocks rendered as diagrams
Selectable text	Yes: the PDF contains real text, not a screenshot
Page breaks	`<!-- pagebreak -->`, `\pagebreak`, `\newpage` or `<div class="page-break"></div>` on its own line

If you need this in a script or CI job instead, MDTool has no CLI; see Markdown to PDF with Python, Pandoc and Node for command-line options with highlighting.

Why Code Blocks Are the Hardest Part of Markdown to PDF Conversion

If you've ever tried to convert a Markdown file with code blocks into a PDF, you've almost certainly run into at least one of these problems:

Monospace font not used, so code renders in the same proportional font as body text
No syntax highlighting, so everything is plain black text
Lines overflow the page and get cut off
Indentation is lost, making code unreadable
Background color disappears, so code blocks look identical to normal paragraphs

These aren't random bugs. They happen because most tools take a shortcut: they parse Markdown into HTML, then dump it into a PDF renderer that ignores CSS entirely. Code blocks depend heavily on CSS (font-family: monospace, white-space: pre, overflow-x: auto, background colors), and when CSS is stripped out, code becomes unreadable.

What Broken Code Blocks Look Like

Here's a concrete example. Take this simple JavaScript function in a Markdown file:

```javascript
async function fetchUser(id) {
  const response = await fetch(`/api/users/${id}`);
  if (!response.ok) throw new Error("User not found");
  return response.json();
}
```

A broken PDF converter will output something like this in the PDF:

async function fetchUser(id) { const response = await fetch("/api/users/" + id); if (!response.ok) throw new Error("User not found"); return response.json(); }

No line breaks. No monospace. No background. Just a wall of text that's impossible to read.

A correct PDF converter preserves:

The monospace font (Courier, Fira Code, or similar)
Each line on its own line with proper indentation
A light gray or dark background that visually separates code from prose
Syntax-colored tokens (keywords, strings, functions) if it supports highlighting

The Real Code Example

Here's the full JavaScript snippet we'll use to test PDF output throughout this guide:

// Illustrative example: a minimal browser-side Markdown to PDF function.
// (Not MDTool's own code; MDTool builds a vector PDF with pdfmake instead.)
async function convertMarkdownToPDF(markdownContent) {
  // Parse Markdown into an HTML string
  const { marked } = await import("marked");
  const htmlContent = marked.parse(markdownContent);

  // Wrap in a styled document for proper PDF rendering
  const styledHTML = `
    <!DOCTYPE html>
    <html>
      <head>
        <style>
          body { font-family: Georgia, serif; line-height: 1.6; }
          pre  { background: #f4f4f4; padding: 1rem; border-radius: 4px; overflow-x: auto; }
          code { font-family: 'Courier New', monospace; font-size: 0.9em; }
        </style>
      </head>
      <body>${htmlContent}</body>
    </html>
  `;

  // Use html2pdf.js (browser only - never run server-side)
  const html2pdf = (await import("html2pdf.js")).default;
  return html2pdf()
    .set({ margin: 10, filename: "output.pdf", html2canvas: { scale: 2 } })
    .from(styledHTML)
    .save();
}

Notice the three things that make this work: the <pre> element gets a background and padding, code gets a monospace font, and html2pdf.js is imported dynamically so it only ever runs in the browser, never on the server where window is undefined.

The catch with this approach is that html2pdf.js takes a picture of the page with html2canvas. The code in the PDF is an image: you can't select or search it, and it blurs when you zoom. That's why MDTool switched to pdfmake, which writes the code into the PDF as real text, with the highlight colors applied to each token.

Step-by-Step: Convert Markdown with Code Blocks to PDF

Step 1: Paste Your Markdown

Open a converter that highlights code in the PDF itself, such as MDTool's Markdown to PDF, and paste your Markdown. Your code blocks should be fenced with triple backticks and include a language identifier:

```javascript
// your code here
```

Language identifiers like javascript, python, bash, typescript, and json enable syntax highlighting. Without one, the converter tries to guess the language, which works for common code but is less reliable, so tag your fences.

Step 2: Check the Live Preview

The preview panel renders your Markdown in real time. Before downloading, verify that:

Code blocks have a distinct background
Indentation is preserved (4-space indents should look like 4 spaces, not 1)
Long lines wrap correctly or have a horizontal scrollbar hint

If the preview looks right, the PDF will match, because the converter uses the same rendered HTML for both.

Step 3: Choose a Theme (Optional)

Light themes (GitHub, Academic, Minimal) work best for printed PDFs because they use dark text on a white or light-gray code background, exactly what you'd expect on paper. Dark themes look great on screen but can waste toner and reduce readability when physically printed.

Step 4: Download the PDF

Click Download PDF. The conversion happens entirely in your browser using pdfmake, so your Markdown never leaves your machine, and no server processes it.

Tip: For technical documentation, use the GitHub theme. It matches the code block style developers already recognize from GitHub READMEs.

Common Problems and Fixes

Problem: Code lines are cut off at the right edge of the page
Fix: Make sure your code lines are under ~80 to 90 characters. The converter wraps very long lines, but it can't reformat code logic. Break long lines manually before converting.

Problem: Syntax highlighting doesn't appear
Fix: Add a language tag after the opening triple backtick. js ` instead of just `.

Problem: Indentation collapses to a single space
Fix: Use spaces, not tabs. Some PDF renderers collapse tab characters. Replace tabs with 2 or 4 spaces.

Problem: Code block background is hard to see when printed
Fix: Every theme gives code blocks a tinted background and a border, but the light themes use a very pale gray that some printers barely show. Academic has the darkest code border of the light themes. For on-screen reading, the Dark theme gives the strongest contrast.

Problem: A Mermaid diagram shows up as code
Fix: The fence must be tagged exactly `mermaid. If the diagram has a syntax error, the block stays as code; check the live preview, which shows the same result the PDF will.

How MDTool Handles Code Blocks Differently

Most online Markdown-to-PDF converters run on the server: they accept your Markdown, process it with a headless browser or a PDF library, and return a file. The problem is CSS support in these pipelines is inconsistent, especially for code blocks.

MDTool takes a different approach. The entire conversion runs client-side in your browser using pdfmake. This means:

Real text, not a screenshot: code in the PDF is selectable, searchable and sharp at any zoom
No data sent to a server: your code stays on your machine
Consistent output: the preview and the PDF come from the same rendered HTML, with highlight colors carried into the PDF and Mermaid diagrams drawn before the PDF is built

This is especially important for code blocks, which depend on whitespace, a monospace font and per-token colors that many converters discard.

For GitHub READMEs specifically, check out our guide on converting GitHub READMEs to PDF. It covers badge handling and image-heavy READMEs alongside code blocks. If you need a refresher on fenced code block syntax itself, see the Markdown cheatsheet.

Frequently Asked Questions

Q: Does MDTool support syntax highlighting for all programming languages?

It supports JavaScript, TypeScript, Python, Bash, JSON, YAML, HTML/XML, CSS, SQL, Go, Rust and Dart. The underlying parser uses marked with highlight.js for token coloring. If your language isn't highlighted, formatting (monospace font, background, indentation) is still preserved, and only color tokens are skipped.

Q: Will the code block look the same in the PDF as in the preview?

Very close. The PDF is built from the same rendered HTML you see in the preview, with the same token colors, indentation and diagrams. Fonts can differ slightly: code uses Courier in the PDF, and long lines wrap to fit the page.

Q: Can I convert a file with hundreds of lines of code?

Yes. Because the PDF is built as text rather than as an image, long files stay small and sharp. Very large documents take longer to build in the browser, so for files with thousands of lines of code, split them into sections or use page breaks to keep each section readable.

Q: My code has backticks inside the code block. How do I escape them?

Use four backticks to open and close the fenced block instead of three. This allows triple backticks inside the block without escaping.

Q: Is there a file size limit?

There's no server-side limit because conversion happens in your browser. The practical limit is your device's RAM, and most modern machines handle Markdown files up to several megabytes without issue.

Q: Can I use MDTool for confidential code?

Yes. Because conversion is entirely client-side, your code is never transmitted to any server. You can use it for proprietary or sensitive code with confidence.

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.

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?