# Markdown to PDF

> For AI agents: a documentation index is available at https://makespdf.com/llms.txt — every docs page also has a markdown twin (append .md to the page URL), including this one: https://makespdf.com/docs/markdown.md

Send GitHub Flavored Markdown, get an accessible, archival-grade PDF back. No AI
call, no template — pure computation, typically under 200ms. This page covers
what's supported, how images are handled, and the gotchas worth knowing before
you wonder why something didn't come out the way you expected.

## Calling it

Markdown rendering is available through the `POST /api/v1/md` endpoint, the
`makespdf` CLI (`makespdf md report.md -o report.pdf`), and the VS Code and
Obsidian plugins. The endpoint returns the PDF binary by default, or JSON
metadata when you send `Accept: application/json`.

```bash
curl -X POST https://makespdf.com/api/v1/md \
  -H "Authorization: Bearer mpdf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Hello\n\nSome **bold** text."}' \
  -o output.pdf
```

See the [API Reference](https://makespdf.com/docs/api) for the full request/response
contract, authentication, and rate limits. Markdown text is capped at 200KB
(roughly 50,000 words) — inline `data:` images don't count toward it, and the
request body is capped at 15MB. Any single *block* (lines with no blank line
between them) is capped at ~8MB, because that is where the parser runs out of
stack. A blank line splits a paragraph or image block and renders the same
content — but it stays inside a fenced code block, and between table rows it
splits one table into two.

**Zed.** The `makespdf` CLI plugs into Zed's task runner: add an entry to
`.zed/tasks.json` (project) or `~/.config/zed/tasks.json` (all projects).
Install and authenticate first with `npm i -g @makespdf/cli`, then
`makespdf login` (or `makespdf auth <key>` for headless use).

```json
[
  {
    "label": "makesPDF: export Markdown to PDF",
    "command": "makespdf md \"$ZED_FILE\" -o \"$ZED_DIRNAME/$ZED_STEM.pdf\"",
    "reveal": "no_focus",
    "hide": "on_success"
  }
]
```

Run it from the task picker (`task: spawn`), or bind it to a key in
`keymap.json` under a `bindings` map:
`["task::Spawn", { "task_name": "makesPDF: export Markdown to PDF" }]`. The PDF
is written beside the Markdown file. The output path uses Zed's `$ZED_DIRNAME`
and `$ZED_STEM` variables, since Zed's variable substitution does not support
shell parameter expansion.

## Supported Markdown

The renderer follows the GitHub Flavored Markdown spec. The following all render
as you'd expect:

**Text & structure**

- Headings (`#` through `######`), paragraphs, horizontal rules
- Bold, italic, strikethrough, inline code, links. Link targets are limited to http, https and mailto (plus internal #anchor links); any other scheme is drawn as plain text without a clickable link.
- Highlight (`<mark>` or Obsidian `==highlight==`) — yellow background span
- Ordered, unordered and nested lists; task lists (`- [x]` / `- [ ]`)
- Blockquotes and GFM alerts (`> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`,
  `> [!WARNING]`, `> [!CAUTION]`), drawn with the type's icon. Text after
  the marker on the same line is a title shown in place of the type name:
  `> [!NOTE] Before you start`
- Footnotes (`[^1]` references with end-of-document definitions)
- Superscript (`<sup>`) — the run renders at 75% of the surrounding size,
  raised 0.33em, on the same baseline and without changing the line height
- A safe subset of inline HTML:
  `<em> <strong> <b> <i> <del> <s> <mark> <sup> <img>`

**Code**

- Fenced code blocks with syntax highlighting for 26 languages (monospace font,
  GitHub-inspired colour theme)

**Tables**

- GFM tables with per-column alignment
- HTML `<table>` blocks rendered as real tables — `<thead>` / `<tbody>` / `<tfoot>`,
  `<tr>`, `<th>` / `<td>`, `colspan`, `rowspan`, `align`, `valign` (a cell
  without one is centred vertically, as in a browser), a
  `style="background-color: …"` cell background, and cell content that mixes
  inline markdown, inline HTML and `<br>`. Table HTML the renderer cannot draw
  — a nested table, a caption, a grid too wide for the page — falls back to
  stacked cell text with an `html-table-fallback` layout warning instead of
  failing the render
- Per-table HTML-comment directives placed on the line before the table:
  `<!-- borderless -->`, `<!-- full-width -->`, `<!-- columns: stretch fit -->` —
  combinable as `<!-- full-width borderless columns: stretch fit -->`, and they
  apply to GFM and HTML tables alike

**Diagrams & graphics**

- Mermaid diagrams (```mermaid blocks) rendered as native PDF vector graphics —
  flowchart, sequence, class, state, gantt, pie, ER, gitgraph, xychart-beta,
  timeline, quadrantChart, sankey-beta, treemap-beta, mindmap, journey,
  radar-beta, requirementDiagram, C4Context/C4Container, kanban and block-beta —
  with worked, rendered examples per diagram type in the
  [Mermaid syntax reference](https://makespdf.com/mermaid)
- Mermaid accessibility directives — `accTitle: …` and `accDescr: …`, or the
  multi-line `accDescr { … }` block — become the diagram's alt text in the tagged
  PDF; `POST /api/v1/md/validate` warns when a diagram has neither
- Graphviz DOT diagrams (```dot or ```graphviz blocks) rendered as native PDF
  vectors — node shapes, fill colours, clusters, edge labels and edge styles. An
  optional `---` front matter header carries the figure's `alt` and an optional
  `width` (e.g. `60%`); DOT attributes that cannot be honoured are listed in a
  single layout warning instead of being silently dropped
- Declarative graphs (```graph blocks) — a strict YAML schema of `nodes`,
  `groups` and `edges` for data-shaped diagrams such as org charts, with
  `layout: layered | tree`, direction, per-node shapes and colours, and edge
  `style`/`arrow`. Unknown keys and dangling references are errors;
  `POST /api/v1/md/validate` reports them as `graph-invalid`, and warns with
  `graph-missing-description` when a graph block has no `alt`
- A diagram block that cannot be rendered (Mermaid, DOT or `graph`) never fails
  the document: it is shown as its source in a code block, and a
  `diagram-render-failed` entry with the parse error is added to `layoutWarnings`
  on JSON responses and named by the `X-Layout-Warnings` header on the PDF
  response
- SVG images drawn as native vectors (shapes, paths, text, transforms, opacity);
  raster images embedded directly

## Images

Both Markdown image syntax (`![alt](url)`) and HTML `<img>` tags are supported.
This is the part most worth understanding up front, because a misreferenced
image fails quietly.

> **Image URLs must be absolute and publicly reachable.** Rendering happens on
> our servers — there is no repository, working directory, or local filesystem in
> scope. An image source has to be something the server can fetch on its own:
> `https://` (or `http://`) URLs, or inline `data:` URIs.

**What works**

- Absolute URLs — `https://example.com/logo.png`
- Inline data URIs — `data:image/png;base64,…` (including
  `data:image/svg+xml,…`)
- Formats: PNG, JPEG, GIF, WebP, and SVG

**What does not work**

- Relative paths — `./images/logo.png`, `../assets/logo.png`,
  `/static/logo.png`. These resolve against a local checkout that the server
  doesn't have. This is the single most common surprise when rendering a README
  or doc straight from a repository.
- `file://` URLs and any other non-HTTP scheme
- URLs pointing at private or internal hosts (localhost, link-local, RFC 1918
  ranges) — blocked for security

> **When an image can't be fetched, it is silently omitted.** The renderer
> collapses it to zero size — no placeholder box, no error, no warning in the
> response. The surrounding text simply closes up around where the image would
> have been. If an image you expected is missing from the PDF, an unreachable URL
> is the first thing to check.

**Limits**

| Limit | Value |
| --- | --- |
| Images per document | 20 (extras are skipped) |
| Size per image | 5 MB |
| Fetch timeout per image | 5 seconds |

An image that exceeds the size limit, times out, returns a non-image content
type, or is beyond the count cap is omitted the same way an unreachable one is.
SVGs render as native vectors but don't yet support gradients or filters — those
elements are dropped.

**Rendering a repo README.** To render a document that uses relative image paths,
either rewrite the paths to absolute URLs (for a GitHub repo, the
`https://raw.githubusercontent.com/<owner>/<repo>/<branch>/<path>` form works
well), or inline the images as `data:` URIs before sending the Markdown.

## Options

Options can be set in the request body under `options`, or as YAML frontmatter
at the top of the Markdown itself. When both are present, an explicit body option
wins; otherwise frontmatter wins; otherwise the runtime default applies.

| Option | Values |
| --- | --- |
| `pageSize` | A3, A4 (default), A5, Letter, Legal |
| `fontFamily` | Inter (default), NotoSans |
| `fontSize` | Base size in points, 6–24 (default 10) |
| `margins` | [top, right, bottom, left] in points (default [40, 40, 40, 40]) |
| `theme` | github (default) — GitHub styling with h1/h2 underlines and zebra tables; default — heavier headings, no underlines |
| `title` | PDF document title (max 200 chars) |
| `author` | PDF document author (max 200 chars) - written to `/Author` and `dc:creator` |
| `subject` | One-line description of the document (max 200 chars) - written to `/Subject` and `dc:description` |
| `keywords` | Topic keywords - an array of strings, or one comma-separated string (max 500 chars). Written to `/Keywords` and `pdf:Keywords` |
| `pageNumbers` | Footer page numbers - `page-n-of-total` ("Page 3 of 12"), `n-of-total` ("3 / 12"), or `n` ("3"). Omit for no page numbers |
| `pageNumberPosition` | Footer alignment when `pageNumbers` is set - `left`, `center`, or `right` (default) |

## Other things to know

**Page breaks keep related content together.** The layout engine treats headings,
code blocks, and GFM alerts as units that shouldn't be split across a page
boundary. A heading is pushed to the next page rather than stranded at the bottom
of one; a code block that doesn't fit moves wholesale to the next page; and a
single-line label ending in a colon stays with the code block it introduces. As a
result you may occasionally see white space at the foot of a page — that's the
renderer keeping a block intact, not a bug.

**Accessibility is built in.** Every PDF is PDF/A-2A + PDF/UA-1 dual-compliant: a
tagged structure tree, embedded fonts, and Unicode text extraction, with no
configuration needed. Image alt text from `![alt](…)` is preserved on the figure
structure element. You can check a document's heading hierarchy and alt-text
coverage ahead of time with `POST /api/v1/md/validate`.

**Script support.** Latin scripts and CJK (Chinese, Japanese, Korean) render out
of the box — Chinese, Japanese and Korean text draws with an embedded Noto Sans
fallback, no font upload needed. Pick the script with the `lang` option (a BCP 47
tag such as `"ja"`, `"zh-Hant"` or `"ko"`): it also writes the PDF's `/Lang`,
which accessibility checkers want. Without a `lang`, the text decides — any kana
means Japanese, any Hangul means Korean, and Han-only text is simplified Chinese.
Non-Latin European scripts (Cyrillic, Greek, Vietnamese, Georgian, Armenian) need
a custom font supplied through the template APIs. Right-to-left and complex-script
text (Arabic, Hebrew, Persian, Indic, Thai, Khmer) is not yet supported and won't
render correctly.

## Related

- [API Reference](https://makespdf.com/docs/api) — full `/api/v1/md` contract,
  authentication, rate limits
- [Getting Started](https://makespdf.com/docs/getting-started) — sign-up, API keys, your
  first render
- [Generate](https://makespdf.com/generate) — VS Code, Obsidian, AI chat, library templates
