Styling
For people who want to change how the document body looks: page style, fonts, code colours, their own CSS and page breaks.
The quickest change, in your settings file:
{
"look": "report",
"font": "serif",
"heading_font": "geometric",
"highlight_style": "atom-one-light.css"
}Page styles
look picks a ready-made style for the whole document:
| Value | Description |
|---|---|
clean | Default. GitHub-style, neutral. |
report | Serif headings, strong title rule. Business reports. |
academic | Serif body, justified, minimal colour, 25 mm margins, black and white code. |
compact | Dense and small, 10 mm margins. More text per page. |
technical | Framed code blocks, blue accents, Atom One light code colours. |
A look is a stylesheet plus a few settings. Keys you write next to it win, so "look": "academic", "margin": {"top": "20mm"} keeps the academic style with a smaller top margin.
Theme colour
report and technical have an accent colour. accent_color replaces it:
{
"look": "technical",
"accent_color": "#2e7d32"
}| Look | What changes |
|---|---|
technical | the rule under the title, section titles, the bar beside code blocks, inline code and table headers (a light tint) |
report | the rule under the title, the bar beside quotes |
The value is #rgb or #rrggbb. The other looks have no accent and ignore it. In your own CSS, var(--accent), var(--accent-strong) (darker) and var(--accent-soft) (light tint) give the same colours.
Fonts
| Key | Sets |
|---|---|
font | the text font, from a preset name |
heading_font | the title font (h1 to h6), from a preset name |
font_family | the text font, as a CSS font list |
heading_font_family | the title font, as a CSS font list |
The preset names are sans, serif, book, humanist, geometric, office, mono and system (see Settings file). For any other font:
{
"font_family": "\"Source Sans 3\", \"Segoe UI\", Arial, sans-serif",
"heading_font_family": "Georgia, serif"
}The font must be installed on the computer that makes the PDF. List a common font last as a fallback. A font you choose always wins over the font of the page style.
office needs Aptos or Calibri installed as a normal font. On Windows, Calibri always is; Aptos comes with recent Office. On a Mac, Office keeps its fonts for itself, so the PDF falls back to Segoe UI or Arial unless you install the font files. On Linux, the free Carlito font has the same widths as Calibri.
The header and footer use the text font unless you set font_family on them.
Your own CSS
{
"stylesheet_path": "pdf.css"
}The path is relative to the settings file. On the command line, --stylesheet-path pdf.css is relative to the Markdown file.
Your stylesheet is added after the built-in styles, so your rules win:
h1 { color: #0b4f8a; border-bottom: 2px solid #0b4f8a; }
table { font-size: 0.9em; }
th { background: #f0f4f8; }
blockquote { border-left-color: #0b4f8a; }
a { color: inherit; text-decoration: underline; }A page style is a stylesheet too, and only one stylesheet is used: stylesheet_path replaces the look's stylesheet. Use one or the other.
The styles are added in this order (later wins):
- The built-in stylesheet.
- The maths stylesheet, when
mathis on. - The code colour theme.
- Your stylesheet, or the look's stylesheet.
- The fonts you chose.
Start from a blank page
{
"include_default_styles": false,
"stylesheet_path": "my-print.css"
}With include_default_styles set to false, the built-in stylesheet is left out and only your CSS (plus the code colours) applies. Headings, tables and code blocks then use the browser's plain defaults until you style them.
Background colours are printed by default; set "print_background": false to save ink.
Code colours
highlight_style picks the colour theme for code blocks. It takes the file name of any highlight.js theme. A few of them:
| Light | Dark |
|---|---|
github.css (default) | github-dark.css |
atom-one-light.css | atom-one-dark.css |
vs.css | vs2015.css |
xcode.css | monokai.css |
ascetic.css (black and white) | nord.css, tokyo-night-dark.css |
The $schema autocomplete lists all of them. Dark themes also darken the code block background.
Code is coloured only when the block names its language after the opening backticks, for example python. Set "highlight": false to print all code in one colour.
Page breaks
Put one of these lines where a new page should start. They all do the same:
<div class="page-break"></div>
<!-- page-break -->
<hr class="page-break">Other accepted names for the classes en comments are: page, pagebreak, page_break, new-page, newpage and break-page.
A plain <div style="page-break-after: always"></div> works too.
To break before an element instead, use <div class="page-break-before"></div>.
These work even when include_default_styles is off. For more control, use CSS in your own stylesheet:
h1 { break-before: page; } /* each h1 starts a new page */
h2 { break-after: avoid; } /* keep a heading with its text */
table, pre, figure { break-inside: avoid; }A table of contents made with [[toc]] is followed by a page break. See Content.
Paper size, orientation and margins: see All settings.
