mdword

Why this exists

I like Markdown. It fits well in git, diffs cleanly, edits and lives offline well, supports efficient editors, and reviews like code.

Technical teams I work with share this opinion mostly, but the business teams don't share that preference. They want a Word document, and it has to land in SharePoint or Word Online looking like it belongs there.

mdword is a small piece of documentation collaboration tooling built to close that gap: technical writing stays in Markdown the whole way through, from first draft to final review, and what comes out the other end is a document a business stakeholder would assume was made carefully, not generated.

The gap it closes

Pandoc's default Word output looks like the sad legacy thing it is: Times New Roman-ish fonts, a bare header underline, tables with barely any style.

Hand that to a business stakeholder, and they'll assume you are strange or lazy, when really you just use a better tool for your role.

Modern Word and Word Online have a clean, opinionated look out of the box, so mdword ships a reference.docx built to match it, which means the technical side never has to leave the tools it already trusts to produce something the business side will actually take seriously.

The fix, in one command

pandoc yourfile.md --reference-doc=reference.docx -f markdown-auto_identifiers -o yourfile.docx

A pandoc reference-doc is just a real Word file whose named styles pandoc copies onto your Markdown when it builds the .docx - Normal, headings, table style, block quote, code block, all of it.

Pandoc only reads style definitions from it, never content, so there's no leftover text that can sneak into your output. If the reference file already looks like a polished modern Word doc, everything generated from it does too.

-f markdown-auto_identifiers turns off pandoc's automatic heading bookmarks, which nobody asked for and which read as odd little artifacts to anyone outside engineering. Add --toc if you want a table of contents.

The shell script

Typing that full invocation every time gets old, so mdword wraps it:

mdword input.md                 -> input.docx
mdword input.md output.docx     -> custom output path
mdword input.md --toc           -> also add a table of contents

It resolves the reference doc from ${XDG_CONFIG_HOME:-$HOME/.config}/mdword/reference.docx by default, with a MDWORD_REFERENCE_DOC environment variable to point at a different one per run, so no editing the script is required.

set -euo pipefail keeps it from limping on partway through a bad state, and it checks for pandoc up front with a plain-English error and the install command, rather than failing three steps deep with something cryptic.

Output path defaults to swapping the input's extension, or takes an explicit second argument. That's the entire script: no dependencies beyond pandoc, no config file to hand-edit unless you want a different reference doc.

The installer

install.sh puts mdword on your PATH and the reference doc where the script expects it, using ~/.local/bin and ~/.config/mdword, both already-standard XDG locations, nothing new invented off $HOME just because it was convenient to write.

It checks whether that bin directory is actually on your live PATH at runtime, rather than grepping a dotfile for it, which avoids false negatives when PATH is already set some other way: .zprofile, a shell plugin manager, direnv, whatever you've got.

If it isn't on PATH, the installer tells you the exact line to add and, only in an interactive terminal, offers to append it to ~/.zshrc for you. It never edits a dotfile silently, and it never guesses in a non-interactive run.

Why this is worth a whole tiny project

The actual cost this solves isn't really about fonts. It's the tax on every handoff between people who write in Markdown and people who read Word documents.

Without a shared, presentable output, that tax gets paid one of two ways: technical work shows up looking rough and undermines its own credibility, or someone burns time manually reformatting the same headings and tables in Word by hand, every single time. Neither is a good trade for a problem that's fixable once.

A reference.docx built to match what stakeholders already expect from Word Online removes that tax permanently. Technical and business teams end up collaborating off the exact same source material, with neither side having to babysit formatting on the way out the door.

See it for yourself

Same example file, run through pandoc twice: once with no reference doc, once with mdword's.

Two pages of the same comparison side by side, with pandoc's default on the left and mdword's output on the right:

Built with

A bash script, pandoc, and a hand-tuned reference.docx, with fonts, styles, and table styling matched to Word Online's current default look.

That's the whole stack, on purpose. The first release is shipped, and probably close to the only one it needs.