Zum Hauptinhalt springen

Kapitel 18 · Teil III · In der Praxis

Kommandozeile: postext im Terminal, in einem Skript oder einem Agenten

Eine eigenständige ausführbare Datei für macOS, Linux und Windows. Sie wandelt ein .postext-Buch, einen Buchordner oder lose Markdown-Dateien in PDF, HTML, EPUB, Seitenbilder und Word um, packt Pakete, prüft Bücher und liefert JSON-Ausgabe für Skripte und Agenten

Aktualisiert 2026-11-0613 minenescadefritptzhjaar

Kurz gesagt

Diese Seite richtet sich an alle, die Bücher mit Postext im Terminal statt auf der Website machen wollen. Sie laden eine einzige Datei für Ihren Computer herunter und führen sie aus, ohne etwas zu installieren. Sie geben ihr Ihr Buch oder ein paar Textdateien, und sie erzeugt ein PDF, eine Webseite, ein E-Book, Bilder der Seiten oder ein Word-Dokument. Sie kann ein Buch auch auf Probleme prüfen und seine Dateien zu einer einzigen packen. Auch Programme und KI-Assistenten können sie nutzen, denn sie kann in einem Format antworten, das diese leicht lesen.

postext setzt Ihr Buch aus einem Terminal, einem Skript oder einem Agenten heraus.

In der Sandbox schreiben und gestalten Sie ein Buch nach Augenmaß. Die Kommandozeile nimmt dasselbe Buch und erzeugt seine Dateien ohne Browser: ein druckfertiges PDF, die Seiten als HTML, ein EPUB, ein Bild einer Seite oder aller Seiten, ein Word-Dokument. Außerdem packt und entpackt sie .postext-Pakete, importiert Word-Dokumente, beschreibt ein Buch und prüft es auf Probleme.

Sie ist eine eigenständige ausführbare Datei pro System. Die Postext-Engine, die Schreiber für PDF, EPUB, HTML und Word, der Renderer für die Seiten (Skia), HarfBuzz für Arabisch und andere komplexe Schriftsysteme, die ICC-Druckprofile und die Standardschriften (EB Garamond und Open Sans) stecken alle darin. Es gibt keine Laufzeitumgebung, kein Paket und keine Bibliothek zu installieren, und das Layout ist das der Sandbox: Dasselbe Buch bricht in dieselben Seiten um.

#Herunterladen

Mit Homebrew unter macOS oder Linux:

brew install drnachio/postext/postext

Mit Scoop unter Windows:

scoop bucket add postext https://github.com/drnachio/scoop-postext
scoop install postext

Beide installieren die ausführbare Datei des neuesten Release als Befehl postext, geprüft anhand ihrer Prüfsumme, und brew upgrade postext bzw. scoop update postext holt das nächste. Ohne Paketmanager laden Sie die Datei selbst herunter.

Jedes Release von Postext veröffentlicht die ausführbaren Dateien in seinem GitHub Release, zusammen mit ihren Prüfsummen (SHA256SUMS) und einer readme.txt:

DateiSystem
postext-macos-arm64macOS auf Apple Silicon (M1 und neuer)
postext-macos-x64macOS auf Intel
postext-linux-x64Linux x86-64 mit glibc (Debian, Ubuntu, Fedora …)
postext-linux-arm64Linux ARM64 mit glibc (Raspberry Pi OS 64 Bit, ARM-Server in der Cloud)
postext-linux-x64-muslLinux x86-64 mit musl (Alpine; vorher apk add libstdc++ libgcc ausführen)
postext-windows-x64.exeWindows x64

Jede Datei ist zwischen 115 und 140 MB groß. Der Link https://github.com/drnachio/postext/releases/latest/download/<file> liefert immer die neueste.

Unter Linux oder macOS:

curl -fL -o postext https://github.com/drnachio/postext/releases/latest/download/postext-linux-x64
chmod +x postext
./postext

Verschieben Sie sie in einen Ordner in Ihrem PATH (/usr/local/bin, ~/.local/bin), um sie von überall als postext aufzurufen. macOS stellt eine mit einem Browser heruntergeladene Datei unter Quarantäne; entfernen Sie die Markierung einmal:

xattr -d com.apple.quarantine postext-macos-arm64

Unter Windows in PowerShell:

Invoke-WebRequest https://github.com/drnachio/postext/releases/latest/download/postext-windows-x64.exe -OutFile postext.exe
.\postext.exe

Ist Node.js installiert, lädt npx postext-cli die ausführbare Datei für Ihr System von npm herunter und führt sie aus, und npm install -g postext-cli behält sie als Befehl postext.

Ohne Argumente aufgerufen, gibt postext seine Hilfe aus; postext help <command> listet die Optionen eines Befehls auf.

#Ein erstes Buch

Drei Markdown-Dateien in einem Ordner sind ein Buch, je ein Kapitel, in der Reihenfolge der Namen:

postext pdf chapters/ --name "Field notes" -o field-notes.pdf

Das Frontmatter des ersten Kapitels gibt dem Buch Titel und Autor, und die Standardwerte der Engine erledigen den Rest: zwei Spalten, ein Grundlinienraster, Text im Blocksatz mit Silbentrennung, Kolumnentitel. Fügen Sie eine Konfiguration und Bilder hinzu, wenn Sie sie brauchen:

postext pdf chapters/ --config design.json --resources pictures/ -o field-notes.pdf

Ein in der Sandbox erstelltes Buch (Bücher → .postext exportieren) funktioniert so, wie es ist:

postext pdf my-book.postext -o my-book.pdf
postext image my-book.postext --page 1 -o cover.png

#Was ein Buch sein kann

Jeder Befehl, der ein Buch liest, akzeptiert jede dieser Formen:

  • Eine .postext-Datei: das Paket, das die Sandbox exportiert und öffnet (siehe Pakete).
  • Ein Buchordner: ein entpacktes Paket mit seiner preset.json, seinen Kapiteln, Ressourcen und Schriften. Der Agent-Skill liefert so etwas, und postext unpack schreibt einen.
  • Lose Markdown-Dateien: eine oder mehrere .md-Dateien, je ein Kapitel in der angegebenen Reihenfolge, oder ein Ordner, dessen .md-Dateien nach Namen sortiert genommen werden (01-intro.md, 02-method.md …). Dazu:
    • --config design.json: die Konfiguration, entweder ein bloßes Konfigurationsobjekt oder eine ganze preset.json;
    • --resources pictures/: die Bilder, jedes eine Abbildung, benannt nach seinem Dateinamen ohne Endung (map.png ist ::resource{id="map"}); eine resources.json im Ordner beschreibt sie stattdessen (IDs, Typen, Legenden, Alternativtext), in derselben Form wie die resources einer preset.json;
    • --fonts fonts/: Schriftdateien, die das Buch mitbringt (TTF, OTF, WOFF2), benannt nach der Familie, die ihre Tabellen angeben;
    • --name "Title": der Name des Buchs.

--config funktioniert auch bei einem Paket oder einem Ordner: Es wird über die eigene Konfiguration des Buchs gelegt. Ein mehrsprachiges Paket wird in seiner eigenen Sprache gelesen, es sei denn, --locale verlangt eine andere (--locale en).

#Befehle

BefehlWas er tut
pdfDas PDF, mit Lesezeichen, Links, eingebetteten Schriften und standardmäßig für Barrierefreiheit getaggt (PDF/UA); PDF/X und CMYK für den Druck.
htmlDie Seiten als HTML mit echtem Text: eine eigenständige Datei oder ein Ordner mit index.html und assets/.
epubEin EPUB-3-Buch, mit festen Seiten wie gedruckt oder umfließendem Text.
imageEine Seite als PNG-, JPEG- oder WebP-Bild.
imagesAlle Seiten oder einen Bereich als Bilder in einem Ordner.
docxDie Kapitel als Word-Dokument: semantisch (der Inhalt allein, in schlichten Word-Formatvorlagen), gesetzt (derselbe bearbeitbare Text im Design des Buchs) oder als Seitenfaksimile (jede Zeile in einem festen Textfeld).
idmlDie Seiten als InDesign-Paket (IDML), zur Fertigstellung in InDesign.
import-docxDie Korrekturen aus einer exportierten Word-Datei zurück ins Buch; jedes andere Word-Dokument als neues Buch (ein Ordner oder eine .postext-Datei).
import-idmlEin als IDML gespeichertes InDesign-Dokument als neues Buch (ein Ordner oder eine .postext-Datei).
packEinen Buchordner oder lose Markdown-Dateien als eine einzige .postext-Datei.
unpackEine .postext-Datei als Ordner.
infoKapitel, Sprachen, Ressourcen und Schriften des Buchs, mit --pages auch seine Seitenzahl.
checkSetzt das Buch und meldet jedes Problem; für den Druck auch den Preflight.
buildSetzt das Buch einmal und schreibt mehrere der obigen Ausgabeformate; --watch läuft weiter und baut bei jedem Speichern neu.

Jeder Befehl schreibt in das Verzeichnis, in dem Sie ihn aufrufen, benannt nach der Eingabe, es sei denn, -o gibt den Pfad an (images schreibt in pages/). -o - schreibt eine einzelne Ausgabe auf die Standardausgabe.

#pdf

postext pdf book.postext -o book.pdf
postext pdf book/ --pdfx x4 --profile fogra51 -o book-print.pdf
postext pdf book/ --color-space grayscale --no-outlines

Das PDF folgt den eigenen Einstellungen des Buchs (siehe PDF-Erzeugung und Druckvorstufe); diese Optionen ändern sie für einen Lauf:

  • --pdfx none|x1a|x4: der PDF/X-Standard für eine Druckerei.
  • --profile NAME|FILE: das ICC-Ausgabeprofil, über seinen Namen (fogra39, fogra51, fogra52, swop5, gracol2006, snap2007, ifra26 und die übrigen Profile der Druckeinstellungen) oder eine .icc-Datei.
  • --color-space rgb|cmyk|grayscale.
  • --accessible / --no-accessible: die getaggte Struktur für Screenreader.
  • --no-outlines: die Lesezeichen weglassen.
  • --page-negative: negative Seiten, für manche Druckabläufe.

#html

postext html book.postext -o book.html
postext html book.postext -o site/ --mode single

Ein Pfad, der auf .html endet, ergibt eine einzige Datei mit den Bildern und Schriften darin, leicht zu verschicken. Jeder andere Pfad ist ein Ordner: index.html neben assets/, das die Bilder, die Schriften und selbst gehostete Videos enthält. --assets embed|folder wählt für jeden Pfad die eine oder andere Variante. Die Seiten sind das Drucklayout, in Bildschirmgröße gezeigt: nebeneinander (--mode multi, Standard) oder untereinander (--mode single). Schriften mit der Markierung redistributable: false werden genannt, aber nicht kopiert. Gibt die Familie einen fallback an, werden stattdessen die Schnitte dieser freien Familie unter dem Namen der Familie geschrieben (seit postext 1.43).

#epub

postext epub book.postext -o book.epub
postext epub book.postext --layout reflowable --cover cover.jpg

--layout fixed (Standard) behält jede Seite wie gedruckt, mit markierbarem Text; --layout reflowable lässt das Lesesystem den Text für seinen Bildschirm neu setzen (siehe EPUB-Bücher). Das Cover ist das Vorschaubild des Buchs, es sei denn, --cover gibt ein Bild an. Die Metadaten des Pakets (Titel, Autoren, Sprache, Kennung) kommen aus dem Frontmatter des ersten Kapitels, wie in der Sandbox. Schriften mit redistributable: false werden nicht kopiert; eine Familie, die einen fallback angibt, wird mit den Schnitten dieser freien Familie unter ihrem eigenen Namen eingebettet (seit postext 1.43).

#image und images

postext image book.postext --page 12 -o page-12.png
postext image book.postext --page "#1" --dpi 300 -f jpeg -o cover.jpg
postext images book.postext -o pages/ --dpi 100
postext images book.postext --pages 1-10,iv -f webp --pattern "{chapter}-{label}"

Seiten werden wie gedruckt benannt (12, iv, ein Bereich 7-9) oder nach ihrer Position im Buch mit # (#1 ist die erste Seite, egal, welche Nummer sie trägt, #10-#20, #30- bis zum Ende). --pages nimmt eine kommagetrennte Liste an. Gezeichnet wird wie in der Canvas-Ansicht der Sandbox, ein Bild zeigt die Seite also genau so, wie sie gesetzt ist, ohne den Umweg über ein PDF.

  • --format png|jpeg|webp (oder die Endung von -o), --quality 1-100 für JPEG und WebP.
  • --dpi: Auflösung, standardmäßig 150; 72–100 genügen, um eine Seite zu lesen, 300 für den Druck.
  • --pattern: die Dateinamen von images, aus {n} (die Position, {n:03} auf drei Ziffern aufgefüllt), {label} (die gedruckte Nummer) und {chapter}; standardmäßig page-{n:03}.
  • --print-preview: die Seite so, wie die Druckerei sie wiedergeben wird, über das Ausgabeprofil, mit eingezeichnetem Endformat und Anschnitt.
  • --jobs N: wie viele Bilder gleichzeitig kodiert werden (standardmäßig so viele, wie der Rechner Prozessoren hat).

#docx und import-docx

postext docx book.postext -o book.docx
postext docx book/ --variant semantic -o words.docx
postext docx book/ --variant facsimile -o pages.docx
postext import-docx book.docx book/ --dry-run
postext import-docx book.docx book/
postext import-docx manuscript.docx -o manuscript/ --locale es --report

docx schreibt die Word-Dokumente, die die Sandbox exportiert (siehe Sandbox › Word-Dokumente), und ein drittes. --variant formatted, die Voreinstellung, baut aus dem Markdown ein bearbeitbares Dokument mit Überschriften, Listen, Fußnoten, Tabellen, Formeln und Abschnitten von Word selbst, im Design des Buchs, so weit Word es zulässt, und mit den eingebetteten Schriften des Buchs (--no-embed-fonts nennt sie nur); wofür Word keine Struktur hat, das reist als Quelltext in Inhaltssteuerelementen Postext Source. --variant semantic schreibt denselben Text als reinen Inhalt: ein schlichtes Dokument (A4, eine Spalte, Arial) in Word-Formatvorlagen, die jeden Teil benennen, ohne Seitendesign und ohne eingebettete Schriften. Keines von beiden braucht ein Layout; beide lassen sich in Word und in Google Docs öffnen, und beide kommen über import-docx zurück. --variant facsimile setzt das Buch wie pdf und schreibt jede Seite als Word-Abschnitt, jede Zeile in einem festen Textfeld, mit eingebetteten Schriften: eine Datei, um das Layout in Word auf dem Desktop anzusehen, nicht zum Bearbeiten und nicht für Google Docs. Eine Familie, die das Buch nicht weitergeben darf (redistributable: false in customFonts), bleibt draußen, und ihr freier Ersatz kommt hinein, wie im EPUB; eine Schrift, deren Lizenz das Einbetten verbietet, eine mit PostScript-Konturen und eine variable Schrift werden gemeldet und nur genannt. In build schreibt --docx DATEI dieselbe Datei, mit --docx-variant und --no-docx-fonts. Seit postext 1.68; --template gilt nicht mehr für docx und build.

Mit einem Buch nach der Datei bringt import-docx die Korrekturen zurück, die in einem von docx aus diesem Buch exportierten Dokument gemacht wurden. Es liest die Karte, die die Datei mitführt, vergleicht den Text mit der beim Export gemachten Kopie der Kapitel und führt jede Korrektur mit dem Buch zusammen, wie es jetzt ist: die Kapiteldateien eines Ordners, einer .postext-Datei oder loser Markdown-Dateien, und den Wortlaut der Ressourcen (Legenden, Anmerkungen, Alternativtext, Tabellenzellen) in preset.json, bei losem Markdown in der resources.json von --resources DIR. Bei einem Buch in mehreren Sprachen nennt --locale die Ausgabe, aus der die Datei exportiert wurde, und eine Korrektur am Wortlaut einer Ressource geht in den localized-Block dieser Ausgabe. Jede Korrektur wird in einer eigenen Zeile gemeldet:

  • applied, mit der Datei und Zeile, in die sie ging;
  • conflict: Der Text hat sich seit dem Export auch im Buch geändert, das Kapitel oder die Ressource gibt es nicht mehr, oder zwei Korrekturen überschneiden sich;
  • rejected: Text, den das Buch selbst erzeugt (Nummern, Legendenbezeichnungen), oder Formatierung, die über Postext-Markup hinwegläuft.

Nachverfolgte Änderungen gelten als angenommen, und Kommentare werden mit Autor und Stelle aufgeführt, aber nicht geschrieben. Der Exit-Code ist 3, wenn eine Korrektur nicht übernommen wurde. --dry-run (-n) gibt den Bericht und ein Unified Diff jeder Datei aus, die sich ändern würde, und schreibt nichts. Jede Datei wird neben ihr Ziel geschrieben und darüber umbenannt, sodass ein abgebrochener Lauf nie ein halbes Kapitel hinterlässt; eine Kapiteldatei, die sich während des Imports geändert hat, bleibt mit einer Warnung docx.fileChanged unangetastet. -o passt nicht zu einem Buch. Mit --json enthält die Antwort variant, exportId, edits (jeweils mit status, reason, kind, before, after und at), comments, files und bei einem Probelauf diff.

Auch eine Datei, die in Google Docs bearbeitet und als .docx heruntergeladen wurde, kommt zurück. Docs lässt die Karte und die Kopie der Kapitel weg; der Import schreibt die Karte aus dem Buch neu, und sagt das im Bericht. Weil diese Datei keine Kopie des exportierten Texts mitführt, wird sie mit dem Buch verglichen, wie es jetzt ist. Hat sich das Buch seit dem Export geändert, warnt der Bericht davor, und eine inzwischen im Buch gemachte Änderung kann als Bearbeitung erscheinen, die sie zurücknimmt. Importieren Sie eine Docs-Datei in das Buch, aus dem sie exportiert wurde, bevor Sie dieses Buch ändern; eine von Word gespeicherte Datei behält ihre Karte und wird mit späteren Änderungen am Buch zusammengeführt. Docs entfernt außerdem das verborgene Lesezeichen eines Texts, der ganz ersetzt wird (eine Überschrift, eine Tabellenzelle, eine Legende, ein Kastentitel, eine Fußnote). Der Import findet einen solchen Text an seinem Platz zwischen seinen Nachbarn; eine Überschrift bleibt also eine Überschrift, und eine Legende geht an ihre Ressource. Lässt sich das nicht entscheiden, etwa weil daneben auch ein Absatz getippt wurde und nichts die beiden unterscheidet, zeigt der Bericht stattdessen eine Löschung und eine Hinzufügung. Dieselbe Datei ein zweites Mal zu importieren, bringt nichts.

Ohne Buch macht import-docx aus jedem Word-Dokument ein neues Buch: ein Kapitel an jeder Überschrift der Ebene 1 (--no-split behält eines), Bilder und Tabellen als Ressourcen, und --report gibt den Qualitätsbericht aus, den die Sandbox zeigt (verwendete Formatvorlagen, direkte Formatierung, getippte Nummerierung …). --template nimmt eine Importvorlage an (eine aus der Sandbox gespeicherte .json-Datei oder eine .docx-Datei, die eine enthält).

Der Zeichenabstand gehört zur Formatvorlage, nicht zum Text, und steht deshalb nicht im Markdown. docx schreibt das letterSpacing der Absatzformate, der Überschriftenstile und der Überschriftenebenen als Zeichenabstand der Word-Formatvorlage, und import-docx liest ihn in em der Schriftgröße der Vorlage zurück: Er wird als letterSpacing bei den Formaten des Buchs gesetzt, die keinen eigenen haben (den Absatzformaten und Überschriftenstilen der --config-Datei, denen die Word-Formatvorlagen entsprechen, und den Überschriftenebenen); einen Zeichenabstand, den das Buch schon festlegt, lässt er unverändert. Mit --json führt styleTracking auf, was gesetzt wurde (applied) und was übrig blieb (skipped). Seit postext 1.39.

#idml

postext idml book/ -o book.idml
postext idml book.postext -o book.idml --images link
postext idml book/ -o out/book.idml --lines reflow --fonts

idml setzt das Buch wie pdf und schreibt die Seiten als InDesign-Markup-Paket, zur Fertigstellung in InDesign: die Seiten in Druckbögen beiderseits des Rückens bei einem Buch mit Rändern für gegenüberliegende Seiten (sonst eine Seite je Druckbogen), Linien, Kästen, Pfade und Bilder als Seitenobjekte, Tabellen als InDesign-Tabellen, der Text jedes Rahmens einer zusammengesetzten Seite als Textrahmen mit eigenem Textabschnitt (mit next verkettete Rahmen teilen sich einen), Kastenstile als Absatzformate und vom Autor angelegte CMYK-Farben als Farbfelder. Chips mit einem Formularfeld werden zu InDesign-Formularfeldern. --lines keep (Standard) beendet jede Zeile dort, wo Postext sie beendet hat, sodass InDesign dieselben Zeilen zeigt wie das PDF; --lines reflow überlässt die Absätze dem Setzer von InDesign, und die Zeilenumbrüche können abweichen. --images link legt die Bilder neben der Datei in Links/ ab, statt sie in die Datei zu packen. --fonts schreibt die Schriftdateien der verwendeten Schnitte neben das Paket, nach Document fonts/, wo InDesign sie für dieses Dokument findet; dafür muss -o eine Datei nennen, und eine Familie, die das Buch nicht weitergeben darf, bleibt mit einer Warnung draußen. Was das Paket nicht so tragen kann, wie es im Buch steht (senkrechter Text, der abgerundete Rahmen einer Tabelle), wird als Warnung idml.* gemeldet. Der Export ist das Paket postext-idml: siehe Programmatische Nutzung › InDesign-Pakete. In build schreibt --idml DATEI dasselbe Paket, mit --idml-images, --idml-lines und --idml-fonts. Seit postext 1.71; --lines und --fonts seit 1.76.

#import-idml

postext import-idml book.idml -o book/
postext import-idml book.idml -o book.postext --layout flow --links pictures/
postext import-idml book.idml --report --json

import-idml liest ein InDesign-Markup-Paket und schreibt ein neues Buch, als Ordner oder als .postext-Datei: die Kapitel als Markdown, die Konfiguration, die sich aus den Formaten und Seiten des Dokuments ergibt, und seine Bilder und Tabellen als Ressourcen. Eine .indd-Datei wird nicht gelesen: Speichern Sie sie vorher in InDesign als InDesign Markup. --layout pages folgt dem Dokument Seite für Seite mit zusammengesetzten Seiten, jeder Rahmen dort, wo er stand; --layout flow schreibt ein Buch mit fließendem Text, in Lesereihenfolge und mit den Formaten des Dokuments, das Postext neu setzt; auto (Standard) wählt eines von beiden und nennt den Grund. Verknüpfte Bilder werden aus --links gelesen, sonst aus dem Ordner der Datei und dessen Links/, und die nicht gefundenen werden aufgelistet. Auch die Schriften, die das Dokument nennt, werden aufgelistet: Ein Paket enthält keine Schriftdateien, geben Sie sie also beim Erzeugen des Buchs mit --font-dir an.

Ein aus Postext exportiertes Buch kommt mit denselben Zeilen zurück. Ein in InDesign erstelltes Dokument wird mit Verlusten gelesen: Der Befehl gibt das Urteil (faithful, approximate oder lossy), die Zählungen und das Verlorene oder Angenäherte aus; --report ergänzt die Hinweise und wie jedes Absatzformat gelesen wurde, und --json trägt alles als Daten. --hidden, --pasteboard und --non-printing lesen auch ausgeblendete Ebenen und Objekte, die Montagefläche und nicht druckende Objekte; --conditions all liest den gesamten bedingten Text, --changes reject liest verfolgte Änderungen als abgelehnt, und --no-masters lässt die Objekte der Musterseiten weg. --name und --locale geben Titel und Sprache an. Der Import ist idmlToPostext aus dem Paket postext-idml: siehe Programmatische Nutzung › InDesign-Pakete.

#pack und unpack

postext pack my-book/ -o my-book.postext
postext pack 01.md 02.md --name "Notes" --config design.json --resources img/ -o notes.postext
postext unpack my-book.postext -o my-book/

pack packt einen Buchordner so, wie er ist, als ZIP oder baut ein Paket aus losen Markdown-Dateien. Dieselbe Eingabe ergibt immer dieselben Bytes, sodass sich ein Paket vergleichen oder hashen lässt. Bei losen Markdown-Dateien setzen --id, --description und --thumbnail FILE (ein Titelbild) die ID, die Beschreibung und das Vorschaubild des Pakets; die ID ist standardmäßig ein Slug des Namens. Ein Ordner behält, was seine preset.json angibt. Ein Buch, das kein Titelbild angibt, erhält seine erste Seite als Titelbild (thumbnail.jpg, 1024 px an der langen Seite), das Bild, das ein Dateimanager für die Datei anzeigen kann; --no-auto-thumbnail lässt es weg. unpack weigert sich, in einen Ordner zu schreiben, der nicht leer ist, es sei denn, --force ist angegeben.

#info und check

postext info book.postext --pages
postext check book.postext
postext check chapters/ --strict --json

info listet die Kapitel auf (Titel, Wörter, Datei und mit --pages ihre Seiten), die Ressourcen und jede Schriftfamilie mit ihrer Herkunft (Buch, Ordner, ausführbare Datei, Download-Cache oder Ersatzschrift). Bei einem Buch, das angibt, wo es beginnt (start in preset.json: ein Auszug, der auf Seite 58 in Kapitel 4 einsetzt), gibt info auch das aus, und jeder Befehl setzt das Buch ab dort.

check setzt das Buch und meldet, was das Bedienfeld Prüfungen der Sandbox zeigt: Markdown, das nicht geschlossen wird, unbekannte Ressourcen, Direktiven und Formate, Kästen, die das Layout erzwingen musste, fehlende Schriften, Einstellungen, die die Engine ersetzen musste, und bei einem für den Druck eingerichteten Buch (oder mit --preflight) den Preflight: Bilder mit geringer Auflösung, Haarlinien, kleinen Text in mehreren Druckfarben, Farbauftrag über dem Grenzwert, Text nahe am Endformat. Außerdem listet er den Text auf, der sich auf seinem Grund nicht lesen lässt (contrast), einmal pro Farbpaar, mit dem Kontrastverhältnis auf dem Bildschirm und für den Druck auf dem Papier des Ausgabeprofils. Jedes Problem nennt die Kapiteldatei, die Zeile und die Seite. Der Exit-Code ist 3, wenn ein Fehler gefunden wird, oder mit --strict bei jeder Warnung.

Außerdem meldet er Gestaltungstexte der Konfiguration, die den Text des Buches statt Platzhaltern enthalten (contentInConfig), einmal je Überschriftenstil, Kolumnentitel oder Teilgestaltung, mit dem Pfad jedes Textes: Verschieben Sie diesen Text ins Markdown oder tragen Sie Titel oder Verlagsnamen in checks.contentInConfig.allow ein.

Bei einem Buch mit Seitenvorlagen meldet check außerdem Text, der nicht in seinen Rahmen passt (frameOverflow, mit den Einpassstufen, die versucht wurden, und den Änderungen, die das Problem beheben würden), einen Artikel, der über die Seiten hinausläuft, die ein Rahmen anfügen darf (frameContinuationLimit), einen Sprung auf eine Seite, die nicht folgt (continueTargetMissing), Beschriftungen von Abbildungen, die sich nicht zeichnen lassen oder sich überschneiden (labelAnchorUnknown, anchorUnlabelled, labelOverflow, labelOverlap), Rahmen, die unter anderen Rahmen verborgen liegen oder über ihre Kante hinausragen (frameCovered, frameOutsideArea), mehr Karten, als ein Raster fasst (repeatOverflow), und Module, die eine Seite nicht setzen kann (moduleUnknown, moduleAsPage, moduleNested, moduleNameRejected). Nach den Warnungen gibt es pro zusammengesetzter Seite mit Ereignissen eine reflow-Zeile aus, und --json liefert die Schritte, die Vorschläge und das Umbruchprotokoll als Daten. Siehe Zusammengesetzte Seiten › Warnungen und Umbruchprotokoll.

#build und --watch

postext build book/ --pdf out/book.pdf --html out/book.html --images out/pages --pages 1-4
postext build chapters/ --pdf book.pdf --watch

build setzt das Buch einmal und schreibt jedes Ausgabeformat, das Sie angeben (--pdf, --html, --epub, --images, --docx, --idml), mit den Optionen des jeweiligen Befehls. --watch bleibt aktiv: Wenn sich ein Kapitel, die Konfiguration oder ein Bild ändert, wird das Buch neu gesetzt, wobei Schriften und Engine geladen bleiben, für ein Kapitel typischerweise in einem Bruchteil einer Sekunde, und die Dateien werden neu geschrieben. Führt eine gespeicherte Änderung zu einem Fehler, wird der Fehler ausgegeben, und die zuletzt fehlerfreien Dateien bleiben erhalten.

#Optionen für jedes Buch

OptionWas sie tut
--locale TAGDie Sprache, in der ein mehrsprachiges Buch gelesen wird (es, en, pt-BR …).
--chapters LISTSetzt nur einige Kapitel: 2, 1,3-5, 4-. Schneller bei einem langen Buch; ihre Seiten werden ab ihrer eigenen ersten Seite nummeriert.
--set PATH=VALUEÄndert eine Einstellung für diesen Lauf, als Pfad mit Punkten: --set page.dpi=150, --set bodyText.fontFamily=Lora, --set headings.levels.0.italic=true. Der Wert wird als JSON gelesen, wenn das geht (Zahlen, true und false, Objekte), sonst als Text. Wiederholbar.
--config FILEEine Konfiguration (oder eine preset.json) für lose Markdown-Dateien, oder über die eigene eines Buchs gelegt.
--resources DIR, --fonts DIR, --name TEXTBilder, Schriften und Titel für lose Markdown-Dateien.
--font-dir DIREin Ordner, in dem nach Schriften gesucht wird, die das Buch nicht mitbringt. Wiederholbar.
--offlineNie Schriften herunterladen.
--cache-dir DIRWo heruntergeladene Schriften aufbewahrt werden.

Und für jeden Befehl: --json, --quiet (-q, nur Fehler), --verbose (Fortschritt und jede Warnung), --no-color, --help (-h), --version (-v).

#Schriften

Ein Buch, das seine Schriften mitbringt (ein Paket oder --fonts bei losen Markdown-Dateien), wird mit ihnen gesetzt und mit nichts anderem. Für jede Familie, die die Konfiguration nennt und die das Buch nicht mitbringt, sucht postext der Reihe nach:

  1. in den mit --font-dir angegebenen Ordnern;
  2. unter den in die ausführbare Datei kompilierten Schriften: EB Garamond und Open Sans, die Standardschriften der Engine;
  3. im Download-Cache;
  4. bei Google Fonts, das ganze statische TrueType-Dateien liefert, oder bei Fontsource für eine Familie, die Google Fonts nicht hat (Commit Mono, FiraGO); sie werden im Cache aufbewahrt, sodass eine Familie nur einmal heruntergeladen wird.

Eine Schriftstärke, die eine Familie nicht mitliefert, wird in dem Schnitt gesetzt, den ein Browser dafür wählen würde (CSS-Font-Matching: über 500 zuerst die schwereren Schnitte, unter 400 zuerst die leichteren; bei einer Familie mit 400 und 700 wird eine 600 also zur 700, ebenso eine 550). Eine Neigung, die die Familie nicht mitliefert, wird in ihrem aufrechten Schnitt gesetzt. Beide Schnitte werden unverändert verwendet, in den Seitenbildern wie im PDF: Eine Displayschrift mit nur einer Schriftstärke behält auch für Fett ihre eigenen Buchstaben, und eine Familie ohne Kursive bleibt auch für Kursiv aufrecht.

Geladen werden die Schriftstärken, die die Konfiguration verlangt: für jede Familie normal und fett samt ihren Kursiven, dazu jede andere Schriftstärke, die eine Einstellung angibt, auch die für Fett (bodyText.boldFontWeight: 600 verlangt den Schnitt 600). Wenn sich eine Schriftstärke, die die Familie mitliefert, nicht laden ließ (offline ohne Datei im Cache, ein fehlgeschlagener Download, ein Schriftordner ohne die Datei), wird der Text in dem Schnitt der Familie gesetzt, der nach derselben Regel dafür einspringt, und postext check listet das als Warnung fontFallback auf: Die Zeilen dieses Textes können anders umbrechen als in der Sandbox.

Ein Zeichen, für das eine Schrift keine Glyphe hat, wird aus einer anderen Schrift gezeichnet. postext check liest die cmap-Tabelle jeder geladenen Schrift und meldet solche Zeichen einmal je Schrift für das ganze Buch als Warnung glyphFallback; mit --json enthält ihr data die Zeichen und ihre Anzahl.

Der Cache liegt in ~/.cache/postext (%LOCALAPPDATA%\postext\cache unter Windows); POSTEXT_CACHE_DIR oder --cache-dir verlegt ihn. --offline überspringt den Download. Eine nirgends gefundene Familie wird unter ihrem eigenen Namen in EB Garamond gesetzt, sodass Layout und PDF weiterhin übereinstimmen, und eine Warnung missingFont nennt sie. postext info zeigt, woher jede Familie stammt.

Ein Paket, das die Dateien einer lizenzierten Familie weglässt, kann dafür eine freie Familie ähnlicher Breite angeben (fallback in den fonts des Manifests, seit postext 1.42). postext sucht diese Familie dann nach den obigen Schritten und setzt die Schnitte, die das Buch nicht mitbringt, in deren Schnitten gleicher Stärke und Neigung unter dem Namen der lizenzierten Familie; das Layout kommt dem mit den Dateien nahe, und postext check meldet dafür kein missingFont. Eine Familie, die das Buch nur teilweise mitbringt, nimmt vom fallback nur die Neigung, von der sie keine Datei hat. Das PDF bettet die freie Schrift ein.

#Für Skripte und Agenten

Die Kommandozeile ist dafür gebaut, von anderen Programmen gesteuert zu werden, auch von Coding-Agenten.

  • --json gibt am Ende des Befehls ein JSON-Objekt auf der Standardausgabe aus; jede Meldung geht auf die Standardfehlerausgabe. Der Bericht listet auf, was geschrieben wurde, die Seiten, jede Warnung mit ihrer Quelle und wie lange jeder Schritt gedauert hat (in Millisekunden):
{
  "ok": true,
  "command": "pdf",
  "version": "1.22.1",
  "book": { "name": "notes", "id": "notes", "locale": "en", "chapters": 2 },
  "pages": 3,
  "outputs": [{ "kind": "pdf", "path": "notes.pdf", "bytes": 29746, "pages": 3 }],
  "warnings": [
    {
      "kind": "unknownResourceId",
      "severity": "warning",
      "message": "Unknown resource id \"map\" in ::resource — nothing is embedded (offset 26)",
      "at": "notes/02-more.md:5"
    }
  ],
  "timings": { "read": 13, "fonts": 8.4, "math": 28.2, "layout": 51.6, "pdf": 132.1, "total": 1638 },
  "exitCode": 0
}
  • Exit-Codes: 0 erledigt, 1 fehlgeschlagen, 2 falsche Verwendung (eine unbekannte Option, eine fehlende Eingabe), 3 check hat Fehler gefunden (oder mit --strict Warnungen), oder import-docx hat eine Word-Korrektur nicht übernommen.
  • Keine Rückfragen. Die Kommandozeile wartet nie auf eine Eingabe; ein Ordner, der nicht leer ist, wird abgelehnt, statt nachzufragen.
  • Standardausgabe: -o - schreibt ein PDF, ein Bild oder ein Paket dorthin, um es per Pipe weiterzureichen.
  • Geschwindigkeit. Die ausführbare Datei startet in wenigen Hundertstelsekunden. Ein kurzes Buch wird in deutlich unter einer Sekunde zu einem PDF oder einem Seitenbild; ein langes braucht so lange, wie sein Layout braucht (ein illustrierter Roman mit 140 Seiten etwa zehn Sekunden). Um ein paar Seiten eines langen Buchs anzusehen, kombinieren Sie --chapters mit image oder images --pages. Um über viele Änderungen hinweg an einem Buch zu arbeiten, lassen Sie postext build --watch laufen und lesen seine Ausgaben.

Der Agent-Skill verwendet die Kommandozeile, um die Seiten zu rendern, an denen er arbeitet, und um eine Portierung zu prüfen.

#Python

pip install postext macht die Kommandozeile zu einer Python-Bibliothek. Das Paket ist reines Python ohne Abhängigkeiten, und seine Version ist die von postext. Beim ersten Befehl lädt es die ausführbare Datei Ihres Systems aus dem GitHub-Release dieser Version herunter, prüft sie gegen SHA256SUMS und legt sie im oben beschriebenen Cache unter bin/<Version>/ ab. Zeigt POSTEXT_BIN auf eine ausführbare Datei, die Sie schon haben (aus Homebrew, Scoop oder einem eigenen Build), wird nichts heruntergeladen.

import postext
 
report = postext.pdf("book.postext", out="book.pdf", set={"page.dpi": 300}, locale="es")
print(report.output.pages)
for warning in report.warnings:
    print(warning.kind, warning.at, warning.message)
 
pdf = postext.pdf_bytes(open("book.postext", "rb").read())
  • Eine Funktion pro Befehl: pdf, html, epub, image, images, docx, import_docx, pack, unpack, info, check und build. Die Optionen behalten ihre Namen, mit Unterstrichen (color_space, font_dirs, dry_run). set nimmt ein Dictionary, config eine Datei oder ein Dictionary, chapters eine Zahl, eine Liste, ein range oder "1,3-5".
  • Berichte als Objekte. Jede Funktion führt ihren Befehl mit --json aus und gibt den Bericht zurück: outputs, pages, timings und warnings, jede Warnung ein Diagnostic mit kind, severity, message, at und page. info ergänzt chapters, resources und fonts, check ergänzt passed, error_count und warning_count.
  • Fehler als Ausnahmen. Ein Fehlschlag löst PostextError aus, eine falsche Option UsageError. Findet check Fehler, löst es ProblemsFound aus, dessen report sie auflistet; mit raise_on_problems=False gibt es den Bericht zurück.
  • Bytes. Ein Buch kann als Bytes eines .postext-Pakets übergeben werden. Mit out="-" kommt die Datei in report.content zurück; pdf_bytes, html_bytes, epub_bytes, image_bytes, docx_bytes und pack_bytes geben sie direkt zurück.
  • postext.Postext(binary, cwd=…, timeout=…) verwendet eine bestimmte ausführbare Datei, und python -m postext … ist die Kommandozeile selbst.

Jeder Aufruf startet die ausführbare Datei neu. Das README des Pakets führt alle Optionen auf.

#Wie sie gebaut ist

Die Kommandozeile ist das Paket postext-cli im Repository. Bun kompiliert sie mit der Engine und ihren Schreibern zu einer ausführbaren Datei pro System, und Skia (über @napi-rs/canvas) misst und zeichnet den Text, so wie das Canvas des Browsers in der Sandbox. Ein SVG-Bild, das ein Rasterbild enthält (ein als Data-URI eingebettetes PNG oder JPEG, wie es pdftocairo -svg für aus einem PDF ausgeschnittene Grafiken schreibt), wird stattdessen von resvg gezeichnet, weil der SVG-Renderer von Skia solche Bilder weglässt. Bei jedem Release werden die ausführbaren Dateien gebaut, unter Linux, Alpine, macOS und Windows ausgeführt und an das GitHub Release angehängt; npm erhält postext-cli und ein Paket postext-cli-<system> pro ausführbarer Datei.

So führen Sie sie aus einer Kopie des Repositorys aus:

pnpm install
pnpm --filter postext-cli start pdf book.postext
pnpm --filter postext-cli build:bin --current

Der erste Befehl führt sie aus ihren Quellen aus; der zweite schreibt die ausführbare Datei für diesen Computer nach packages/postext-cli/bin/.

#Unterschiede zur Sandbox

  • HTML ist das Drucklayout in Bildschirmgröße. Der Tab HTML der Sandbox setzt den Text für das Fenster neu.
  • --chapters setzt die Kapitel einzeln: Ihre Seitenzahlen beginnen neu, während die Sandbox die Nummerierung des Buchs fortführt.
  • Schriften kommen aus dem Buch, Ihren Ordnern, der ausführbaren Datei, Google Fonts oder Fontsource (für eine Familie, die Google Fonts nicht hat), nie aus den auf dem Computer installierten Schriften, sodass ein Buch auf jedem Rechner gleich herauskommt.
  • Die Sprache des Texts ist im Browser die des Dokuments (bodyText.shapingLanguage: 'document', der Standard seit postext 1.30). Das Canvas von Skia nimmt zwar eine Sprache entgegen, formt den Text aber ohne sie; die Kommandozeile misst daher die Formen der Standardsprache jeder Schrift und setzt ihre Bücher immer mit shapingLanguage: 'host', was auch immer die Konfiguration angibt; ihr PDF und ihre Bilder zeigen dieselben Formen. Ein Buch, dessen Schrift Formen für eine Sprache hat (ein katalanisches l·l, ein türkisches fi, die Ziffern einer chinesischen Schrift in einem englischen Buch), wird hier in den Standardformen gesetzt. Was 'document' sonst misst (die an einem Zeilenende getrennten Teile eines Worts, ein Wort von rechts nach links, ein Gestaltungstext), wird hier so gemessen, wie 'host' es misst, sodass eine Zeile an einem anderen Wort umbrechen kann als in der Sandbox.