Templates & Mappings

The system that connects markdown elements to Word styles.

What are templates?

A template is a regular Word .docx file. It contains the styles, fonts, headers, footers, and page layout you want in your output documents. Think of it as the shell — MDDoc pours your markdown content into it.

You create templates in Word (or Google Docs exported as .docx). Then you upload them to MDDoc. Every template gets versioned — update it whenever your branding changes.

Templates are managed via the dashboard. The public API provides read-only access for listing templates and their styles. Upload and edit templates in the MDDoc web app.

What templates can include

Cover page — automatically preserved. MDDoc keeps the first section of your template as-is and can update the title from your first H1.
Paragraph and character styles — Heading 1 through Heading 6, body text, lists, code blocks, quotes, tables.
Custom fonts — upload .ttf, .otf, .woff, or .woff2 files to the font library. Templates using custom fonts will render correctly.
Headers and footers — page numbers, logos, dates. They carry through to the output.
Final page — content after the last section break is preserved (useful for appendix pages, back covers).

Style extraction

When you upload a template, MDDoc reads every paragraph and character style defined in the .docx file. You can see the full list via the dashboard or API:

Get template styles (internal API)

curl https://api.mddoc.app/api/templates/TEMPLATE_ID/styles \
  -H "Authorization: Bearer mddoc_YOUR_KEY"

Response

{
  "template_id": "550e8400-...",
  "styles": [
    "Normal", "Heading 1", "Heading 2", "Heading 3",
    "List Bullet", "List Bullet 2", "List Number",
    "Code", "Quote", "Title", "Subtitle",
    "Header", "Footer", "TOC Heading"
  ],
  "used_styles": [
    "Normal", "Heading 1", "Title", "Subtitle"
  ]
}

styles lists every style defined in the template. used_styles shows which styles are actually applied to content in the template file. Use both to build your mapping.

What are mappings?

A mapping is a set of rules that tell MDDoc which Word style to apply for each markdown element. Heading 1 becomes "Heading 1" in Word. A bullet list becomes "List Bullet." A code block becomes your "Code" style.

Each mapping is tied to a template. Different templates have different style names, so you need different mappings.

Mapping rules schema

Here's the full schema for a mapping's rules object:

Field	Type	Default	Description
heading	object	—	Map of heading level to style name, e.g. {"1": "Heading 1", "2": "Heading 2"}
document_title	string	""	Style for the cover page title (from first H1)
document_subtitle	string	""	Cover page subtitle style
paragraph	string	"Normal"	Body text style
list_bullet	string	"List Bullet"	Level 1 bullet list
list_bullet_2	string	"List Bullet 2"	Level 2 bullet list
list_bullet_3	string	"List Bullet 3"	Level 3 bullet list
list_ordered	string	"List Number"	Level 1 numbered list
list_ordered_2	string	"List Number 2"	Level 2 numbered list
list_ordered_3	string	"List Number 3"	Level 3 numbered list
code_block	string	"Code"	Fenced code block style
blockquote	string	"Quote"	Block quote style
table	object	—	{style, header_row} — table style name and whether first row is a header
page_break_before	string[]	[]	Elements that trigger a page break, e.g. ["heading.1"]
metadata_mapping	object	{}	Cover page field-to-style mapping for metadata clearing

Example mapping

Here's a complete mapping for a typical corporate template:

Full mapping rules

{
  "heading": {
    "1": "Heading 1",
    "2": "Heading 2",
    "3": "Heading 3",
    "4": "Heading 4"
  },
  "document_title": "Cover heading",
  "document_subtitle": "Cover subtitle",
  "paragraph": "Normal",
  "list_bullet": "List Bullet",
  "list_bullet_2": "List Bullet 2",
  "list_bullet_3": "List Bullet 3",
  "list_ordered": "List Number",
  "list_ordered_2": "List Number 2",
  "list_ordered_3": "List Number 3",
  "code_block": "Code Block",
  "blockquote": "Block Quote",
  "table": {
    "style": "Grid Table 1 Light",
    "header_row": true
  },
  "page_break_before": ["heading.1"],
  "metadata_mapping": {
    "Author": "Cover Author",
    "Date": "Cover Date"
  }
}

How conversion uses mappings

When MDDoc converts your markdown, it:

Parses the markdown into a structured AST (abstract syntax tree)
Loads the .docx template
Validates that every style referenced in the mapping exists in the template
Preserves the cover page and final page sections
Walks each AST node and creates a Word paragraph with the mapped style
Returns the result with a conversion report

If a mapped style doesn't exist in the template, the conversion still succeeds — it falls back to the default style and includes a warning in the response.

Validation warnings

The conversion report includes two types of warnings:

Warning type	Meaning
missing_style	A mapping rule references a style that doesn't exist in the template
unmapped_element	The markdown contains an element with no corresponding mapping rule

Check warnings in your API response to catch mapping issues early. Zero warnings means a clean conversion.

Learn how to use MDDoc directly from your AI assistant with the MCP Server integration.

Conversion API MCP Server