How to Write in Markdown but Deliver in Word. A Senior Architect's Workflow.

The Conflict: Engineering vs. Management

There is a fundamental conflict in corporate IT:

• Engineers want to write documentation like code (Markdown, in IDE, versioned in Git).
• Management/Clients want "professional" documents (Word, neatly formatted, with logos).

As a Senior Architect, I refuse to spend my "Deep Work" hours fighting with Microsoft Word margins or table alignments. But I also know that sending a raw .md file to a stakeholder is unprofessional.

The solution is not to surrender to Word. The solution is to compile to Word.

The Tool: Pandoc with Reference Docs

Pandoc is a command-line tool that converts text formats. But its "killer feature" for corporate environments is the --reference-doc flag.

This feature allows you to map your plain Markdown text onto a strictly formatted corporate Word template.

The Workflow

Tutorial: Setup Your Factory

Here is how I set up a "Documentation Factory" in 5 minutes.

Step 1: Install Pandoc

macOS: brew install pandoc
Windows: choco install pandoc

Step 2: Create the "Reference Dog" (The Template)

This is the most important step. You don't create styles in Pandoc. You "steal" them from a Word doc.

1. Take an existing, well-formatted document from your company (one with the correct headers, fonts, and footer logo).
2. Delete all the content, leaving just one dummy header and one paragraph.
3. Save it as reference.docx.

Step 3: Write in Markdown

Open your IDE (VS Code / IntelliJ). Write your specs using standard Markdown.

# Architectural Decision Record 001

## Context
We need to migrate the Monolith to AWS.

## Decision
We will use AWS Lambda and Spring Boot SnapStart.

## Consequences
* Cost reduction by 40%
* Cold starts handled by SnapStart

Step 4: The Build Command

Run this simple command in your terminal:

pandoc input.md -o Final_Report.docx --reference-doc=reference.docx

What just happened?
Pandoc took your text from input.md and "poured" it into the styles defined in reference.docx.

• Your # Header 1 became the company's official blue, size 16 font.
• Your lists are perfectly indented.
• The company logo is already in the header/footer.

Why This is a Career Hack

1. Speed: You write 3x faster in Markdown than in Word.
2. Version Control: You can track changes in Git. Try doing a "Code Review" on a binary .docx file—it's impossible. With this method, you review the Markdown, merge it, and generate the Word doc as a build artifact.
3. Professionalism: You deliver documents that look exactly like the business expects, without ever opening Office 365.

Work smart, not hard. Let the CLI handle the formatting.