# Docusaurus → 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/docusaurus.md

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

The integration is the
[@makespdf/docusaurus-plugin](https://www.npmjs.com/package/@makespdf/docusaurus-plugin)
npm package (dependency-free, Node 18+). MkDocs sites use the
[makespdf[mkdocs]](https://makespdf.com/docs/integrations/mkdocs) Python extra; Hugo sites
use the [Hugo recipe](https://makespdf.com/docs/integrations/hugo).

## Setup

```bash
npm install --save-dev @makespdf/docusaurus-plugin
export MAKESPDF_API_KEY=... # mint at https://makespdf.com/settings/api-keys?ref=docusaurus-plugin
```

```js
// docusaurus.config.js
module.exports = {
  plugins: [
    [
      "@makespdf/docusaurus-plugin",
      {
        docsDir: "docs",
        pdfOptions: { pageSize: "A4" }, // optional; forwarded as /md `options`
        // combined: true,             // also emit build/combined.pdf
      },
    ],
  ],
};
```

`npm run build` now also writes the PDFs. Versioned and translated docs are
separate source trees (`versioned_docs/`,
`i18n/<locale>/docusaurus-plugin-content-docs/current/`) — add one plugin
instance per tree you want PDFs for.

## Per-page front-matter

Same contract as the MkDocs extra, so both publishers behave identically:

```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:
`pdfOptions: { pdf_template: "<slug>" }` (page-level `pdf-template` wins).
Template-routed pages are excluded from the combined PDF.

## Combined mode

```js
{
  combined: true, // build/combined.pdf
}
{
  combined: "all-docs.pdf", // custom file name
}
```

## Behaviour

- `outDir` defaults to the build output; the docs tree is preserved.
- Markdown text over the 200KB server cap is rejected client-side (200,000
  characters, inline `data:` image payloads excluded — the same measurement the
  API applies, so a page it would render is never skipped locally). CJK-heavy
  pages are counted correctly: a character is a character, however many UTF-8
  bytes it takes. The request body, inline image bytes included, is capped at
  15MB by the API.
- API failures fail the build by default so a silently PDF-less deploy cannot
  slip through; `failOnError: false` warns per page instead.
- No offline rendering: every call is a hosted API call against
  `https://makespdf.com` (`MAKESPDF_BASE_URL` overrides the API host).

## Cost and limits

One billed render per page, plus one more when combined mode is on. Every render
is billed at 1 credit per 10 pages on success; failures deduct zero. No offline
rendering: every call is a hosted API call, so billing matches the web app and
CLI.
