# Convert Between Markdown and Word

Create reviewable Word documents from Markdown and return DOCX content to Markdown with explicit image and formatting policies.

A Markdown-to-Word workflow is useful when authors prefer text-based source control but reviewers need comments, tracked changes, or a familiar DOCX file. The return conversion is best treated as semantic round-trip, not pixel-perfect fidelity.

## Create the review copy

`Convert-OfficeDocument -To Word` accepts a Markdown path, Markdown text (`-Text -From Markdown`), or a parsed document (`-Document`). Pass `New-OfficeMarkdownWordOptions` through `-Options` for template insertion, front matter, and image policies.

```powershell
$options = New-OfficeMarkdownWordOptions -Template .\Template.docx -BookmarkName MainContent
$report = Convert-OfficeDocument -Path .\Review.md -To Word -OutputPath .\Review.docx -Options $options
$report.Diagnostics
```

## Return to Markdown

`Convert-OfficeDocument -To Markdown` accepts a Word path or loaded document. Use `New-OfficeWordMarkdownOptions` for image export mode and directory, underline, and highlight output. Those formatting extensions are opt-in because Markdown targets represent them differently.

```powershell
$options = New-OfficeWordMarkdownOptions -ImageExportMode File -ImageDirectory .\Review-Images
Convert-OfficeDocument -Path .\Review.docx -To Markdown -OutputPath .\Review.md -Options $options
```

The [Word round-trip recipe](https://github.com/EvotecIT/OfficeIMO/blob/3b680b1b6fb15a268ff5525a4ca6cdd70b2f6613/PowerShell/PSWriteOffice/Examples/Markdown/Recipe-Markdown-WordRoundTrip.ps1) creates Markdown, converts it to DOCX, and converts the Word file back to Markdown.

For heavily designed Word templates, define which semantic elements must survive before promising a round-trip. Tables, headings, lists, links, and basic emphasis are a better contract than exact pagination.

<!-- PowerForge markdown source sha256:093F3F676D89640FBCDB959CDCCD4920114667A77D62B0CD0739337F8A9B90BC; title=True -->

<!-- PowerForge markdown artifact sha256:7414BD8188D598CB2E356125791AE161DF3D64D0B83D0F436332901CFA1D4CF0 -->
