mdtopdf.

Document field notes

Raw HTML in a Markdown PDF: what prints, what hides

How raw HTML behaves on export, why a closed details section can vanish from the PDF, and which inline elements still print.

Published 2026-10-24 · Markdown to PDF editorial

Raw HTML mostly passes through a Markdown preview, and most of it prints. One element breaks that assumption: a closed <details> section prints its summary and leaves the content out of the PDF entirely. If you hide detail behind a toggle, the PDF loses it.

Why HTML behaves differently from Markdown

CommonMark allows raw HTML blocks, so a document can carry elements that Markdown has no syntax for. Markdown to PDF renders that HTML in the browser and prints the result, which is why a <kbd> keycap or a highlighted phrase survives export. Print output only includes what is visible at print time, and a closed disclosure element is not visible content.

A fixture with both states

# HTML test

Visible paragraph.

<!-- This comment should not print -->

<details>
<summary>Hidden detail</summary>
This text is inside a closed details element.
</details>

<details open>
<summary>Open detail</summary>
This text is visible because the element is open.
</details>

<mark>Highlighted</mark> and H<sub>2</sub>O and x<sup>2</sup>.

Press <kbd>Ctrl</kbd>+<kbd>S</kbd> to save.

<div align="center">Centered text</div>

What the checks showed

The fixture was opened in the live preview and exported as a one-page PDF on 24 October 2026. These are observations from that session, not a specification of every browser or renderer.

  • The closed section printed only its summary. "Hidden detail" appeared as a collapsed disclosure row; the sentence inside it was absent from the PDF text. It was visible in the source, not in the output.
  • The open section printed its body. "Open detail" and the sentence underneath both appeared. Adding open to the element changed the result.
  • The small HTML elements printed. <mark> produced a highlighted phrase, <kbd> produced keycap styling around Ctrl and S, and sub/superscripts kept their positions.
  • The centre-aligned block printed centred. The align="center" attribute was honoured in the export, although it is obsolete in HTML5; treat it as a legacy convenience and check the result.
  • The HTML comment did not print. It was not visible in the preview or in the PDF text.
  • The highlight lost its colour in greyscale. The phrase remained readable as text, but the yellow became a faint grey band. Do not rely on the highlight alone to carry meaning.

Use HTML only where Markdown stops

  1. Keep closed details for optional material. A changelog of older releases or a long troubleshooting appendix can sit behind a closed disclosure on the web. In a PDF, only the summary will print. If the content matters to the recipient, write <details open> or convert the section to a normal heading and paragraphs.
  2. Do not hide instructions in a disclosure. A prerequisite, a warning or a required step must be visible in the printed page. A toggle that looks open to you may export closed to someone else.
  3. Prefer Markdown for structure. Headings, lists, tables and emphasis have portable syntax and predictable print behaviour. Raw HTML should be the exception: a keycap, a highlight, a centred line, a small image width.
  4. Repeat meaning that depends on styling. A highlight, a colour or a background is decoration. Write "required" or "deprecated" in words so the meaning survives greyscale and text extraction.
  5. Use comments for editorial notes, not secrets. Comments do not print, which is useful for leaving yourself a note in the source. They remain in the Markdown and may be visible in a repository, so they are not a place for credentials or private remarks.
  6. Leave script and style out of documents. They are not content, their behaviour varies between renderers, and they are not something a PDF export needs. Use the converter's own settings for layout.

Check the HTML in the printed file

  1. Search the PDF for the hidden text. If a disclosure was meant to print, search for a phrase from inside it. In the test, that phrase was absent.
  2. Print or preview in greyscale. Confirm that a highlight or coloured label is not the only carrier of meaning.
  3. Check centred and aligned lines. Short lines centre cleanly; a long sentence in a centred div can look uneven on a narrow page. Keep the technique for captions and short statements.
  4. Check keycaps and superscripts at 100%. They are small by design. If a key combination is critical, spell it out in the sentence as well.
  5. Confirm comments are absent. If you left yourself a note in the source, verify it did not leak into the visible page. Absence from the page is not proof that the source is private.

Diagnose raw HTML that misbehaved

Text inside a disclosure is missing from the PDF
The element is closed. Add open, or replace the disclosure with a heading and normal paragraphs before exporting.
An HTML tag appears as literal text
The block may be indented or split in a way that stops it being parsed as HTML. Put the element at the start of a line, keep the tags balanced, and check the preview before exporting.
A highlight is invisible in print
The colour did not survive greyscale or the printer. Keep the words and add bold or a label; do not depend on the background.
Centred text looks ragged
Centring works best on one or two short lines. Long centred paragraphs are harder to read; use normal left-aligned text.
A comment appears on the page
Check that it uses HTML comment syntax rather than visible text or a Markdown blockquote. If it still prints, remove it from the source rather than relying on rendering.
The page looks different from the preview
Compare the PDF at 100%, then in a second viewer. Print layout, not the editor pane, is the final output.

Delivery checklist

  • No required instruction sits inside a closed disclosure element.
  • Every <details> that must print has open, or was converted to ordinary Markdown.
  • Highlights and colours are backed by words.
  • Keycaps, superscripts and centred lines were checked at 100% in the PDF.
  • Comments are absent from the printed page and contain nothing private.
  • No script or style elements were used as document content.
  • The full PDF text was searched for any phrase that was supposed to be hidden.

Sources and scope

Checked 24 October 2026. The workflow is editorial guidance. Preview and PDF observations come from one desktop browser session and one one-page export on that date; no cross-browser or printer certification is claimed.