Engineering teams write documentation in GitHub-flavored Markdown, but not everyone downstream lives in GitHub. Auditors, clients, and non-technical stakeholders often need the same content as a Word document — something they can comment on, redline, or attach to a compliance package.
Copy-pasting a rendered README from GitHub's web view into Word usually goes wrong: tables collapse, code blocks lose their formatting, and badge images (the little build-status icons at the top of most READMEs) either disappear or paste as broken links.
Step 1: Get the raw Markdown, not the rendered page
Don't copy from the GitHub web preview. Instead, go to the raw file:
- Open the README on GitHub.
- Click the file name, then click Raw (or add
?plain=1to the URL to view the source directly). - Select all and copy the raw Markdown text — this preserves the actual
##headings, ``` code fences, and table syntax instead of GitHub's rendered HTML.
Step 2: Convert with a GitHub-flavored Markdown converter
GitHub READMEs use GFM (GitHub Flavored Markdown) — this includes tables, task lists (- [x]), strikethrough, and autolinks, which aren't part of standard Markdown. Use a converter that explicitly supports GFM syntax:
- Open the Markdown to Word converter (or the dedicated GitHub Markdown to Word page).
- Paste the raw README content.
- Check the preview: task list checkboxes, tables, and fenced code blocks should all render correctly.
- Click Convert to Word to download the .docx.
Handling badges and shields
Most READMEs start with a row of badge images (build status, license, npm version) written as Markdown image syntax pointing to shields.io or similar services:
These convert as regular images. In a Word document, a row of small badge icons at the top rarely looks intentional — consider deleting the badge row before converting, or moving it to an appendix, since it adds visual noise without meaning to a reader outside GitHub.
Handling Mermaid diagrams in READMEs
Many modern READMEs include architecture diagrams as ```mermaid code blocks, since GitHub renders Mermaid natively in its web UI. A plain-text paste turns these into unreadable code. Use a converter with Mermaid support (like the one above) so the diagram renders as an actual image in the Word file, not raw diagram syntax.
What usually needs cleanup after converting
- Relative links (e.g.
](./docs/setup.md)) — these point to files in the repository and won't resolve outside it. Either convert them to absolute GitHub URLs first, or note in the Word doc that they're repo-relative. - Collapsible sections (
<details><summary>) — GitHub supports HTML-based collapsible blocks; these convert as plain expanded text since Word has no equivalent collapse behavior. - Table of contents links (
[Installation](#installation)) — these anchor links won't jump to headings in Word the way they do on GitHub. Word's own automatic Table of Contents feature (Insert → Table of Contents, generated from heading styles) is a better replacement once the document is converted.
Frequently asked questions
Does this work with GitLab or Bitbucket READMEs too? Yes — GitLab and Bitbucket both use GFM-compatible Markdown, so the same raw-text-then-convert workflow applies.
Will the converted document keep GitHub's heading styles? Headings convert to native Word heading styles (Heading 1, Heading 2, etc.), which means Word's built-in navigation pane and auto-generated table of contents work immediately.
Is there a size limit? No practical limit for a typical README — even long documentation files with dozens of sections convert in a few seconds since everything runs in your browser.
Convert your Markdown to Word now
Tables, Mermaid diagrams, and LaTeX math — all preserved. Free, no sign-up, runs in your browser.
Open the converter