mark-my-word 0.2.3

Convert Markdown file to PDF using themes extracted directly from Word templates

mark-my-word

You have a Word template — the right fonts, colours, headers, footers. You have a Markdown file you want to print. mark-my-word connects the two: it reads your Word template and uses it to render your Markdown as a styled PDF.

Is this for me?

It's a good fit if:

• You have a .docx or .dotx Word template with the styling you want
• You want your PDFs to match that template without manual CSS work
• You're happy running a command-line tool

It's probably not for you if you need pixel-perfect fidelity to complex Word layouts (tables with merged cells, tracked changes, etc.) or if you need to render Word documents directly — this tool works with Markdown input.

Install

uv tool install mark-my-word
# or
pipx install mark-my-word

Requires Python 3.11+. WeasyPrint (the PDF engine) needs some system libraries — see the WeasyPrint docs if the install fails.

Basic usage

Pass your Word template directly and mark-my-word does the rest:

mark-my-word render document.md --template my-template.dotx

Output lands next to the input file by default (document.pdf). Use --output to put it somewhere else:

mark-my-word render document.md --template my-template.dotx --output /tmp/document.pdf

If the output file already exists, the command refuses rather than silently overwriting. Use --force (or -f) to overwrite:

mark-my-word render document.md --template my-template.dotx --force

Or extract the theme separately

If you render from the same template often, extract it once and reuse the theme directory:

mark-my-word extract my-template.dotx --output themes/my-theme/
mark-my-word render document.md --theme themes/my-theme/

The extracted theme is plain CSS and HTML — easy to inspect or tweak. Add --save-theme themes/my-theme/ to the one-step command if you want to keep the theme without a separate extract step.

Document frontmatter

Headers and footers in your theme can include placeholders like {{title}} or {{author}}. You can also supply a fallback: {{title: Untitled}} is used when title is not set. Matching is case-insensitive.

Set values in your Markdown file's YAML frontmatter:

---
title: Q1 Report
author: Daniel
---

# Introduction

...

Pass extra values on the command line with --set:

mark-my-word render document.md --theme themes/my-theme/ --set version=draft

Skipping preamble

If you write notes in an app like NotePlan, there's often metadata at the top — tags, links, app-specific syntax — that you don't want in the PDF. Put <!--more--> on its own line to mark where your real content starts:

@project(Quarterly Review)
[[linked-note]]

<!--more-->

# Q1 Report

...

Everything before <!--more--> is ignored. Everything after renders normally. If <!--more--> appears inside a code block in the body, put a second one at the top of the document to act as the separator instead.

What gets extracted

From your Word template, mark-my-word extract pulls:

• Page margins
• Theme colours → CSS custom properties (--color-body, --color-heading, etc.)
• Body text formatting: font family, size, line height, and paragraph spacing (from the Normal style)
• Heading styles: font size, weight, colour, and spacing for H1–H6
• Header and footer content, including tab-separated left/right layouts, page numbers, and paragraph borders (top and bottom)
• Watermark images

The result is a plain directory you can inspect and edit. The stylesheet uses CSS custom properties throughout, so tweaking colours or fonts is a one-line change.

Theme directory layout

themes/my-theme/
  style.css           required
  header.html         header on all pages (or cont-header.html / first-header.html)
  footer.html         footer on all pages (or cont-footer.html / first-footer.html)
  watermark.png       optional full-page background image

If your Word template has a different header on the first page, extract writes first-header.html and cont-header.html separately. render handles both layouts automatically.

Tips for Word templates

Left/right footer layouts

For a footer with content on the left and right (e.g. company name on the left, page number on the right), use a single paragraph with a right-aligned tab stop rather than a table:

1. In your footer, type the left content
2. Press Tab
3. Type the right content
4. Set a right-aligned tab stop at the right margin (Format → Tabs, or drag the tab marker in the ruler)

mark-my-word converts the tab character into a flex-row layout. Tables work too, but they carry implicit cell spacing that doesn't always translate cleanly.

Horizontal rules

To draw a decorative line above or below footer content, add a paragraph border (Format → Borders and Shading → Borders tab) rather than an actual horizontal rule or a separate table row. Paragraph top and bottom borders are extracted and rendered faithfully.

Options

mark-my-word render --help
mark-my-word extract --help

Changelog

0.2.3

• More style properties are now extracted from the Word template and applied to the PDF: body text font size, line height, and paragraph spacing (from the Normal style) join heading size, weight, colour, and spacing (H1–H6) as template-driven values rather than hardcoded defaults
• Internal cleanup: removed unused helper functions

0.2.2

• README updated with 0.2.1 changes (should have shipped with the release)

0.2.1

• Paragraph borders (top and bottom) in Word headers and footers are now extracted and rendered with correct spacing
• Empty paragraphs used as horizontal rules extract at natural line height, matching Word's visual spacing
• Footer height estimation fixed: <p> elements inside flex-row cells are no longer counted as separate lines, preventing over-large body margins
• Page break orphan/widow protection relaxed from 3 lines to 2

0.2.0

• First-page header/footer fallback: if no distinct first-page fragments exist, the running header/footer is used on all pages
• <!--more--> preamble separator support
• {{variable: default}} syntax for fragment placeholders
• H1 extracted as document title and removed from body when no title: frontmatter is set
• --force flag to overwrite existing output files
• Watermark extraction from Word VML <w:pict> elements

Links

• Repository
• Issue tracker