Which Markdown does it read?

GitHub Flavored Markdown: tables, task lists, strikethrough and autolinks, plus footnotes and a front matter block. Heading ids follow GitHub’s rule, so links between headings work inside the PDF.

How large may the Markdown be?

Up to 1 MB of UTF-8 per request, and a stylesheet in settings.markdown.css up to 256 kB. Limits per plan are in the docs.

Where do pictures come from?

A picture named by a bare file name, such as logo.png, is a file of the workspace’s file library; a public https address or a data:image/ address works as well. formfeed pdf convert report.md sends the pictures beside the file along by itself.

Guide · curl

Convert Markdown to PDF in curl

A report your code writes, release notes or an answer from a model are Markdown already. This curl program sends a Markdown file to the Formfeed API as it is and saves the PDF, styled by the `document` theme and with raw HTML in the text shown as text, so it never runs.

Start for free Read the docs

Free plan with 100 units a month, no credit card

What you need

An API key. Create one in the app under API keys and export it as FORMFEED_API_KEY. A test key (ff_test_…) is right for trying things out. See the quick start.
curl. You need curl and jq.
A Markdown file. report.md next to the program, up to 1 MB. A sample is further down.

The program

The program reads report.md, posts it as markdown with bookmarks from its headings, waits for the result when the API answers 202, stops with the API’s message when something is wrong, and saves the PDF.

render.shShell

set -e

render=$(jq -Rs '{markdown: ., settings: {pdf: {outline: true}}}' report.md \
  | curl -sS https://api-eu.formfeed.dev/v1/renders \
      -H "Authorization: Bearer $FORMFEED_API_KEY" \
      -H "Content-Type: application/json" \
      --data-binary @-)

# not done within 60 seconds: the answer is 202 and the render goes on in the background;
# its result answers the same way until the render has finished
while printf '%s' "$render" | jq -e '.status == "queued" or .status == "rendering"' > /dev/null; do
  sleep 2
  render=$(curl -sS "https://api-eu.formfeed.dev/v1/renders/$(printf '%s' "$render" | jq -r .id)/result" \
    -H "Authorization: Bearer $FORMFEED_API_KEY")
done

# every error is a problem document (RFC 9457) with a title and a detail
url=$(printf '%s' "$render" | jq -r '.download_url // error(.title + ": " + (.detail // ""))')
curl -sS -o report.pdf "$url"
printf '%s' "$render" | jq -r '"\(.id) \(.page_count) page(s), \(.units) unit(s)"'

Run it

It prints the render’s id, the page count and the units it cost, and report.pdf lies next to the program.

Shell

export FORMFEED_API_KEY=ff_test_...
sh render.sh

What is particular about curl

jq writes the JSON. Building the body with jq instead of string concatenation means quotes, line breaks and umlauts in the input are escaped correctly.
Errors do not vanish. error(…) makes jq stop with the problem’s title and detail when the answer is a problem document, and set -e ends the script there, instead of handing an empty string to the next command.
The key goes to the API only. Every call to the API carries the Authorization header. The file comes from a signed URL that needs none, so the last curl fetches it without your key.

A Markdown file with a title

The front matter gives the PDF its title and author; without one the first heading is the title. A line \newpage starts a new page, and a link to a heading works inside the PDF:

report.mdMarkdown

---
title: Release notes 2.4
author: Fennlor Studio GmbH
---

# Release notes 2.4

## What is new

- Faster previews, see [the numbers](#numbers)
- Footnotes in the export[^1]
- [x] Tested on every plan

## Numbers

| Step    | Before | After  |
| :------ | -----: | -----: |
| Preview | 840 ms | 310 ms |
| Export  | 2.1 s  | 1.4 s  |

\newpage

## Thanks

To everyone who reported a problem.

[^1]: From version 2.4 on.

What the settings control

Look. settings.markdown.theme is document, which styles the text, in the brand kit’s fonts and colour where the workspace has one, or none; settings.markdown.css comes after it.
Raw HTML. Shown as text by default. settings.markdown.html: "allow" writes it as it stands, for Markdown you wrote yourself, never for text from your users or a model.
Line breaks. settings.markdown.breaks: true makes a single line break a line break, for text from a chat.
Paper, header and footer. paper, margin, header.html and footer.html work as for HTML; elements with the classes pageNumber and totalPages show the page numbers.

Placeholders in the Markdown

Add "engine": "jinja2" (or liquid, handlebars) and a data object, and {{ … }} in the text is filled before it is read as Markdown, with all helpers. The Markdown guide has the rest.

When the API says no

One shape for every error. Errors are problem documents (RFC 9457) with type, title, status, detail, a stable code and the request_id to quote to support; the type URL leads to a page about that error. The list is in the error reference.
The usual ones. 401 unauthorized for a missing or revoked key, 404 template_not_found for a wrong template name, 422 template_runtime_error when the template fails on the data, 429 rate_limited above the plan’s requests per second, 402 quota_exceeded when the Free plan’s units are used up (a paid plan bills extra units up to its hard cap).
Retry safely. Send an Idempotency-Key header with the POST, and repeat the request with the same key when you do not know whether the first attempt arrived: for 24 hours the key returns the first answer instead of rendering and billing again. The answer is stored once the first attempt has been answered, so do not retry while it may still run; and problems below 500 are stored too, so a corrected request needs a new key.

The job around this program

This guide is one program. What the job needs around it, from the template to the limits and the price, is on the page Markdown to PDF API.

More curl guides

FAQ

Which Markdown does it read?: GitHub Flavored Markdown: tables, task lists, strikethrough and autolinks, plus footnotes and a front matter block. Heading ids follow GitHub’s rule, so links between headings work inside the PDF.
How large may the Markdown be?: Up to 1 MB of UTF-8 per request, and a stylesheet in settings.markdown.css up to 256 kB. Limits per plan are in the docs.
Where do pictures come from?: A picture named by a bare file name, such as logo.png, is a file of the workspace’s file library; a public https address or a data:image/ address works as well. formfeed pdf convert report.md sends the pictures beside the file along by itself.