Markdown to PDF with CSS

How your CSS is applied when Markdown becomes a PDF

Markdown has no styling of its own, which is exactly why people reach for CSS: it is the only widely understood way to say "11 pt serif body, 2 cm margins, a running header with the report title". MDtoDOCX converts Markdown to HTML, applies a cascade of stylesheets and then paginates that HTML into a PDF. Your CSS sits at the top of that cascade. This page describes what is in the cascade below it, which print-specific rules work, how fonts are handled and where the limits are, so you can write a stylesheet once and get the same document every time.

The cascade: MDtoDOCX's print stylesheet, then yours

Two stylesheets go into the document, in this order. First, MDtoDOCX's own print stylesheet, which is not a set of themes you choose between but a single sheet generated from the settings already in the converter: the font and size from the options bar become the body rules, the paper size and margins become the @page rule, and fixed rules handle table borders, code block padding, heading spacing, fragmentation and print-color-adjust. There is no theme picker in this version, so the way to change the starting point is to change those options or to override the properties yourself. Second, your CSS, emitted last in the document head. Nothing in the generated sheet uses !important, so any property you set wins on specificity ties simply by coming later, and you can reset the lot with a few blanket rules if you want a blank sheet. Because MDtoDOCX emits plain semantic HTML, h1 through h6, p, ul, table, pre code, blockquote, img, your selectors are the same ones you would write for a website. Fenced code blocks get a language-xxx class and syntax tokens get the standard .token.keyword classes, so a highlight.js or Prism theme pastes straight in and overrides the built-in token colours.

@page: size, margins, headers, footers and page numbers

The @page at-rule is where print CSS differs from screen CSS, and it is fully supported. size: A4, Letter, A4 landscape or explicit dimensions such as 210mm 297mm set the sheet. margin sets the printable area; anything you put in the sixteen margin boxes, @top-left, @top-center, @top-right, @bottom-center and so on, becomes a running header or footer on every page. Inside those boxes content: counter(page) gives the current page number and counter(pages) the total, so content: counter(page) " of " counter(pages) produces "3 of 12". The :first pseudo-class lets the title page drop its header, and named pages such as @page landscape { size: landscape } with .wide { page: landscape } rotate a single wide table. These rules only apply in the PDF; the HTML download ignores them.

Controlling page breaks

Use the modern fragmentation properties: break-before: page on an h1 starts each chapter on a new sheet; break-after: avoid on headings keeps them with the paragraph that follows; break-inside: avoid on pre, table, figure and blockquote stops them being cut. The older page-break-* spellings are accepted too. orphans and widows default to 2 and can be raised. A single Markdown line containing only ---pagebreak--- or the HTML comment <!-- pagebreak --> forces a break without any CSS.

Fonts: what a font-family actually resolves to

Any font-family you name is resolved in two steps. If it is one of the fonts bundled with MDtoDOCX (Inter, Source Serif 4, Source Sans 3, JetBrains Mono, Latin Modern, STIX Two), it is used directly. Otherwise the family is looked up on the machine doing the rendering, and if it is not installed there the next name in your font stack is tried, exactly as in a browser. Remote font files are not downloaded for you in this version: an @import url(https://fonts.googleapis.com/…) or an @font-face whose src points at a URL is not fetched, so a Google Fonts line in your stylesheet will silently fall through to the next family rather than producing the face you named. That is a limitation of the current release. The practical rule is to write a stack you can vouch for, ending in a generic family, for example font-family: "Source Serif 4", Georgia, serif. The glyphs actually used are embedded in the PDF when it is produced, so a recipient without the font still sees the document correctly. Prefer pt for font sizes and cm or mm for margins; px is converted at 96 per inch, which is what browsers assume, but point units make the intent clear on paper.

Printing backgrounds and colours

Browsers drop background colours when printing unless told otherwise, which is why a shaded table header vanishes in most Markdown-to-PDF tools. MDtoDOCX sets -webkit-print-color-adjust: exact and print-color-adjust: exact on every element, so th { background: #eee } prints as written. This is unconditional: there is no switch in the options bar to turn printed backgrounds off in the current version. If you want a toner-saving draft, say so in your own stylesheet, which is loaded after ours — @media print { *, *::before { background: none !important } } strips the shading while leaving the layout alone. Colours are written into the PDF as sRGB; if you need a CMYK-only workflow, export and convert in your print tool.

What is not supported

JavaScript in the Markdown is stripped. position: fixed is treated as static because the PDF engine paginates rather than scrolls; use margin boxes for running content instead. CSS Regions, string-set for chapter titles in headers and footnote floats are not implemented. Remote font files are not fetched, as described above, and there is no theme picker and no printed-background switch in this release. External images referenced from CSS background-image must be reachable over https. Everything else that renders in a current browser, including grid, flexbox, custom properties and @media print, renders in the PDF.

Free preview, Pro download

The preview applies your CSS for free, so you can iterate on a stylesheet without an account. Downloading a PDF with custom CSS and @page rules is a Pro feature; a free download uses the generated print stylesheet alone, driven by the font, size and paper you picked in the options bar. Stylesheets can be saved as presets and reused across documents on the Pro plan, and the same preset applies to Markdown to HTML output. See Pricing for the 7-Day Pass at $4.9.

Frequently asked questions