Pagecraft

markdown-to-pdf

Markdown to PDF

Set a Markdown file on paper, with its headings, lists, tables and code.

Reads
a Markdown file — text/markdown, text/x-markdown
Writes
one file — PDFs
Tool page
/markdown-to-pdf

Example

Turn a written note into a document with headings and lists.

Given

  • note.md — a Markdown file

From code

            import { loadDocument, runOperation } from '@pagecraft/core';

const note = await loadDocument({ bytes, name: 'note.md' });

const [output] = await runOperation('markdown-to-pdf', [note], {
  size: 'a4',
  fontSize: 11,
});

From a shell

            pagecraft markdown-to-pdf note.md --size a4 --font-size 11

What comes back

One PDF, containing “Quarterly report”.

This example is run by the test suite. If it stopped being true, the build would fail.

Options

filename--filename

string

Filename

What the PDF will be called.

Default: ''

size--size

string, one of

Page size

Default: 'a4'

  • source — The size and margins in the file, or A4 with 20mm where it names none.
  • a3 — A3
  • a4 — A4
  • a5 — A5
  • a6 — A6
  • b5 — B5
  • letter — Letter
  • legal — Legal
  • tabloid — Tabloid
  • executive — Executive
  • custom — Custom size

width--width

number

Width

Only when size is 'custom'.

Default: 210

height--height

number

Height

Only when size is 'custom'.

Default: 297

orientation--orientation

string, one of

Orientation

Default: 'portrait'

  • portrait — Portrait
  • landscape — Landscape

margin--margin

number

Margin

Default: 20

unit--unit

string, one of

Measured in

Default: 'mm'

  • mm — Millimetres
  • cm — Centimetres
  • in — Inches
  • pt — Points

fontSize--font-size

number (pt)

Text size

Default: 11

lineHeight--line-height

number

Line spacing

A multiple of the text size. 1.4 is what a book uses.

Default: 1.4

align--align

string, one of

Alignment

Default: 'left'

  • left — Even word spacing; an uneven right edge.
  • justify — Both edges flush; the word spacing stretches to do it.

font--font

string, one of

Typeface

Default: 'sans'

  • sans — Helvetica.
  • serif — Times.
  • mono — Courier.

fontFile--font-file

Uint8Array

Font file

A TrueType or OpenType font to set the text in. Needed for scripts the built-in fonts do not cover, unless the host supplies one.

What it cannot do

  • A practical CommonMark, not a conforming one: headings, paragraphs, emphasis, code, links, lists, block quotes, thematic breaks and GFM tables. Reference-style links, footnotes, definition lists and raw HTML are set as the text they are written as.
  • A picture is drawn only when the file carries its bytes, as a `data:` URI. A picture named by a path or an address cannot be fetched — the engine opens no files and no sockets — so its alt text is set in its place rather than a broken frame.
  • A table wider than the page has its columns squeezed together to fit rather than running off the edge, so a table of thirty columns will be unreadable at any page size.
  • Text is set in the standard fonts every reader already carries, so the file renders identically on a machine that has none of your fonts installed. Anything they cannot draw needs a font file, which is embedded and subsetted into the PDF with it.
  • A font file you supply is used for everything: bold, italic and monospaced text are all drawn in that one face rather than in a bold, italic or fixed-width cut of it. Code blocks and columns of figures lose their alignment as a result, so supply one only when the built-in fonts cannot draw your text.
  • Shaping and joining come from the font itself, and nothing reorders a line: text is drawn in the order it is given, so a line mixing right-to-left and left-to-right writing comes out in that order rather than in reading order.