Skip to content

Advanced: settings, options and details for people who want full control. Most people only need Studio.

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:

json
{
  "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:

ValueDescription
cleanDefault. GitHub-style, neutral.
reportSerif headings, strong title rule. Business reports.
academicSerif body, justified, minimal colour, 25 mm margins, black and white code.
compactDense and small, 10 mm margins. More text per page.
technicalFramed 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:

json
{
  "look": "technical",
  "accent_color": "#2e7d32"
}
LookWhat changes
technicalthe rule under the title, section titles, the bar beside code blocks, inline code and table headers (a light tint)
reportthe 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 ​

KeySets
fontthe text font, from a preset name
heading_fontthe title font (h1 to h6), from a preset name
font_familythe text font, as a CSS font list
heading_font_familythe 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:

json
{
  "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 ​

json
{
  "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:

css
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):

  1. The built-in stylesheet.
  2. The maths stylesheet, when math is on.
  3. The code colour theme.
  4. Your stylesheet, or the look's stylesheet.
  5. The fonts you chose.

Start from a blank page ​

json
{
  "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:

LightDark
github.css (default)github-dark.css
atom-one-light.cssatom-one-dark.css
vs.cssvs2015.css
xcode.cssmonokai.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:

markdown
<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:

css
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.

Released under the MIT License.