Docs menu
MarkdownWhat renders
What renders
The converter's markdown dialect: CommonMark plus the GitHub extensions people actually use, rendered natively.
The dialect supports CommonMark and GitHub extensions, with paragraph-wide line breaking and font shaping. Automatic hyphenation uses your document language. Every feature below has a runnable example you can download as-is or open in the editor.
Blocks#
- Headings
#through######plus setext (===/---), auto-bookmarked in the PDF outline. - Table of contents: write
[TOC]on a line of its own where the contents belong. It lists every heading down to the third level with its page number, leader dots and a link to the page.[[_TOC_]]works the same. See the headings example. - Page break: write
\newpageon a line of its own. The next block starts on a new page; two breaks in a row make one. Inside code it stays text. Other Markdown viewers show it as plain text. - Paragraphs with typographic quotes, dashes, and ellipsis (opt-out:
smart_typography) and hard line breaks (two trailing spaces or a backslash). - Blockquotes with nesting, including GitHub alert syntax (
> [!NOTE],[!TIP],[!IMPORTANT],[!WARNING],[!CAUTION]). - Fenced blocks between
:::lines, as other Markdown tools write them, at the top level of the document.:::note,:::tip,:::info,:::important,:::warning,:::cautionand:::dangerdraw a callout like an alert; give it a title with:::tip Titleor:::tip[Title]. Any other block, such as::: {lang=ar dir=rtl}, shows its content without the markers;langsets the language of its content anddirits direction. A line of colons closes the innermost block; more colons on the outer block help reading. - Fenced code blocks with syntax highlighting for 23 languages, among them c, json, bash, python, javascript, rust, swift, go, java, html, css, sql, yaml, toml, c#, php, powershell, ruby, lua, dart, r, perl, vb.
- Lists: bullets (two-space nesting), ordered (auto-renumbered), task lists (
- [ ]/- [x]→ clickable PDF checkboxes), definition lists. - Tables with column alignment (
|:---:|) and headers that repeat across page breaks. Grid tables, drawn with+---+borders, are not supported: write them as pipe tables. - Horizontal rules (
---). - YAML front matter, stripped from the body and mapped to PDF document metadata (
title:,author:). Without a title, the PDF takes the text of the first level-1 heading (#), then the file name you give it, elselegivel.com documentand the render time in UTC. Every PDF names legivel.com as the application that made it.theme: darkortheme: lightsets the page theme for every render of the document.format:,width:,height:andmargin:set the page (Page format, size and margins).archive:,accessible:andmathml:ask for PDF standards, andaccessible: falseturns the tags off unless the request sendsaccessible(Standards and warnings).
Inline#
- Bold, italic,
code,strikethrough, ==highlight==, kbd, sup, sub; they nest freely. - Links: inline
[text](url), reference[text][label], autolinks<https://…>. Internal anchors ([text](#heading)) become real PDF GoTo jumps. - Footnotes:
[^1]references collect as numbered footnotes at the end of the document. - Emoji: color emoji from a bundled COLR font, plus
:rocket:-style shortcodes for ~140 common names (opt-out:emoji). - Images: base64 data-URI
render inline (opt-out:images). Images linked from the web are loaded for signed-in accounts with documents left, each time you convert, and never stored; see how we load images. An SVG image may show images it links to; they load the same way. It may not refer to other files: a<use>, stylesheet,@import, font orurl()that points outside the SVG. Such an SVG counts as an image that could not be loaded. Write each image as a web address or a data URI: a file path such asimages/chart.pngdoes not load, because a request carries only the Markdown. - HTML: a block of HTML on its own lines renders as HTML, with its inline styles and a
<style>element whose rules apply to that block only; tables with merged cells,<div>and<section>layouts and inline SVG work this way. Inline HTML in a paragraph renders with its styles too. Opt-out:html_blocks; with it off, blocks print as code and only<b> <i> <u> <s> <sup> <sub> <kbd> <mark> <br>still render. See the HTML blocks example.
Math#
Math is written in LaTeX notation and typeset natively, as vector glyphs: $…$ inline and $$…$$ on its own line (opt-out: math). Fractions, radicals, sums and integrals, matrices (pmatrix, bmatrix, vmatrix), piecewise cases, aligned derivations, arrays, delimiters that grow to fit, and braces over and under terms. Formulas work in headings, lists, tables, quotes and footnotes; see the math examples.
In an accessible PDF, each formula also carries its MathML, the web standard for math. Assistive tools that read MathML get the structure of the formula, not only its picture. With accessible: false, the formula is a picture of vector glyphs and nothing more. See accessible PDFs.
Diagrams and charts#
```mermaid fences render as native vector drawings where they are written, scaled into the text column. The first line of the fence selects one of 33 kinds:
- Flow and structure:
flowchart,swimlane,block,architecture,agentflow. - Software:
sequenceDiagram,zenuml,classDiagram,stateDiagram,erDiagram,C4Context,requirementDiagram,packet,gitGraph,usecase,eventmodeling,railroad. - Planning and analysis:
gantt,timeline,journey,kanban,mindmap,treeView,ishikawa,cynefin,wardley. - Charts:
pie,xychart,quadrantChart,radar,sankey,treemap,venn.
graph is the same as flowchart; the C4 family also takes C4Container, C4Component, C4Dynamic and C4Deployment; railroad diagrams take a grammar in ABNF, EBNF or PEG (railroad-abnf, railroad-ebnf, railroad-peg). A fence that does not parse prints as a code block, so a typo never breaks the document. With mermaid off, every fence prints as code.
Chart settings: pie charts take the colors pie1 to pie12; bar and line charts (xychart) take width, height and plotColorPalette. Set them under config: in the fence's front matter, or in an %%{init: …}%% line; plotColorPalette is read from the front matter only. primaryColor does not recolor a pie.
Diagram pages are opt-in (mermaid_appendix). Each diagram then gets a page of its own after the document body, an A size from A4 to A0, landscape or portrait, whichever fits it at natural scale. In the text the fence leaves a link (Diagram 3: Pipeline Overview →); the page is captioned with a link back to that spot, and each diagram is a bookmark in the PDF outline. A diagram without a title is named after its kind. This keeps a very wide flowchart readable instead of squeezing it into the text column. See the diagram and chart examples.
Barcodes and QR codes#
A ```barcode fence becomes a native vector barcode (opt-out: barcode). The body is key: value lines; type and data are required.
```barcode
type: qr
data: https://example.com/menu
module-shape: rounded
ec: H
width: 220
```21 types: QR, Micro QR, rectangular Micro QR, EAN-13, EAN-8, UPC-A, UPC-E, Code 128 (GS1-128 with gs1: true), Code 39, Code 93, Codabar, ITF, ITF-14, MSI, GS1 DataBar (omnidirectional, limited, expanded), Data Matrix, PDF417, Aztec and MaxiCode. QR codes take module and corner shapes, colors, gradients, a logo and the error-correction level; linear codes take label position, text, colors and size. An option a type cannot use is ignored with a warning; data the type rejects prints as a code block with the reason. See the barcode examples.
SVG graphics#
A ```svg fence renders as native vector art (opt-out: svg). The body is a full SVG document, bare path data that takes the text color, or key: value lines (d, fill, stroke, stroke-width, width, …). Gradients, clip paths, markers, <use> symbols and text on a path are drawn. A body that is not valid SVG prints as a code block. See the SVG examples.
Typography#
Lines are broken across the whole paragraph, not one line at a time, so the spacing stays even. Two hyphens become an en dash (–), three an em dash (—) and three dots an ellipsis; code is left as typed. Mixed-direction scripts, such as Hebrew and Arabic, and Japanese and Chinese line breaking are supported. Thai text without spaces breaks between words, with or without a language. Fonts cover Latin, Greek, Cyrillic, Devanagari, Chinese, Japanese, Korean, Arabic, Hebrew, Thai, Khmer, Myanmar, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugu, Kannada, Malayalam, Georgian, Armenian, Ethiopic, Coptic and color emoji. Chinese takes simplified shapes for a zh-CN document and traditional shapes for a zh-TW one; without a Chinese language, characters shared with Japanese take Japanese shapes. Choose light or dark pages with the editor's theme control, or with theme: in front matter, which wins over the control.
Language and hyphenation#
Automatic hyphenation is enabled by default. It works only when a document language is specified and matching language rules are available. Without a language, words wrap as before, without automatic hyphenation. Hyphenation never uses a language detected from the text or taken from your browser settings.
The PDF also records the language as its document language, so screen readers know which language to read. A language without hyphenation rules is recorded too. Without a language, the PDF records the main language of the text, which the converter detects, or en when the text does not show it clearly. That language serves the tags only; see document language. With accessible: false the PDF names none.
Set language in the JSON render request or in Markdown front matter. Use a language tag such as en-US, en-GB, de or ro. The editor's output settings provide the same controls.
---
language: en-GB
hyphenation: true
---
Your document starts here.To disable automatic hyphenation, set features.hyphenation to false in JSON, or hyphenation: false in front matter. Existing hyphens and author-inserted soft hyphens remain available. Code and literal URLs are excluded from automatic hyphenation.
{
"markdown": "# Report\n\nYour document starts here.",
"language": "en-GB",
"features": { "hyphenation": false }
}Each explicit request setting overrides its front-matter value. An omitted setting uses front matter, then the default. An unsupported language leaves automatic hyphenation inactive when the setting is omitted. Explicitly enabling it for an unsupported language returns 400 invalid_request. A missing language always leaves automatic hyphenation inactive.
Supported hyphenation language tags (77)
Tags are case-insensitive. Use a listed tag or alias; other regional variants do not automatically select a dictionary.
af, as, be, bg, ca, cop, cs, cu, cy, da, de-1901, de-1996, de-CH-1901, el-monoton, el-polyton, en-GB, en-US, eo, es, et, eu, fi-x-school, fi, fr, fur, ga, gl, grc, gu, hr, hsb, hu, hy, ia, id, is, it, ka, kmr, kn, la-x-classic, la-x-liturgic, la, lt, lv, mk, ml, mn-Cyrl, mr, mul-Ethi, nl, nn, oc, or, pa, pi, pl, pms, pt, rm, ro, ru, sa, sh-Cyrl, sh-Latn, sk, sl, sq, sr-Cyrl, sv, ta, te, th, tk, tr, uk, zh-Latn-pinyin
These aliases select a listed dictionary:
| Tag you send | Dictionary used |
|---|---|
en | en-US |
en-UK | en-GB |
de, de-DE, de-AT | de-1996 |
fr-FR, fr-CA | fr |
es-ES, es-MX | es |
pt-PT, pt-BR | pt |
ro-RO | ro |
ru-RU | ru |
uk-UA | uk |
Page format, size and margins#
Pages are A4 with 54 pt margins unless you set them. Write the page settings under one page key in the front matter. size takes a paper name: A0 to A10, B0 to B10, C3 to C6, DL, JIS-B4, JIS-B5, Letter, Legal, Tabloid, Ledger, Executive, Statement or Half-Letter. Case does not matter. Add landscape or portrait after the name to turn the page. B sizes are ISO; use JIS-B5 for the Japanese B5.
---
page:
size: A5 landscape
margin: 15mm 20mm
---
Your document starts here.For any other page, write the width and the height as two lengths. Write a length as a number and a unit: pt, mm, cm or in, such as 210mm, 21cm or 8.5in.
---
page:
size: 100mm 150mm
---margin follows the CSS shorthand, with spaces or commas between values: one value for every side; two for top and bottom, then left and right; three for top, then left and right, then bottom; four for top, right, bottom and left. Each value is a length in pt, mm, cm or in. Without margin, a page under 152 mm on its short side gets smaller margins, an eighth of that side.
---
page:
margin: 20mm 15mm 25mm 15mm
---The JSON render request and the MCP tool take the same page object.
{
"markdown": "# Report\n\nYour document starts here.",
"page": { "size": "Letter", "margin": "1in 0.75in" }
}Request settings override front matter key by key: a margin in the request replaces the front matter margin and keeps the front matter size. Each side of the page must be between 10 mm and 2 m, and the margins must leave at least half of the page width and height. An unknown key under page, an unknown name or unit, or a value out of these limits returns 400 invalid_request with a message that names the problem. Diagram pages keep their own sizes.
The older flat keys still work, at the top level of the front matter or the request: format (or papersize, its name in Quarto), width and height, margin, header, footer and page-numbering (page_numbering in a request). A key under page wins over its flat key. A front matter format that names no paper, such as Quarto's format: html, leaves the page as it is.
Header, footer and page numbers#
Every page has a footer with the page number, 1 / 12, in the center. Set header and footer under page to put your own text at the top and bottom of every page. One text goes in the center. For more than one position, write left, center and right on indented lines. none or false removes the header or the footer. true asks for the default: no header text, and the page number in the footer.
Each text is inline Markdown: bold, italic, code and strikethrough. Links keep their color but are not clickable in the header and footer. For several lines, write | after the key and the lines indented under it, as YAML does.
---
title: Annual report
author: Finance office
page:
header:
left: "**{title}**"
right: |
Acme Ltd
*{author}*
footer:
left: "*Confidential*"
right: acme.example
---Four placeholders work in any position:
{page}: the number of the page.{pages}: the number of the last page.{title}: thetitlefrom front matter; empty without one.{author}: theauthorfrom front matter; empty without one.
Any other text in braces returns 400 invalid_request. In YAML, put a value that starts with { or * in quotes, as above. Each position is at most five lines of at most 100 characters. The header sits in the middle of the top margin and the footer in the middle of the bottom margin, in small gray text. A header or footer of several lines widens its margin to fit; it must leave at least half of the page height for the text.
Page numbers
numbering sets the page number. A short value is one of three kinds:
- A text with placeholders, such as
Page {page} of {pages}. - A number style, as in Quarto:
1for 1, 2, 3 (the default),aorAfor letters,iorIfor roman numerals. The style applies to{page}and{pages}in the header and the footer. falseornonefor no page numbers.
---
page:
numbering: Page {page} of {pages}
---To set more than one of these, write numbering with indented keys:
style: the number style,1,a,A,iorI.text: the text, such asPage {page} of {pages}.position:headerorfooter, thenleft,centerorright, such asfooter right. One word alone keeps the default for the other. The default isfooter center.start: the number of the first page, from 1 to 9999. A three-page document that starts at 5 reads5 / 7to7 / 7.
With a start other than 1 or a style other than 1, PDF viewers show the same numbers in their page list. The watermarked download is made of page images and keeps the printed numbers only.
---
page:
numbering:
style: i
text: Page {page} of {pages}
position: footer right
start: 3
footer:
left: Acme Ltd
---A header or footer text at the position of the page number replaces the number. A footer with only left or right keeps the number in the center.
Title page
first: false removes the header, the footer and the page number from the first page only, as on a title page.
---
title: Annual report
page:
first: false
header: "{title}"
---The JSON render request and the MCP tool take the same keys under page. A header or footer is a string, true, false, or an object with left, center and right. The style 1 may be the number 1. start is a number and first is true or false. Each request setting replaces its front matter value.
{
"markdown": "# Report\n\nYour document starts here.",
"page": {
"header": { "left": "**Acme Ltd**", "right": "Annual report" },
"numbering": { "text": "Page {page} of {pages}", "position": "footer right" },
"first": false
}
}Accessible PDFs#
An accessible PDF is tagged: it carries a structure that screen readers follow. Headings, paragraphs, lists with their numbering, tables with their header cells, links, block quotes, code blocks, footnotes and table of contents entries are tagged. HTML blocks are tagged by element. Images carry their alt text, diagrams a description in words, SVG graphics their title, description or text, and formulas their LaTeX as a text alternative. Each formula also carries its MathML, for screen readers that read math. A hyphen added at a line break is marked as a soft hyphen, so screen readers read the whole word. Images with empty alt text, headers, footers, page numbers, rules and backgrounds are marked as decoration, so screen readers skip them.
A diagram's description comes from the diagram itself. Write it with Mermaid's accDescr line, or accTitle for a short one; a diagram title also serves. Without any of them, the description names the kind of diagram and lists its labels in reading order. Diagram code is never read aloud.
```mermaid
flowchart LR
accTitle: Meter reading flow
accDescr: Readings go from the meter to the bill, through a check when they look wrong.
A[Meter] --> B{Check} --> C[Bill]
```Every PDF is accessible by default, and claims PDF/UA-2 when the document meets it; see Standards and warnings. Without a document language, the converter detects the main language of the text for the tags, or takes en. For an untagged file, which is the smallest, set features.accessible to false, or turn off Accessible PDF in the editor. The watermarked download is made of page images and carries no tags.
{
"markdown": "# Report\n\nYour document starts here.",
"features": { "accessible": false }
}