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

Source: Dev.to | Dec 19, 2025 (UTC)

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

Enter fullscreen mode

Exit fullscreen mode