PDF | MarkupGo

Generating PDFs

Before generating a PDF, let's take a look at the options available for the PDF generation.

PDF Options

Each PDF route accepts the following form fields inside the options object:

Key	Description	Default
`header`	The header HTML content. See	-
`footer`	The footer HTML content. See	-
`properties`	The PDF properties. Please see the Properties section.	-
`emulatedMediaType`	The emulated media type.	-
`pdfUA`	Enable PDF for Universal Access for optimal accessibility	`false`
`waitDelay`	The wait delay in milliseconds.	-
`waitForExpression`	The wait for expression.	-
`userAgent`	The user agent.	-
`extraHttpHeaders`	The extra HTTP headers.	-
`failOnHttpStatusCodes`	The HTTP status codes to fail on.	-
`failOnConsoleExceptions`	Whether to fail on console exceptions.	`false`
`skipNetworkIdleEvent`	Whether to skip the network idle event.	`false`
`metadata`	The metadata.	-
`cookies`	The cookies.	-

PDF Options

  type PdfOptions = {
    header?: string;
    properties?: Properties;
    pdfUA?: boolean;
    emulatedMediaType?: 'screen' | 'print';
    waitDelay?: string;
    waitForExpression?: string;
    userAgent?: string;
    extraHttpHeaders?: Record<string, string>;
    failOnHttpStatusCodes?: number[];
    failOnConsoleExceptions?: boolean;
    skipNetworkIdleEvent?: boolean;
    metadata?: Record<string, string>;
    cookies?: Cookie[];
  }

PDF Properties

The properties object contains the following fields:

Key	Description	Default
`singlePage`	Whether to print the document as a single page. Best used for render all pages in a single page.	`false`
`size`	The size of the document.	-
`size.width`	The width of the document in millimeters.	`816`
`size.height`	The height of the document in millimeters.	`1056`
`margins`	The margins of the document.	-
`margins.top`	The top margin in millimeters.	`0`
`margins.bottom`	The bottom margin in millimeters.	`0`
`margins.left`	The left margin in millimeters.	`0`
`margins.right`	The right margin in millimeters.	`0`
`preferCssPageSize`	Whether to prefer the CSS page size.	`false`
`printBackground`	Whether to print the background.	`false`
`omitBackground`	Whether to omit the background.	`false`
`landscape`	Whether to print the document in landscape mode.	`false`
`scale`	The scale of the document.	`1`
`nativePageRanges`	The native page ranges.	-
`nativePageRanges.from`	The starting page number.	-
`nativePageRanges.to`	The ending page number.	-

Properties

  type Properties = {
    singlePage?: boolean;
    size?: {
      width: number;
      height: number;
    };
    margins?: {
      top: number;
      bottom: number;
      left: number;
      right: number;
    };
    preferCssPageSize?: boolean;
    printBackground?: boolean;
    omitBackground?: boolean;
    landscape?: boolean;
    scale?: number;
    nativePageRanges?: {
      from: number;
      to: number;
    };
  }

The rules regarding the printBackground and omitBackground form fields are the following:

If printBackground is set to false, no background is printed.
If printBackground is set to true:
- If the HTML document has a background, that background is used.
- If not:
  - If omitBackground is set to true, the default background is transparent.
  - If not, the default white background is used.

Example Options

const ExamplePdfOptions = {
  properties: {
    size: {
      width: 210,
      height: 297
    },
    margins: {
      top: 10,
      bottom: 10,
      left: 10,
      right: 10
    }
  },
  pdfUA: true,
  emulatedMediaType: 'print',
  waitDelay: '2s',
  waitForExpression: 'document.querySelector("h1") !== null',
  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3',
  extraHttpHeaders: {
    'X-My-Custom-Header': 'My custom value'
  },
  failOnHttpStatusCodes: [404, 500],
  failOnConsoleExceptions: true,
  skipNetworkIdleEvent: true,
  metadata: {
    Creator: 'MarkupGo',
    Copyright: '2025'
  },
  cookies: [
    {
      name: 'MY_COOKIE',
      value: 'my_cookie_value',
      domain: 'example.com',
    }
  ],
};

Header & Footer

Every PDF document can have a header and footer. The header and footer can be set using the header and footer fields in the options object. Each of them has to be a complete HTML document:

<html>
<head>
  <style>
  body {
    font-size: 12px;
    margin: auto 20px;
  }
  </style>
</head>

<body>
  <p><span class="pageNumber"></span> of <span class="totalPages"></span></p>
</body>
</html>

The following classes allow you to inject printing values:

date - formatted print date.
title - document title.
url - document location.
pageNumber - current page number.
totalPages - total pages in the document

There are some limitations:

No JavaScript.
The CSS properties are independent of the ones from the HTML document.
footer.html CSS properties override the ones from header.html.
Only fonts installed in the Docker image are loaded - see the fonts configuration section.
Images only work using a base64 encoded source - i.e., data:image/png;base64, iVBORw0K....
background-color and color CSS properties require an additional -webkit-print-color-adjust: exact CSS property in order to work.
Assets are not loaded (i.e., CSS files, scripts, fonts, etc.).
Background form fields do not apply.

Metadata

Not all metadata are writable. Consider taking a look at https://exiftool.org/TagNames/XMP.html#pdf for an (exhaustive?) list of available metadata.

When the page relies on JavaScript for rendering, and you don't have access to the page's code, you may want to wait a certain amount of time to make sure Chromium has fully rendered the page you're trying to generate.

{
  "waitDelay": "3s"
}

Endpoint Structure

The /pdf endpoint generates a PDF from a URL, HTML, or a template. The endpoint accepts a JSON object with the source and options fields. The source field specifies the source of the document, and the options field specifies the PDF generation options. Please see the PDF Options section for more information.

Endpoint Structure

{
  source: UrlSource | HtmlSource | TemplateSource,
  options: PdfOptions
}

Getting buffer response

If you want to get the PDF as a buffer, you just need to put /buffer at the end of the URL.

fetch('/api/v1/pdf/buffer')

POST /pdf - From URL

The /pdf endpoint generates a PDF from a URL.

Request Body

The request body must contain a JSON object with the source field. Optionally, you can include the options field. Please see the PDF Options section for more information and default values.

Key	Description
`source.type`	This should be set to `url`.
`source.url`	The URL of the document.
`options`	The PDF options. Please see the PDF Options section.

Response

The response contains a task object. Please see the tasks section for more information.

Request

fetch('/api/v1/pdf', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    source: {
      type: 'url',
      data: 'https://example.com'
    },
    options: PdfOptions
  })
})

Response (Task)

{
  "id": "26a4ebd91745f1755df615ba",
  "url": "https://files.markupgo.com/tasks/66a4ebd91745f1755df615ba/1725057544064.pdf",
  "format": "pdf",
  "size": 1048576,
  "width": 210,
  "height": 297,
  "createdAt": "2026-06-21T10:00:00Z",
  "updatedAt": "2026-06-21T10:05:00Z"
}

POST /pdf - From HTML

The /pdf endpoint generates a PDF from HTML.

Request Body

The request body must contain a JSON object with the source field. Optionally, you can include the options field. Please see the PDF Options section for more information and default values.

Key	Description
`source.type`	This should be set to `html`.
`source.html`	The HTML content.
`options`	The PDF options. Please see the PDF Options section.

Response

The response contains a task object. Please see the tasks section for more information.

Request

fetch('/api/v1/pdf', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    source: {
      type: 'html',
      data: '<h1>Hello, World!</h1>'
    },
    options: PdfOptions
  })
})

Response (Task)

{
  "id": "26a4ebd91745f1755df615ba",
  "url": "https://files.markupgo.com/tasks/66a4ebd91745f1755df615ba/1725057544064.pdf",
  "format": "pdf",
  "size": 1048576,
  "width": 210,
  "height": 297,
  "createdAt": "2026-06-21T10:00:00Z",
  "updatedAt": "2026-06-21T10:05:00Z"
}

POST /pdf - From Template

Check out the editor

The /pdf endpoint generates a PDF from a template.

Request Body

The request body must contain a JSON object with the source field. Optionally, you can include the options field. Please see the PDF Options section for more information and default values.

Heads up!

The template options will override original template options that you have configured in the dashboard.

If you want to use the original template options, you should only provide the id field in the source.data object.

How to get the template ID?

Visit the template list in the dashboard and click copy on the template you want to use.

Key	Description
`source.type`	This should be set to `template`.
`source.data`	Template data.
`source.data.id`	The template ID.
`source.data.context`	The template context.
`source.data.html`	The template HTML content.
`source.data.css`	The template CSS content.
`source.data.libraries`	The template libraries.
`source.data.libraries.js`	The template JavaScript libraries.
`source.data.libraries.css`	The template CSS libraries.
`options`	The PDF options. Please see the PDF Options section.

Response

The response contains a task object. Please see the tasks section for more information.

Request

fetch('/api/v1/pdf', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    source: {
      type: 'template',
      data: {
        id: '666b3561fbaa04f6877e70b5',
        context: {
          name: 'John Doe'
        }
      }
    },
    options: PdfOptions
  })
})

Response (Task)

{
  "id": "26a4ebd91745f1755df615ba",
  "url": "https://files.markupgo.com/tasks/66a4ebd91745f1755df615ba/1725057544064.pdf",
  "format": "pdf",
  "size": 1048576,
  "width": 210,
  "height": 297,
  "createdAt": "2026-06-21T10:00:00Z",
  "updatedAt": "2026-06-21T10:05:00Z"
}

POST /pdf - From Markdown

The /pdf endpoint generates a PDF from a markdown file.

Request Body

The request body must contain a JSON object with the source field. Optionally, you can include the options field. Please see the PDF Options section for more information and default values.

Key	Description
`source.type`	This should be set to `markdown`.
`source.data.markdown`	The markdown content.
`source.data.padding`	The padding of the markdown content.
`source.data.css`	The CSS content.
`source.data.dark`	Whether to use a dark theme.
`options`	The PDF options. Please see the PDF Options section.

Response

The response contains a task object. Please see the tasks section for more information.

Request

fetch('/api/v1/pdf', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    source: {
      type: 'markdown',
      data: {
        markdown: '# Hello, World!',
        padding: 20,
        css: 'body { font-size: 18px; }',
      }
    },
    options: PdfOptions
  })
})

Response (Task)

{
  "id": "26a4ebd91745f1755df615ba",
  "url": "https://files.markupgo.com/tasks/66a4ebd91745f1755df615ba/1725057544064.pdf",
  "format": "pdf",
  "size": 1048576,
  "width": 210,
  "height": 297,
  "createdAt": "2026-06-21T10:00:00Z",
  "updatedAt": "2026-06-21T10:05:00Z"
}

Task

The tasks object in the MarkupGo API represents the result of an API activity triggered by generating documents or images.

Images

Generate images from URLs, HTML, or templates.