Advanced Conversion Options

md2docx includes a handful of options that control layout behavior in Word. These are designed for real-world reports: TOCs, page breaks, section breaks, and callouts.

You’ll find these options on the Convert page under “Advanced options”.

The best approach is to start with the defaults, then enable options only when you have a specific layout goal (for example: “I need a TOC” or “this appendix must be landscape”).

Quick decision guide (which options should you use?)

Most documents don’t need every toggle. Use this as a fast “yes/no” filter:

• TOC: enable when the document is more than ~2–3 pages or has many sections.
• Page break before H1: enable for report-style documents (chapters, appendices, formal proposals).
• Page breaks on ---: enable when you want explicit section boundaries without relying on Word’s pagination.
• Section breaks on ---: enable when you need a landscape page or a different layout for only part of the document.
• Remote images: enable only when images are safe to fetch and must be embedded in the final DOCX.
• Callout labels: enable when the document uses notes/warnings/tips and you want them to stand out during review.

If you’re unsure, convert once with defaults, then enable one option at a time until the document matches your desired layout.

Embed images from remote URLs

When enabled, md2docx fetches HTTP(S) images referenced in Markdown and embeds them into the DOCX:

![Architecture](https://example.com/diagram.png)

If you’re working with confidential documents or private links, keep this off and avoid remote image URLs. For more details, see Limitations.

Remote image embedding is useful for “report-style” Markdown where figures live on the web (public repos, docs sites, or ticket attachments). It’s also the option most likely to surprise people, so treat it as an explicit decision.

When to enable it

• Your Markdown references public images that should appear in the final report.
• You want a self-contained DOCX without “missing image” placeholders.

When to leave it off

• You’re converting sensitive docs and don’t want the server fetching external URLs.
• Your images are behind authentication, short-lived signed URLs, or private networks.

Best practices

• Prefer stable URLs; avoid links that expire quickly.
• Use descriptive alt text. It makes the Markdown easier to review and helps document structure.
• If you have a lot of diagrams, consider using diagram-as-code blocks (Mermaid, Graphviz, PlantUML) instead of remote images. Guides: Mermaid and Graphviz + PlantUML.

Insert table of contents

Inserts a Word table of contents based on headings. This works best when you use Heading 1–3 consistently (see Headings and TOC).

After conversion, Word may ask to update fields when you open the file. If the TOC looks incomplete, right-click it and choose Update Field → Update entire table.

A TOC is only as good as the heading structure. If you want a “report feel”, keep one title as H1 and use H2/H3 for the rest (guide: Headings & TOC).

Page breaks and section breaks (using ---)

Use horizontal rules in Markdown to control pagination:

## Section A

Content…

---

## Section B

More content…

• Page break on horizontal rule: turns --- into a new page.
• Section break on horizontal rule: creates a Word section (useful when changing orientation for wide tables).

Use page breaks when you want visual separation. Use section breaks when you need different layout rules (orientation, headers/footers, margins) for a portion of the document.

A practical pattern: appendices

Many reports have an appendix that should be separated from the main narrative. A simple approach:

## Main report

Main content…

---

# Appendix

## Supporting data

Tables…

With the right options enabled, that horizontal rule becomes a clean boundary between “main report” and “appendix” without manual editing in Word.

Insert page break before each H1

This option makes every top-level heading (# Heading) start on a new page. It’s a simple way to make longer reports feel structured: title → chapter → chapter, without manual pagination.

If your Markdown has many H1 headings, consider switching most of them to H2 so you don’t create too many page breaks.

A good compromise is: use H1 for the title and major parts (“Appendix”, “Release notes”), then use H2 for the rest of the document. This keeps the structure deep enough for a TOC without creating dozens of page breaks.

Use section breaks for landscape pages (wide tables/diagrams)

Word can mix portrait and landscape pages in the same document, but it requires section breaks. The “Section break on horizontal rule” option exists primarily for this workflow.

Recommended steps:

1. Enable Section break on horizontal rule.
2. In your Markdown, place --- before and after the wide content.
3. Convert and open the DOCX in Word.
4. Click inside the wide section, then use Layout → Orientation → Landscape, and apply it to This section.

This is a clean way to handle wide tables without shrinking text to unreadable sizes. For table guidance, see Mastering Markdown tables.

Admonition labels (callouts)

md2docx supports callouts/admonitions. You can write:

:::note
This is a note.
:::

:::warning
This is a warning.
:::

When “Include labels for callouts/admonitions” is enabled, md2docx prefixes a bold label like “NOTE” or “WARNING” in the output, which makes long docs easier to scan.

Callouts are great for reviewer-friendly docs: assumptions, decisions, risks, and “do not skip this” information. Pair them with a template that defines the Quote style if you want a specific look.

Good callout patterns for business docs

• NOTE: clarifies assumptions or context without interrupting flow.
• WARNING: flags risks, breaking changes, or high-impact tradeoffs.
• TIP: suggests a better workflow (templates, TOC, headings structure).

Recommended settings for common documents

Stakeholder report / proposal

• Enable: TOC, Page break before each H1
• Enable (optional): Page break on --- for appendices

Technical spec with diagrams and tables

• Enable: TOC
• Enable (optional): Section breaks on --- for landscape pages
• Enable remote images only if your diagrams are public or non-sensitive

AI-generated draft cleanup

• Enable: TOC if the doc is long
• Enable callout labels to make warnings/notes obvious

Academic or technical writing

• Enable: TOC for longer papers
• Enable callout labels for assumptions and constraints
• Use templates for consistent spacing and heading styles

Templates + options: the best combination

Options control layout behavior, but templates control the “feel” of the final DOCX. If you want a document that looks polished without manual cleanup, use both:

• Template: fonts, margins, heading styles, table appearance.
• Options: TOC insertion, page/section break behavior, callout labels.

Start with Custom templates, then add the options you need for the specific document type.

Troubleshooting

• Images missing: remote fetching may be disabled, the URL may be blocked, or the URL may require authentication.
• TOC looks outdated: update fields in Word (right-click TOC → Update Field).
• Unexpected page breaks: check whether you have multiple H1 headings combined with “page break before each H1”.
• Wide content looks cramped: use a section break (---) and switch that section to landscape in Word.
• Callouts don’t stand out: enable callout labels and/or use a template that defines the Quote style.

For known limitations and best-effort behavior, see Limitations.