Professional Word Output

Production Pipeline

Documents are produced via Pandoc + python-docx + reference.docx template:

Markdown source (structured content)
    ↓ pandoc --reference-doc=templates/reference.docx
.docx (styles applied from reference.docx)
    ↓ manual python-docx post-processing (cover page, TOC, header/footer)
Final .docx → PDF export

Build commands

# Single document
pandoc source.md -o output.docx --reference-doc=templates/reference.docx

# With table of contents
pandoc source.md -o output.docx --reference-doc=templates/reference.docx --toc --toc-depth=3

# Rebuild reference.docx from scratch
python scripts/create-reference-docx.py

Style System

Pandoc maps Markdown elements to named Word styles in reference.docx. Never bypass this with direct formatting.

If a style needs to change, change it in reference.docx — never in the document directly.

Heading Flow & Page Break Rules

These rules are mandatory. They determine how the document breathes across pages and whether the reader can follow the structure without effort.

Rule 1 — Heading 1 always starts a new page

Every # Heading 1 forces a page break before it. Major sections never share a page with the section that precedes them. This makes the document scannable: readers flipping through pages immediately see where each chapter/section begins.

Word setting: Paragraph → Line and Page Breaks → Page break before = ON

python-docx:

from docx.oxml.ns import qn
from docx.oxml import OxmlElement

h1 = doc.styles['Heading 1']
h1.paragraph_format.page_break_before = True
h1.paragraph_format.keep_with_next = True   # heading never orphaned alone

Rule 2 — Heading 2 and Heading 3 stay with their first paragraph

If the heading plus its first following paragraph do not entirely fit on the current page, the whole unit moves to the next page. A heading that appears at the bottom of a page with its content on the next page is a design failure.

Word settings on Heading 2 and Heading 3:

• Paragraph → Line and Page Breaks → Keep with next = ON
• Paragraph → Line and Page Breaks → Keep lines together = ON

Word setting on Normal / body paragraphs:

• Paragraph → Line and Page Breaks → Keep lines together = ON

This combination means: the heading is glued to the paragraph that follows it, and that paragraph will not be split across pages. If the pair doesn't fit, both move to the next page.

python-docx:

for style_name in ['Heading 2', 'Heading 3']:
    style = doc.styles[style_name]
    style.paragraph_format.keep_with_next = True
    style.paragraph_format.keep_together = True

# Body paragraphs: never split mid-paragraph
doc.styles['Normal'].paragraph_format.keep_together = True

Rule 3 — Widow and orphan control is always on

No paragraph's first line appears alone at the bottom of a page (orphan), and no paragraph's last line appears alone at the top of a page (widow).

Word setting: Paragraph → Line and Page Breaks → Widow/Orphan control = ON (this is the Word default but must be confirmed in reference.docx).

doc.styles['Normal'].paragraph_format.widow_control = True

Summary table — paragraph flow settings per style

What this looks like in the document

• Opening a document and scanning: each major section (H1) occupies its own visual territory — top of a fresh page
• Reading through body content: the eye never arrives at an H2/H3 sitting stranded at the bottom of a page; the heading is always above its content
• Short paragraphs never lose their first or last line to a page break
• The result is a document that reads like it was typeset, not generated

Typography Specification

Read references/typography-layout.md for full font stacks and spacing tables. The standard corporate stack:

Heading 1 visual anchor: 4.5pt navy left border bar — applied via style paragraph border, not manual formatting.

Spacing Rules

Never press Enter twice to create space. Use style space-after settings.

Document Structure (every document)

1. Cover Page

---