Word to Markdown for GitHub READMEs and docs repos

Product and eng teams still draft specs, runbooks, and partner guides in Word. GitHub, Docs-as-Code sites, and most static doc generators want Markdown files in a repo. A .docx attachment in an issue is not a README. The practical path is word to markdown: convert the draft, fix headings and lists in a plain editor, preview on GitHub, then open a PR reviewers can comment on line by line. Use Word to Markdown when the source is .docx. Use PDF to Markdown when someone only sent a PDF export. This guide covers the GitHub and docs-repo loop, including cleanup and review habits, not Obsidian vaults.

Why Word drafts fight GitHub and docs sites

GitHub renders .md in the browser. Docs sites built on MkDocs, Docusaurus, VitePress, or Sphinx-with-MyST expect the same plain-text shape. Word files need a download, a desktop app, and a reviewer who owns a license. Diffs on binary Office files are opaque. Review comments land in email threads instead of line comments on a PR.

Teams keep writing in Word because legal templates, tracked changes, and “send as attachment” habits are sticky. That is fine for the first draft. Shipping that draft as the source of truth in the repo is the mistake. Maintainers then paste screenshots of Word into issues, or they commit a stale PDF next to an empty README.

Markdown in git gives you blame, PR review, and a single URL for the latest text. Contributors edit in any editor. CI can lint broken links. Search indexes the same files humans read. The conversion step is how you stop treating Word as the permanent home for docs that already belong in the repo.

If your goal is a personal notes vault rather than a public or internal docs repo, stop here and follow Import PDFs into Obsidian as Markdown. That article owns the vault workflow. This one stays on README, /docs, and PR review.

What Markdown must look like for a README or docs PR

Good docs Markdown is boring on purpose. One # title. Real ## sections. Lists that use - or 1. instead of fake bullets made of emoji and tabs. Links written as [label](url). Tables as pipe tables when the grid is small enough to maintain by hand.

GitHub Flavored Markdown accepts fenced code blocks, task lists, and most of the syntax you already use in issues. Docs frameworks add frontmatter for titles and sidebar order. Keep frontmatter short: title, description, maybe sidebar_position. Do not invent a schema nobody on the team will fill in.

Name files for the repo, not for Word. Prefer getting-started.md over Document1.md or Final_v7_REAL.docx leftovers. Put images in an assets/ or static/ folder your site already uses. Relative links beat absolute intranet paths that die outside the office network.

README vs long-form docs pages

A README is a front door: what the project is, how to install, where to go next. Keep it short. Move tutorials into /docs. After word to markdown, split a 40-page Word handbook into several .md files instead of one giant README that nobody scrolls.

Long docs pages need stable section headings so deep links work (#authentication). Fix heading levels before you merge. A wall of bold paragraphs from Word looks fine in Word and awful in GitHub preview.

What reviewers check in the first pass

Reviewers skim the rendered preview, not only the diff. They look for a clear title, working install steps, and lists that still read as lists. Broken numbering and heading levels that skip from # to #### are the usual rejection reasons after a first conversion.

Ask for one review focused on structure before you polish tone. Structure bugs are cheap to fix in Markdown and expensive to argue about in a Word comment balloon that never reached the repo.

Prepare the Word file before you convert

Garbage styles survive conversion. Ten minutes in Word saves a longer cleanup in the .md.

Use real Heading 1 / Heading 2 styles. Bold body text is not a heading. Prefer .docx over legacy .doc. Remove password protection. Delete cover pages that only hold a logo. Strip tracked-change leftovers if your process allows accepting all changes first; mixed revision markup confuses extractors.

Redact secrets before any upload: API keys, customer names under NDA, salary tables, private URLs. Conversion copies what it can read. If the file is too sensitive for a browser upload, convert offline with Pandoc or MarkItDown on your machine and skip the public tool.

Split monster handbooks by chapter while still in Word, or plan to split the Markdown after. One 200-page dump becomes an unreviewable PR. Match the split to the docs sidebar you already want.

Walkthrough: Word to Markdown for a README or docs page

You need four artifacts: the original .docx (archive), a cleaned .md, any images in the right folder, and a PR against the docs branch. Skip any of those and you either lose the source trail or merge text nobody can preview.

Work one representative chapter first. Time convert plus cleanup. Only then batch the rest. Scaling a broken outline into twenty files wastes a week of review.

Keep the branch small. One README or one docs section per PR beats a dump of every Word export from the shared drive. Reviewers finish faster when the diff matches a single job.

Convert and download the Markdown

Open Word to Markdown. Upload the prepared .docx under the size limit. Download the .md. Open it in VS Code, Cursor, or any plain editor. Confirm the document title is a single # line. Promote true sections to ##. Demote running headers the converter treated as headings.

Scan lists immediately. Nested bullets from Word often flatten or pick up extra blank lines. Fix the first procedure you care about before you touch tone. Save the file under the docs naming rule.

Place the file in the repo and preview

Copy the .md into README.md or docs/... on a branch. Add images with relative paths. Commit. Open the file on GitHub and use the Preview tab, or run the local docs site if your project has one.

Click every new link once. Check that code fences closed. If the page uses MDX or a strict linter, run that linter before you request review. Conversion does not know your repo’s remark plugins.

Fix lists, headings, and tables that break in preview

Conversion is a draft. The failure modes that kill docs PRs are predictable.

Headings: fake headings stay as bold paragraphs. Add # markers. Skip levels confuse some sidebars. Keep a strict outline.

Lists: Word’s multi-level lists may become paragraphs with leading tabs, or numbered lists that restart at 1. every item. Rebuild the procedure as Markdown lists by hand when the structure matters for on-call steps. Nested lists need consistent indent of two or four spaces; pick one style and stick to it in the repo.

Tables: wide Word tables become unreadable pipe tables. Split columns, turn the grid into definition lists, or link out to a spreadsheet in assets/ when the table is data, not prose. Merged cells rarely survive. Rebuild the rows you need for the docs page and leave the rest in the archived Word file.

Images: you may get empty placeholders or broken media paths. Export figures from Word manually if needed, compress them, and write ![alt](path) with meaningful alt text. Decorative covers can go.

A later article in this wave digs deeper into list fidelity for DOCX. Here, fix what the PR needs and move on.

A short cleanup checklist

1. One # title; sections at ## / ###.
2. Procedures are real lists.
3. Code samples sit in fenced blocks with a language tag when you know it.
4. Links resolve on the preview.
5. No “Page 3 of 12” or confidential footers in the body.
6. Frontmatter matches sibling pages in /docs.

Run that list before you @ a reviewer. Most “conversion looks bad” complaints are checklist skips.

The PR and docs review loop

Treat docs like code. Branch, convert, clean, preview, then open a PR with a short summary: what changed, which Word source you used, what you still owe (diagrams, legal sign-off).

Ask reviewers to use GitHub’s rendered view. Comment on lines. Prefer follow-up commits over rewriting the Word file and converting again from scratch, unless legal insists the .docx stays canonical. If Word must stay canonical, name an owner and a re-convert cadence so the Markdown copy does not rot.

For partner-facing guides, run one non-engineer through the install section after merge. Markdown that engineers like can still hide a missing prerequisite that Word’s narrative prose had buried in a sidebar text box.

When the same handbook also feeds a search index or assistant, clean structure once and reuse it. See Prepare documents for RAG with Markdown and Building a knowledge base for a local AI from PDFs and Word for the retrieval path after the repo copy is stable.

Related jobs: PDF sources, offline tools, and notes apps

Not every “Word doc” arrives as .docx. People print to PDF, email scans, or paste from Google Docs. Route by format.

PDF-only packets belong on PDF to Markdown. Mixed folders can use Convert to Markdown. Google Docs users should export .docx first if you want this Word path, or use a Docs-specific export; do not assume a screenshot PDF will keep headings.

Offline conversion fits private corpora. Pandoc (pandoc file.docx -o file.md) and Microsoft’s MarkItDown CLI both run on your machine. Online tools win for one-off public READMEs under size caps. Choose offline when the file contains secrets you refuse to upload. Privacy habits for browser uploads sit in Is it safe to upload documents online?.

Notes apps are a different destination. Obsidian readers should use the vault guide linked above. This article’s success metric is a mergeable docs PR, not a graph view.

Privacy, limits, and when not to convert online

Upload only files you are allowed to process in a third-party tool. Strip credentials first. Prefer a redacted excerpt when you only need one chapter online.

Toolsy processes the file for the conversion response, then drops the upload on the usual retention window described in the privacy policy. Free tiers cap daily files and size; large handbooks may need splitting or a Pro plan. None of that replaces your own compliance rules.

Do not upload: medical charts with identifiers, unreleased security advisories, customer contracts you have not sanitized, or password lists. Convert those on a locked-down machine. Keep the Markdown private until legal clears publication.

If the docs must stay inside a VPC, wire a local CLI into your pipeline and keep the browser tool for non-sensitive drafts only.

Frequently asked questions

How do I convert Word to Markdown for a GitHub README?

Save the draft as .docx, remove secrets, and use real heading styles. Upload it to Word to Markdown, download the .md, and rename it to README.md or place it under docs/. Fix headings and lists in a plain editor, push a branch, and check GitHub’s Preview before you request review.

Is docx to markdown the same as word to markdown?

For modern Word files, yes: .docx is the format people mean when they say word to markdown. Legacy .doc is less reliable; reopen and save as .docx first. The secondary search phrase “docx to markdown” points at the same job on Word to Markdown.

Can I paste Word into a GitHub issue instead of converting?

You can paste, but you lose durable docs, blame, and site generation. Issue text ages badly and does not feed MkDocs or Docusaurus. Convert once into a tracked .md when the content should outlive the thread.

What breaks most often after Word to Markdown?

Fake headings, nested lists, merged-cell tables, and images with missing files. Footers and page numbers also leak into body text. Budget a cleanup pass; do not merge the raw download without Preview.

Should I use Pandoc instead of an online converter?

Use Pandoc or another local CLI when the file is private, huge, or part of a scripted pipeline. Use an online converter for small public drafts when policy allows upload. Many teams use both: browser for a first pass, Pandoc in CI later.

How do I keep Word as the legal source and Markdown in git?

Name Word canonical in writing, store it outside or beside the repo, and schedule re-converts after each signed revision. Put cleanup rules in a short checklist so each re-convert does not invent new heading styles. Without an owner, the Markdown copy drifts.

What if I only have a PDF of the Word doc?

Convert with PDF to Markdown and expect more cleanup than a native .docx. If anyone still has the Word file, use that instead. Print-to-PDF adds layout noise you will undo by hand.

Does this replace importing documents into Obsidian?

No. Obsidian vaults need a notes-first import path covered in Import PDFs into Obsidian as Markdown. You can reuse the same .md in a vault later, but GitHub docs review is a different workflow and a different success check.

Is it safe to upload a company Word file for conversion?

Only if policy allows and you redacted secrets. Read Is it safe to upload documents online? and the privacy policy. When in doubt, convert offline and keep the draft on hardware you control.

How do I turn converted docs into a knowledge base or RAG corpus?

Merge clean Markdown into the repo first so humans agree on the text. Then point your indexer at that tree. For company RAG pipelines see Prepare documents for RAG with Markdown. For a local assistant folder see Building a knowledge base for a local AI from PDFs and Word.

For the convert step itself, start at Word to Markdown. When the only copy is PDF, use PDF to Markdown. Ship the README or docs page through Preview and a normal PR so the next editor never needs the original Word file to fix a typo.