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

Source: Dev.to

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. Its “killer feature” for corporate environments is the --reference-doc flag, which lets you map plain Markdown onto a strictly formatted corporate Word template.

The Workflow

Tutorial: Set Up Your Documentation Factory

Step 1: Install Pandoc

• macOS:

  brew install pandoc

• Windows:

  choco install pandoc

Step 2: Create the Reference Doc (The Template)

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, etc.) and 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.
• Lists are perfectly indented.
• The company logo is already in the header/footer.

Why This Is a Career Hack

• Speed: You write ~3× faster in Markdown than in Word.
• Version Control: Track changes in Git. Reviewing a binary .docx is impossible, but reviewing Markdown is straightforward; the Word doc is generated as a build artifact.
• Professionalism: Deliver documents that look exactly like the business expects, without ever opening Office 365.

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