Skip to main content

Workflow guide

Prepare converted Markdown for GitHub documentation

GitHub, MkDocs, and Docusaurus all accept Markdown, but a converted file is not a finished documentation page. Each destination has its own rules for front matter, navigation, links, assets, and optional Markdown extensions. Use conversion to recover source structure, then make the smallest destination-specific edits and verify the real documentation build.

Last updated
August 12, 2026
Test environment
To-Markdown web converter; Firecrawl AnyDoc Word and PowerPoint examples; GitHub-flavored Markdown review

1. Convert the editable source into a review branch

Convert the Word or PowerPoint source and save the result with a short, descriptive, lowercase file name. Commit it on a branch so reviewers can compare the text and see later cleanup separately. Keep the source document available during review rather than treating conversion output as authoritative.

The published Word example exercises headings, bullets, a hyperlink, and a simple table. The PowerPoint example exercises two slide headings, bullets, and a table. Use those pages to understand the current output before processing a larger document.

  • Remove duplicated titles if the destination already renders a title from front matter.
  • Use one logical H1 in plain GitHub documents; follow the site theme's title convention elsewhere.
  • Preserve code fences and avoid line wrapping that changes code or tables.

2. Adapt links, assets, and metadata to the destination

GitHub README files commonly use repository-relative links. MkDocs resolves pages and assets according to its docs directory and configuration. Docusaurus commonly uses front matter plus docs-sidebars configuration or autogenerated sidebars. Conversion cannot infer any of these project rules.

Copy images into the repository and write meaningful alt text. Word embedded images are not retained by the current converter, and PowerPoint charts or SmartArt are not reproduced. If a visual is essential, export it, add a relative image reference, and summarize the conclusion in nearby text.

  • Replace links to local Word files or intranet paths with durable destinations.
  • Add only the front matter fields supported by the target project.
  • Update MkDocs nav or Docusaurus sidebar configuration when the project requires it.
  • Check heading anchors after renaming imported headings.

3. Run the documentation build and review the rendered page

A source-level review catches malformed Markdown; a real build catches broken links, unsupported directives, invalid front matter, and navigation mistakes. Run the repository's existing formatter, link checker, and documentation build. Preview the page at mobile and desktop widths when tables, images, or long code blocks are present.

Finish with a subject-matter review. A syntactically valid conversion can still reverse a slide's reading order, omit a speaker note, or flatten a table in a misleading way. Ask the content owner to verify technical claims, commands, names, numbers, and release-specific details.

  • Confirm every new page has an inbound navigation or contextual link.
  • Check internal links and assets from the built output, not only the editor preview.
  • Keep generated changes scoped so reviewers can identify manual corrections.
  • Record the source revision and update date in the pull request or page metadata.

From the tested PowerPoint sample to a docs page

The PowerPoint converter's reproducible two-slide sample produces a linear outline. It is a useful starting point, but a documentation author still needs to choose the page title, explain context, and wire the page into navigation.

Slide content

Q3 launch plan with two bullets, followed by an Owners slide with a two-column table

Observed Markdown

## Q3 launch plan

- Ship the help center
- Verify analytics

## Owners

| Work | Owner |
| --- | --- |
| Help center | Maya |
| Analytics | Theo |

Next step: Promote or rename headings to match the destination page, describe any missing visual context, then run the project's own documentation build.

Review checklist

Complete these checks against the original source and the real destination before treating the Markdown as finished.

Check Acceptance criterion
Title and outline The page has one intended title and meaningful heading levels.
Links Relative and absolute links resolve in the built documentation site.
Assets Images are committed, referenced relatively, and have useful alt text.
Tables and code Content renders without overflow or syntax corruption.
Navigation The page appears in the expected GitHub, MkDocs, or Docusaurus path.
Build Existing formatting, link, and documentation checks pass.

Use a tested source converter

Word to Markdown Convert a DOCX guide and review the tested structure example. PowerPoint to Markdown Start from the tested slide outline and table example. Image to Markdown Extract text from screenshots; keep required image assets separately. Conversion API Automate one-source conversion before repository-specific validation.

Related workflow guides

Convert documents to Markdown for RAG ingestion A practical document-to-Markdown workflow for RAG ingestion: extract source content, review structure, preserve provenance, then chunk and index it downstream. Import documents into Obsidian as Markdown Convert Word, PowerPoint, and images to Markdown for Obsidian, then review links, attachments, properties, and note structure before adding it to your vault.