Convert Word documents for GitHub

From Word file to repository

1. Convert the .docx file

   Upload a modern DOCX file in the home page converter. The file is read locally in your browser and is not sent to a server.

2. Review the Markdown preview

   Check heading levels, nested lists and ordinary tables. Use the source tab to edit wording or Markdown syntax before download.

3. Add the file and its assets

   Download the .md file into your repository. If the Word document contains images, extract and add those image files separately, then update their relative paths.

Check before you commit

• Use one top-level heading for the page title, then keep subsection levels in order.
• Review table column alignment and any cells that were merged in Word.
• Confirm code samples use fenced code blocks if the source document has them.
• Open image links in the repository preview to verify each relative path.
• Check that links point to the intended public or internal documentation pages.

Example image path

If you store an image at docs/assets/setup.png and the Markdown file is in docs, use a relative Markdown link like this:

![Setup screen](assets/setup.png)

Know the format limits

GitHub renders GitHub Flavored Markdown, but Markdown still has no standard way to represent merged table cells. Review complex Word layouts in GitHub after committing a draft.