Printdown
EN

Turn a Word document into a GitHub README

Documentation often starts life in Word: a spec written by a product manager, installation notes from a client, a report that now needs to live next to the code. On GitHub, the natural home for that text is a README.md file, which the site renders on the repository’s front page. Retyping it is slow and error-prone. Converting it takes a minute, and a few targeted fixes make the result read like it was written for GitHub from the start.

1. Prepare the Word document

The converter maps Word’s structure to Markdown, so a well-structured document converts cleanly. Before converting, spend two minutes on these points:

  • Use heading styles (Heading 1, Heading 2…) instead of large bold text. They become # and ## headings, and GitHub uses them to build the outline of the file.
  • Use real lists (the bullet and numbering buttons), not dashes typed by hand.
  • Keep tables simple. Markdown tables cannot merge cells; a merged cell keeps its text in the first column.
  • Give images alt text (right-click → Edit Alt Text). It becomes the image description in Markdown.

2. Convert to Markdown

Open the Word to Markdown converter and drop your .docx (older .doc files work too). The file is converted in your browser; nothing is uploaded, which is useful for internal documents.

If the document has pictures, turn on Include images before converting and use Download .zip. The zip contains the Markdown file and an images/ folder, and the Markdown already points to images/image-1.png and so on. Without that option, each picture is replaced by its alt text.

Rename the Markdown file to README.md and put it, together with the images/ folder, at the root of the repository. GitHub resolves relative image paths, so the pictures will show on the repository page.

3. Polish it for GitHub

The conversion keeps your text, headings, emphasis, lists, tables, links and footnotes. What it cannot guess is intent: Word has no concept of a code block, and prose written for print does not always suit a README. Go through these fixes:

  • One title. Keep a single # heading with the project name at the top and make everything else ## or lower.
  • Code blocks. Wrap commands and code samples in fenced blocks with a language, so GitHub highlights them: 
    ```bash
npm install
npm run dev
```
  • Straight quotes in code. Word replaces " and ' with typographic quotes (“ ” ‘ ’) and hyphens with dashes. Inside commands and code they break copy-paste, so replace them.
  • Inline code for file names, commands and settings: `config.yml`, `--verbose`.
  • Relative links. Point to other files in the repository with paths like [Contributing](CONTRIBUTING.md) instead of absolute URLs, so links keep working in forks and branches.
  • No manual table of contents. GitHub adds an outline menu for every Markdown file, generated from your headings. A numbered “Contents” list copied from Word will get out of date; remove it.
  • Diagrams and math. GitHub renders mermaid code blocks as diagrams and LaTeX between $ signs as math, so you can replace screenshots of simple flowcharts with a Mermaid block that is easier to maintain.

A README structure that works

If the original document was not written as a README, reorganize it around what a visitor needs first:

  1. Project name and a one-sentence description.
  2. A screenshot or short example, if it helps.
  3. Installation and quick start.
  4. Usage and configuration.
  5. How to contribute, license and contact.

Long specifications can move to a docs/ folder and be linked from the README.

4. Preview and commit

Paste the README into the Markdown editor to check headings, tables and code blocks in the preview. Images from the images/ folder will not show there, because a web page cannot read files from your disk, but they will on GitHub. When it looks right:

git add README.md images/
git commit -m "Add README"
git push

Bonus: the same Markdown can go the other way. From the editor, Download PDF gives you a polished PDF of the README for people who prefer a document to a repository. The Markdown guide lists every element the editor supports.

More guides