Markdown in PDF umwandeln mit Python

Was Sie brauchen

• Einen API-Key. Legen Sie ihn in der App unter API-Schlüssel an und exportieren Sie ihn als FORMFEED_API_KEY. Zum Ausprobieren ist ein Test-Key (ff_test_…) richtig. Siehe Quickstart.
• Python. Sie brauchen Python 3.10 oder neuer und das Paket formfeed (es bringt httpx und pydantic mit).
• Eine Markdown-Datei. report.md neben dem Programm, bis 1 MB. Ein Beispiel steht weiter unten.

pip install formfeed

Das Programm

Das Programm liest report.md, sendet sie als markdown mit Lesezeichen aus ihren Überschriften, wartet auf das Ergebnis, wenn die API mit 202 antwortet, bricht mit der Meldung der API ab, wenn etwas nicht stimmt, und speichert das PDF.

import os
from pathlib import Path

from formfeed import Formfeed

formfeed = Formfeed(api_key=os.environ["FORMFEED_API_KEY"])
markdown = Path("report.md").read_text(encoding="utf-8")

# a problem answer (4xx, 5xx) raises a FormfeedError with the API's code, title and detail
render = formfeed.renders.create(
    markdown=markdown,
    settings={
        "pdf": {"outline": True},
    },
)
# not done within 60 seconds: the API answered 202 and the render goes on in the background
if render.status != "succeeded":
    render = formfeed.renders.wait_for(render.id)
if render.status == "failed":
    raise SystemExit(f"render failed: {render.error}")

Path("report.pdf").write_bytes(formfeed.renders.download(render))
print(render.id, render.page_count, "page(s),", render.units, "unit(s)")

Ausführen

Es gibt die ID des Renderings, die Seitenzahl und die verbrauchten Einheiten aus, und report.pdf liegt neben dem Programm.

export FORMFEED_API_KEY=ff_test_...
python render.py

Was an Python besonders ist

• Keyword-Argumente. Jedes Feld der Anfrage ist ein Keyword-Argument (renders.create, pdf.protect), nach den Einträgen von renders.batch und den Quellen von pdf.merge, die zuerst kommen; verschachtelte Optionen wie settings oder post sind einfache Dictionaries.
• Retries sind eingebaut. Der Client sendet mit jedem Rendering einen Idempotency-Key und wiederholt 429, 503 und Netzwerkfehler bis zu dreimal mit Backoff, mit demselben Schlüssel: Ein Retry einer Anfrage, die schon beantwortet wurde, erhält diese Antwort zurück statt eines zweiten Renderings.
• Typisierte Ergebnisse. Die Antwort ist ein pydantic-Modell: render.download_url, render.page_count und render.units sind Attribute, keine Dictionary-Schlüssel.
• Auch asynchron. AsyncFormfeed hat dieselben Methoden als Coroutinen, für FastAPI oder jeden anderen asyncio-Dienst.

Eine Markdown-Datei mit Titel

Das Front Matter gibt dem PDF Titel und Autor; ohne es ist die erste Überschrift der Titel. Eine Zeile \newpage beginnt eine neue Seite, und ein Link auf eine Überschrift funktioniert im PDF:

---
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.

Was die Einstellungen steuern

• Aussehen. settings.markdown.theme ist document, das den Text gestaltet, in Schriften und Farbe des Brand-Kits, wo der Workspace eines hat, oder none; settings.markdown.css kommt danach.
• Rohes HTML. In der Vorgabe als Text gezeigt. settings.markdown.html: "allow" schreibt es, wie es steht, für Markdown, das Sie selbst geschrieben haben, nie für Text Ihrer Nutzer oder eines Modells.
• Zeilenumbrüche. settings.markdown.breaks: true macht einen einzelnen Zeilenumbruch zu einem Zeilenumbruch, für Text aus einem Chat.
• Papier, Kopf- und Fußzeile. paper, margin, header.html und footer.html funktionieren wie bei HTML; Elemente mit den Klassen pageNumber und totalPages zeigen die Seitenzahlen.

Platzhalter im Markdown

Mit "engine": "jinja2" (oder liquid, handlebars) und einem data-Objekt wird {{ … }} im Text gefüllt, bevor er als Markdown gelesen wird, mit allen Helpern. Der Markdown-Guide erklärt den Rest.

Wenn die API nein sagt

• Eine Form für jeden Fehler. Fehler sind Problem-Dokumente (RFC 9457) mit type, title, status, detail, einem stabilen code und der request_id, die Sie dem Support nennen; die type-URL führt zu einer Seite über diesen Fehler. Die Liste steht in der Fehlerreferenz.
• Die üblichen. 401 unauthorized bei fehlendem oder widerrufenem Schlüssel, 404 template_not_found bei falschem Vorlagennamen, 422 template_runtime_error, wenn die Vorlage an den Daten scheitert, 429 rate_limited über den Anfragen pro Sekunde des Tarifs, 402 quota_exceeded, wenn die Einheiten des Free-Tarifs verbraucht sind (ein bezahlter Tarif rechnet weitere Einheiten ab, bis zu seiner Obergrenze).
• Sicher wiederholen. Senden Sie beim POST einen Idempotency-Key-Header und wiederholen Sie die Anfrage mit demselben Schlüssel, wenn Sie nicht wissen, ob der erste Versuch ankam: 24 Stunden lang liefert der Schlüssel die erste Antwort, statt erneut zu rendern und zu berechnen. Gespeichert wird die Antwort, sobald der erste Versuch beantwortet ist; wiederholen Sie also nicht, solange er noch laufen kann. Auch Probleme unter 500 werden gespeichert, eine korrigierte Anfrage braucht deshalb einen neuen Schlüssel.

Die Aufgabe um dieses Programm

Dieser Guide ist ein Programm. Was die Aufgabe darum herum braucht, von der Vorlage bis zu Limits und Preis, steht auf der Seite Markdown-zu-PDF-API.

Weitere Guides für Python

• PDF-Rechnung aus JSON erzeugen mit Python
• ZUGFeRD-E-Rechnung erstellen mit Python
• HTML in PDF umwandeln mit Python
• Open-Graph-Bilder erzeugen mit Python
• PDFs aus einer CSV erzeugen mit Python
• PDFs zusammenfügen und mit Passwort schützen mit Python
• PDF asynchron rendern und den Webhook prüfen mit Python