HTML and CSS

HTML and CSS

Leafmark can preserve HTML in HTML output and render block-level HTML into PNG images for PDF and DOCX. This makes CSS-designed cards, diagrams, badges, dashboards, and other components portable across output formats.

Add stylesheets

Reference CSS files through the frontmatter styles list:

---
title: Styled Report
styles:
  - styles/base.css
  - styles/components.css
---

Paths resolve from the active project. The build stops if a listed file is missing or styles is not a list of non-empty strings.

Write an HTML block

Raw HTML is supported:

<section class="summary-card">
  <h2>Quarterly summary</h2>
  <p>Revenue increased by <strong>18%</strong>.</p>
</section>

Fenced HTML is also supported. Write the normal Markdown fence around the fragment:

```html
<section class="summary-card">
  <h2>Quarterly summary</h2>
  <p>Revenue increased by <strong>18%</strong>.</p>
</section>
```

Fences labeled html or htm are rendered. HTML-looking text in other code fences remains code.

Example CSS

.summary-card {
  box-sizing: border-box;
  padding: 2rem;
  border: 1px solid #cbd5e1;
  border-radius: 1rem;
  color: #172033;
  background: #f8fafc;
}

.summary-card h2 {
  margin: 0 0 0.75rem;
  color: #1d4ed8;
}

.summary-card p {
  margin: 0;
}

Output behavior

Output	Behavior
HTML	The original markup remains in the document and every styles file is attached with Pandoc's --css. The standalone output embeds resources.
PDF	Each detected block is rendered in a headless Chromium-family browser, captured as a high-density PNG, and inserted into the PDF.
DOCX	The same PNG rendering is embedded in the Word document.

Rendered HTML uses a 1200 × 900 browser viewport, a 1120-pixel content width, 40-pixel page padding, and a 2× device scale. The screenshot is cropped to the root block's actual height.

Browser requirement

PDF and DOCX builds containing HTML blocks require one of these installed browsers:

• Google Chrome
• Chromium
• Microsoft Edge
• Brave Browser

Leafmark checks common installation locations on macOS, Windows, and Linux. HTML-only output does not need the screenshot renderer.

Security and behavior

• JavaScript is disabled during image rendering.
• CSS is allowed and local stylesheets are loaded.
• Web fonts and local font files referenced by CSS should be available when the block is rendered.
• Browser animation is disabled for screenshots.
• Each block becomes one image, so its text is not selectable in PDF or DOCX.
• Very tall blocks may be less suitable for page breaks; split them into multiple blocks.

Generated images

Images are written under dist/_html-blocks/ during the build and normally removed after Pandoc embeds them. To inspect them:

pnpx @skxv/leafmark --keep-build-files

The filenames contain a block index and a hash of the HTML, for example block-1-6b5db227a6.png.

Styling recommendations

• Give components an explicit background if they should not be transparent.
• Use responsive widths rather than fixed page-sized widths.
• Keep important text large enough after the image is scaled to document width.
• Avoid relying on hover, focus, animation, video, or JavaScript.
• Split content that needs to paginate naturally into Markdown or several HTML blocks.
• Put print-specific rules in @media print only if HTML export should differ; screenshots use normal screen media.

Troubleshooting

If the document prints literal text such as ![Rendered HTML block](...), update Leafmark and confirm the entire fenced block uses matching fences. If the PNG is missing after a successful build, remember that temporary images are removed unless --keep-build-files is used. See Troubleshooting for more.