Markdown to Word · GitHub
GitHub README to Word
Paste a README.md and download a real .docx for the grant application, the proposal appendix, or the client who will not open a link. The parts a README leans on that Markdown does not own — badges, centred HTML, relative paths — are the parts worth knowing about first.
- Badge rows become [image: …] placeholders unless you fetch remote images.
- Inline HTML is escaped, so <p align="center"> shows up as text in Word.
- Anchor links to your own headings become real, clickable Word bookmarks.
Quarterly Update
Paste anything here — this text is a placeholder. Nothing you type is uploaded.
What shipped
| Workstream | Owner | Status |
|---|---|---|
| Billing migration | Ada | Done |
| Search reindex | Grace | In progress |
| Mobile onboarding | Alan | Blocked |
Bold, italic, struck through and inline code all carry over into
Word as real formatting, not as literal characters.
Next two weeks
Blockquotes become indented quote paragraphs.
export function total(items: readonly number[]): number {
return items.reduce((sum, n) => sum + n, 0);
}
Footnotes become real Word footnotes.[1]
Maths (turn on “Equations”)
Inline , and a display equation:
Diagram (turn on “Diagrams”)
flowchart LR
A[Markdown] --> B[Parse]
B --> C[Render]
C --> D[.docx]
Numbered and positioned by Word itself, so they renumber when you edit. ↩︎
Word theme
Checking clipboard support…
The Markdown → OOXML converter behind this page is an open-source library called downword.
A README-shaped document to try
Copy this into the editor above and convert it. It is deliberately full of the things that only READMEs do: a centred HTML logo block, two shields.io badges, an emoji shortcode in the title, a hand-written contents list, a relative link, a <details> section and a task list. Convert it once and read the notes panel — every line in there corresponds to a row in the table below.
<p align="center"> <img src="assets/logo.png" width="120" alt=""> </p> # ledger-cli :rocket:  [](LICENSE) A tiny double-entry ledger for the terminal. ## Contents - [Install](#install) - [Roadmap](#roadmap) ## Install ```bash npm install -g ledger-cli ``` See [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request. <details> <summary>Advanced flags</summary> - `--strict` fails on unbalanced entries - `--json` prints machine-readable output </details> ## Roadmap - [x] CSV import - [ ] Multi-currency
What a README turns into
A README is the least “pure Markdown” document most people own, because GitHub renders things CommonMark never defined. This is what each of them does here.
| In the source | In the .docx | Verdict |
|---|---|---|
| shields.io badges | An [image: …] placeholder per badge, using the alt text — or the full URL when the badge has no alt, which is most of the time. Turn on Fetch remote images to embed them for real. | Fix it first |
| <p align="center"> | Literal text. Raw HTML is escaped rather than interpreted, so the opening and closing tags both appear in Word as characters. | Fix it first |
| <details> / <summary> | The tags become visible text and the contents become ordinary paragraphs. Nothing stays collapsed — Word has no equivalent. | Fix it first |
| Relative images | An [image: …] placeholder, with or without the remote-images toggle: the Worker has no base URL to resolve a repo-relative path against. | Fix it first |
| Relative links | A hyperlink that keeps its relative target, so it resolves to nothing once the file leaves your machine. Rewrite to the full github.com URL first. | Check it |
| [Install](#install) | A real internal Word hyperlink pointing at a bookmark on that heading — click it in Word and the document jumps. Anchors that match no heading become plain text and a note. | Carries over |
| :rocket: shortcodes | The literal characters. Shortcodes are a GitHub feature, not Markdown. The preview renders them as emoji, so this one is easy to miss. | Fix it first |
| Fenced code blocks | A shaded monospace block, one paragraph per line, no syntax colours — the converter is passed no highlighter, so Word gets the code and not the palette. | Carries over |
| Task lists | Real Word checkbox bullets, ticked and unticked as written. | Carries over |
| ```mermaid fences | A picture in the .docx with the Diagrams toggle on; a plain code block with it off. | Carries over |
The badge block is the first thing to deal with
Almost every README opens with a row of shields.io badges, and they are the first thing you will notice missing. Badges are remote images, and fetching remote images is off by default — that toggle is the only thing on this page that would send any part of your document to another server, so it starts off. Each badge therefore becomes a placeholder in the Word file: the literal text [image: …]with the badge's alt text inside. Badge Markdown very often carries no alt text at all, and when the alt is empty the placeholder falls back to the URL, so what you get is a paragraph reading [image: https://img.shields.io/badge/build-passing-brightgreen] where the badge row used to be. There are three sensible responses: delete the badge block before converting, which is usually right because a build badge means nothing inside a Word document; turn on Fetch remote images and let your browser pull them; or leave the placeholders and delete them in Word. Whichever you pick, every skipped image is named in the notes panel afterwards, so nothing disappears quietly.
READMEs are half HTML, and HTML is escaped
GitHub renders inline HTML, so README authors use it constantly: <p align="center"> around a logo, <img src="…" width="200"> for a screenshot sized just so, <h1 align="center"> for the project name, <details> and <summary> for a collapsible FAQ. This converter escapes raw HTML rather than interpreting it. That is a deliberate choice — interpreting arbitrary HTML out of a pasted document is how converters grow security holes — but it means those tags arrive in Word as visible text. You will see <p align="center"> sitting on its own line above your logo placeholder, and </details> closing a section that is no longer collapsed. The preview above will not warn you, because a preview is a browser and browsers render HTML. Before converting, search the editor for < and unwrap whatever you find: a centred <h1 align="center">Name</h1> becomes # Name, and the <details> wrapper simply goes, keeping its contents.
Relative paths cannot resolve from a browser tab
A README's links and images are written relative to the repository: ./CONTRIBUTING.md, docs/api.md, assets/screenshot.png. Those work on github.com because GitHub resolves them against the repo. Here there is nothing to resolve them against — the conversion runs inside a Web Worker, which has no page and therefore no base URL — so a relative image never loads, with or without the remote-images toggle, and becomes an [image: …] placeholder with a line in the diagnostics panel. Relative links keep their relative target, which means a reader who clicks ./CONTRIBUTING.md in Word gets nothing useful. If the Word file is going to travel, rewrite both to absolute URLs first: the full https://github.com/owner/repo/blob/main/CONTRIBUTING.md for links, and for images the raw.githubusercontent.com URL, which is a remote image and so needs the toggle on. If the file is not going to travel, deleting them is quicker.
Anchor links to your own headings actually work
One thing survives better than you would expect: the hand-written contents list near the top of a long README. Every heading becomes a real Word heading with a bookmark attached, and a link like [Installation](#installation)is written as an internal Word hyperlink pointing at that bookmark — click it in Word and the document jumps to the section, exactly as it does on GitHub. Anchors that match no heading in the document are reported in the notes panel as unresolved and rendered as plain text rather than as a link that goes nowhere. No automatic table-of-contents field is inserted by the converter; because the headings are genuine Heading 1 to Heading 6 styles rather than bold text, Word's References → Table of Contents builds one properly in a click, and Word will keep it updated afterwards.
Code, shortcodes, and the rest of the GitHub layer
A README is mostly code blocks, and they come across as a shaded monospace block, one paragraph per line, with no syntax colouring — the converter is handed no highlighter, so Word gets the code and not the editor's palette. The language tag on the fence is read and then has nothing to do. GitHub's emoji shortcodes are the other GitHub-only layer worth knowing about: :rocket: is not Markdown, it is a GitHub feature, so it stays as those nine characters in the Word file. The preview above renders them as emoji, which makes this one easy to miss. Hard-wrapped paragraphs are fine — single newlines collapse to spaces, so a README wrapped at eighty columns reflows into proper paragraphs rather than a column of short lines. Task lists in a roadmap section become real checkbox bullets, and Mermaid diagrams, which GitHub now renders natively, become pictures with the Diagrams toggle on.
What a converted README is actually for
Converting a README to Word is rarely about the README. It is about a grant application that wants the technical approach as a .docx, a client who will not open a link, a compliance pack that has to be one document, or an appendix in a proposal. For those, the GitHub theme is the closest match to what a technical reader expects — Segoe UI, tighter spacing — and the Academic theme, Times New Roman at 12pt with 1.5 line spacing, is the one to pick when the document is going into a submission with formatting rules. Nothing you paste is uploaded: the parser and the .docx writer both run in this tab, and with remote images off the converter makes no network requests at all.
Turning a README.md into a Word document
Paste a GitHub README, deal with the badges and the inline HTML, and download a Word .docx whose headings are real Word styles and whose anchor links are real bookmarks.
Get the raw Markdown
Open README.md on GitHub and press the Raw button, or copy the file out of your checkout. Copying from the rendered README page gives you HTML, not Markdown.
Paste or drop it in
Paste into the editor on this page, or drop the .md file onto the drop zone. The file is read in your browser; there is no upload step.
Deal with the badges and the HTML
Delete the badge row unless you want it, and search for '<' to unwrap any centred headers or <details> sections. Both would otherwise appear as literal text in Word.
Make the paths absolute
Rewrite relative links to their full github.com URLs and relative images to raw.githubusercontent.com, then turn on Fetch remote images if you want the pictures embedded.
Pick a theme and download
GitHub for technical readers, Academic for a formal submission. Press Download .docx, then read the notes panel — it names every image and anchor the converter could not resolve.
Insert a table of contents in Word
The converter emits no TOC field, but the headings are real Heading 1–6 styles, so References → Table of Contents builds one and keeps it updated.
README to Word: common questions
Why did my README badges turn into text?
Badges are remote images, and fetching remote images is off by default — that toggle is the only thing on this page that would send any part of your document to another server. Each badge therefore becomes a placeholder reading [image: …] with the badge's alt text inside. Badge Markdown usually has no alt text at all, and when the alt is empty the placeholder falls back to the URL, so you get a line of [image: https://img.shields.io/…] where the badge row was. Delete the badge block before converting, or turn Fetch remote images on and let your browser pull them.
Why is HTML like <p align="center"> showing up in my Word document?
GitHub renders inline HTML, so README authors use it constantly for centred logos, sized screenshots and collapsible sections. This converter escapes raw HTML rather than interpreting it — interpreting arbitrary HTML out of a pasted document is how converters grow security holes — so those tags arrive in Word as visible text. Search the editor for '<' and unwrap what you find: replace <h1 align="center">Name</h1> with # Name, and delete <details> and <summary> wrappers while keeping their contents. The live preview will not warn you, because a preview is a browser and browsers render HTML.
Do relative links and images from a README work?
No, and no toggle changes that. A README's paths are written relative to the repository — ./CONTRIBUTING.md, docs/api.md, assets/screenshot.png — and GitHub resolves them against the repo. The conversion here runs inside a Web Worker, which has no page and therefore no base URL to resolve them against, so a relative image can never load and becomes an [image: …] placeholder with a line in the notes panel. Rewrite links to their full https://github.com/owner/repo/blob/main/… form and images to their raw.githubusercontent.com URL before converting, and turn on Fetch remote images for the pictures.
Does a README's table of contents still work in Word?
Yes, better than you would expect. Every heading becomes a real Word heading with a bookmark on it, and a hand-written link like [Installation](#installation) is written as an internal Word hyperlink pointing at that bookmark — clicking it in Word jumps to the section. Anchors that match no heading are reported in the notes panel as unresolved and rendered as plain text rather than as a dead link. No automatic table-of-contents field is inserted, but because the headings are genuine Heading 1–6 styles, Word's References → Table of Contents builds one in a click.
Why is :rocket: not an emoji in the Word file?
Emoji shortcodes are a GitHub feature, not Markdown, so :rocket: stays as those nine characters in the .docx. The live preview on this page does render them as emoji, which makes this an easy one to miss — one more reason to trust the notes panel and a scroll through the finished document over the preview alone. Paste the actual emoji character into the editor instead if you want it in the Word file.
Do Mermaid diagrams in a README convert?
Yes, with the Diagrams toggle on. GitHub renders ```mermaid fences natively and plenty of READMEs now use them for architecture and flow diagrams; each fence becomes a picture in the .docx. Mermaid needs a real DOM to measure text and a canvas to rasterise, so that one pass runs on the page rather than in the Worker, and the engine loads only the first time you use it. Anything Mermaid cannot draw stays a code block and is listed in the notes panel. With the toggle off, diagram fences stay code blocks.
Converting from somewhere else?
- ChatGPT answers to WordNumbered steps with code in them, wide comparison tables, and answers that open at Heading 3.
- Notion export to WordMarkdown & CSV exports, databases that left as separate files, and three heading levels.
- Markdown to Word, generallyThe converter without a source-specific guide around it.
- Markdown to PDFThe same Markdown, with page-break control, when the answer needs to be a PDF.
Related tools
This free tool is built and maintained by KSPR Technologies. We build web, mobile & AI products for clients.