# MkDocs → PDF with makesPDF

> 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/integrations/mkdocs.md

Render every MkDocs page to a sibling PDF via the
[makesPDF](https://makespdf.com/?ref=mkdocs-plugin) hosted API — one billed
[POST /api/v1/md](https://makespdf.com/docs/api?ref=mkdocs-plugin) render per
page, dropped next to the HTML output (`docs/guide.md` → `site/guide.pdf`).

The integration ships as the `mkdocs` extra of the single `makespdf` PyPI
package — there is no separate plugin project to install. Docusaurus sites use
the sibling
[@makespdf/docusaurus-plugin](https://makespdf.com/docs/integrations/docusaurus); Hugo
sites use the [Hugo recipe](https://makespdf.com/docs/integrations/hugo).

## Setup

```bash
pip install "makespdf[mkdocs]"
export MAKESPDF_API_KEY=... # mint at https://makespdf.com/settings/api-keys?ref=mkdocs-plugin
```

```yaml
# mkdocs.yml
plugins:
  - search
  - makespdf
extra:
  makespdf: { pageSize: A4 } # optional; forwarded as /md `options`
```

Build normally — `mkdocs build` now also writes the PDFs.

### Using a hooks file instead

MkDocs `hooks:` takes file paths, not `module:func` strings, so add a one-line
shim, e.g. `docs/hooks/makespdf_hook.py`:

```python
from makespdf.integrations.mkdocs_plugin import on_post_build_hook
```

and list it under `hooks:` in `mkdocs.yml`.

## Per-page front-matter

Skip a page, or route it through a saved template instead of the Markdown
endpoint:

```markdown
---
pdf: false # skip this page entirely (no PDF, no bill)
---
```

```markdown
---
pdf-template: invoice-classic # render via POST /api/v1/render instead of /md
customer: Ada # leftover keys + markdown/content/title become template `data`
---
```

A global default template for every page: `extra.makespdf.pdf_template`
(page-level `pdf-template` wins).

## Combined mode

One extra PDF with every markdown-rendered page concatenated:

```yaml
extra:
  makespdf: { pageSize: A4, combined: true } # -> site/combined.pdf
  # makespdf: { combined: all-docs.pdf }     # custom file name
```

`combined`, `combined_name`, and `pdf_template` are control keys — consumed
by the plugin, never sent as `/md` options. `combined_name` alone (without
`combined`) enables combined mode with that file name; explicit
`combined: false` still disables it. Template-routed pages are excluded from the
combined PDF (they render through `/render`, which cannot concatenate as
markdown).

## Cost and limits

One billed render per page, plus one more when combined mode is on. Markdown text
over the 200KB server cap fails per page (the API returns 400, the build fails
loudly — split the page). Inline `data:` images are excluded from that cap; the
request body is capped at 15MB. No offline rendering: every call is a hosted API
call, so billing matches the web app and CLI.
