Erstellen Sie PDFs aus Markdown mit Pandoc und Latex

Kernpunkte

Dieser Artikel -Autor Chris Ward erklärt, wie Markdown -Dateien mit Pandoc und Latex für den Open -Source -Board -Spiel -Chip -Shop in PDFs konvertiert werden. Spielkomponenten werden mit Markdown geschrieben und die Spielwebsite wird auch von diesen Dateien generiert.

pandoc (ein Open -Source -Markup -Conversion -Tool) und Latex (eine Dokumenterklärung und ein Layout -System) werden verwendet, um PDFs aus Markdown -Dateien zu generieren. Trotz ihrer leistungsstarken Funktionen können sie mehrere PDFs nicht auf einer einzelnen Seite kombinieren. Daher verwendet Ward das Befehlszeilen -Tool PDFJAM, um diese Anforderung zu erfüllen.

Der Autor bietet eine detaillierte Anleitung zur Installation der erforderlichen Abhängigkeiten (Markdown, Jekyll, Pandoc, Latex, PDFJAM) und führt allmählich den Erstellungsprozess ein, einschließlich der Generierung von PDFs aus Markdown, Erstellen von Latex -Dateien und Verwendung von PDFJAM, um Karten zu übertragen, um Karten zu übertragen Kombinieren Sie auf einer Seite.

Der ideale Workflow des Autors besteht darin, eine PDF -Datei zu generieren, während der Besucher sie anfordert. Mit diesem Ansatz kann die PDF -Kartenversion auch von der HTML -Seite unterscheiden, ohne komplexe CSS -Regeln zu verwenden.

Wenn Sie einige meiner Beiträge auf SitePoint oder anderswo gelesen haben, wissen Sie wahrscheinlich, dass ich an einem Brettspiel arbeite. Mit diesem Spiel namens Chip Shop können Sie in den 1980er Jahren eine Computerfirma betreiben.

Als Teil des Projekts habe ich versucht, das gesamte Spiel so weit wie möglich zu eröffnen. Nach einigen Versuchen habe ich beschlossen, Markdown als grundlegendes Framework für die meisten Spielkomponenten (insbesondere Karten und Anweisungen) zu verwenden.

Da die Spielwebsite Jekyll verwendet, wird die Spielwebsite aus der Markdown -Datei generiert. Ich werde eine Premium-Pre-Box-und selbstgedruckte Version des Spiels erstellen, für die ich eine PDF aus einer Markdown-Datei generieren muss.

Ziel

Mein idealer Workflow ist es, PDF -Dateien beim Generieren der Website zu generieren, nicht wenn der Besucher sie anfordert. Dies schließt die Option mit WKHTMLTOPDF aus, die ich normalerweise für die PDF -Erzeugung verwende, da sie PDF aus generiertem HTML generiert. Ein weiterer Grund ist, dass ich möchte, dass die PDF -Kartenversion von der HTML -Seite anders aussieht, und Jekyll fehlt jede Art von "Ansichtsmodus" -Funktionalität, um dies zu erreichen, ohne komplexe CSS -Regeln zu verwenden.

Die Karten-Markdown-Vorlagendatei von Chip Shop Game enthält viele Markdown-Vorinformationsfelder für Spielmechanik, nicht alle Felder werden auf jeder Karte verwendet. Zum einfachen Drucken muss ich die Karten so oft wie möglich auf die A4 -Seite setzen - in diesem Fall ein 3 × 3 -Gitter. Letztendlich muss die Seite auf beiden Seiten gedruckt werden, aber ich habe das noch nicht implementiert.

pandoc und latex

Jede Web -Suche, die PDF -Lösungen aus Markdown generiert, führt Sie auf dem Pfad von Pandoc. Pandoc ist ein Open Source Swiss Army -Messermesser -Umwandlungswerkzeug, das eine Vielzahl von Eingangs- und Ausgangsmarkierungsformaten unterstützt.

Um PDFs mit Pandoc zu generieren, ist Latex erforderlich. Latex stammt aus der wissenschaftlichen Forschungsgemeinschaft und ist ein Dokumenterklärungs- und Layout -System. In Kombination mit Pandoc und Latex können wir Variablen verwenden, um PDFs aus einer Reihe von Markdown-Dateien zu generieren und die Markdown-Vorinformation zu unterstützen.

Trotz der leistungsstarken Pandoc und Latex kann ich keine Möglichkeit finden, mehrere PDFs (Karten) auf einer einzelnen Seite zu kombinieren, insbesondere wenn ich Variablen in einer Markdown -Datei verwendet habe. Nach viel Nachforschungen habe ich mich für PDFJAM entschieden, ein einfaches Befehlszeilen -Tool für diesen Bedarf.

Abhängigkeiten

installieren

Markdown

Sie benötigen keine zusätzliche Markdown -Software, abgesehen davon, dass es möglicherweise einen Editor benötigt. Es gibt viele Redakteure, und ich schlage vor, Sie lesen einige SitePoint -Artikel, um Ihre Wahl zu treffen.

Jekyll

Ich werde weiterhin Jekyll verwenden, um den Build -Prozess in den Beispielen meines Spiels zu veranschaulichen. Wenn Sie jedoch keine Website benötigen, ist dies kein notwendiger Bestandteil der PDF -Generation.

pandoc

Auf meinem Mac habe ich Pandoc mit Homebrew installiert, aber alle Betriebssysteme haben entsprechende Optionen.

latex

Es gibt viele Wörter über die beste Möglichkeit, Latex zu installieren, abhängig von Ihren Anforderungen oder wie Sie es verwenden möchten. Die vollständige Installation seiner gemeinsamen Werkzeuge und Bibliotheken kann nahe 2 GB liegen, aber für die meisten Zwecke ist eine Mindestinstallation ausreichend. Lesen Sie die Download -Seite des Projekts, um die Option zu finden, die für Sie am besten funktioniert.

In diesem Tutorial werden wir die Xelatex -Engine verwenden, da ich benutzerdefinierte Schriftarten verwende. Sie können jedoch jeden Motor auswählen, der die spezifischen Funktionen bietet, die Sie benötigen.

pdfjam

Abhängig davon, wie Sie Latex installieren, haben Sie möglicherweise PDFJAM installiert. (Geben Sie den PDFJAM in das Terminal ein.) Wenn Sie ihn nicht installiert haben, suchen Sie hier nach Installationsdetails.

Bauprozess

Nach einiger Überlegungen führe ich ein Bash -Skript aus, das lokal ausgeführt wird, die derzeit die beste Wahl zu sein. Es gibt einen besseren Weg, aber es funktioniert, und ich kann den Prozess später verbessern und ihn in ein kontinuierliches Integrationssystem oder Git -Haken übertragen.

Bash -Skripte auf GitHub anzeigen.

führen wir dieses Skript jetzt Schritt für Schritt vor.

Einstellungen

<code class="language-bash">bundle install
bundle update

rm -dfr _site
rm -dfr pod</code>

Diese Befehle stellen sicher, dass die von Jekyll zum Erstellen einer Website erforderlichen Ruby -Abhängigkeiten auf dem neuesten Stand sind, und wir haben alle vorhandenen Website- und Druckordner gelöscht.

Erstellen Sie eine Website

<code class="language-bash">jekyll build
mkdir -p pod/pdf/cards</code>

Als nächstes erstellen wir die Website und erstellen einen Ordner für die gedruckte Version der Karte.

PDF aus Markdown

generieren

Erstellen wir einen Ordner, der jede Markdown -Datei PDF -Version enthält:

<code class="language-bash">for filename in _cards/*.md; do
  echo $filename
  pandoc --from=markdown+yaml_metadata_block --template _layouts/cards.latex -o pod/pdf/cards/"$(basename "$filename" .md)".pdf --latex-engine=xelatex $filename
done</code>

Dieses Skript übernimmt jede Markdown-Datei im Verzeichnis _cards und stellt sicher, dass das Feld Markdown-Vorinformationen beobachtet wird. Verwenden der Cards.latex -Vorlage (die wir später abdecken werden) der korrekte Latexmotor gibt einen PDF mit dem entsprechenden Namen aus.

Latex -Datei

Der größte Teil der Magie, Kartendateien aus Pandoc zu generieren, findet in Latexvorlagen statt.

Latexvorlagen auf GitHub anzeigen.

Latex ist neu für mich, aber es ist nicht zu kompliziert. Ich werde erklären, was ich aus der Standard -Latex -Datei (befindet sich in pandoc_install_dir/data/templates/default.latex) geändert habe, damit die Karte ordnungsgemäß funktioniert. Ich empfehle Sharelatex.com für die Vorschau bei der Bearbeitung von Latexdateien.

<code class="language-bash">bundle install
bundle update

rm -dfr _site
rm -dfr pod</code>

Wir benötigen eine bestimmte Seitengröße und verwenden die Spalten, um die Kosten und die Punktzahl der Karte später anzuzeigen. Wir verwenden Grafiken und benutzerdefinierte Schriftarten, daher benötigen wir diese Pakete.

Wir versuchen, ein klares und prägnantes einfaches Layout zu erstellen. So implementieren wir es:

<code class="language-bash">jekyll build
mkdir -p pod/pdf/cards</code>

Ich denke, ein Großteil der oben genannten ist für jeden, der verwendet wird, um zu codieren oder zu markieren, recht leicht zu verstehen. Wir erstellen Elemente der Karte, richten sie aus, setzen die Schriftgröße ein und prüfen, ob Werte vorhanden sind, und geben Sie sie dann aus, damit die Karte nicht mit leeren Feldern endet.

Wir ändern die Größe des Bildes zu einer bestimmten Größe und zentrieren Sie es. Die Kosten- und Bewertungswerte sind in zwei Spalten angeordnet, mit dem Befehl starten {tabular} festgelegt, und die Anzahl der Spalten wird unter Verwendung der Anzahl von l festgelegt.

Karten auf einer Seite kombinieren

Wir verwenden PDFJAM, um eine große PDF -Datei mit jeder einzelnen PDF -Karte zu erstellen:

<code class="language-bash">for filename in _cards/*.md; do
  echo $filename
  pandoc --from=markdown+yaml_metadata_block --template _layouts/cards.latex -o pod/pdf/cards/"$(basename "$filename" .md)".pdf --latex-engine=xelatex $filename
done</code>

Verwenden Sie diesen Befehl, wir geben Folgendes an:

• Die Seitenorientierung sollte immer vertikal sein
• Jedes einzelne PDF sollte ausgearbeitet werden
• Gittergröße
• Dateiname Suffix
• Dateiname

pdfjam kann einen Fehler geben, wenn Sie nicht in das Arbeitsverzeichnis ausgeben. Daher verschiebe ich die Datei dorthin, wo ich sie tatsächlich möchte (hoffentlich wird sie in Zukunft gelöst). Hier können wir auch eine einzige PDF -Datei löschen, wenn wir sie nicht benötigen.

Das ist es - wir haben eine druckbare PDF von Websites und Spielkarten.

Skript ausführen

Ich benutze ./build.sh, um das Build -Skript auszuführen. Da es viele Bilder und PDF -Verarbeitung gibt, dauert es ungefähr fünf bis zehn Minuten. Dann habe ich ein separates Skript, um diese Ordner auf dem Webserver bereitzustellen.

Nächste Schritte

Dieser Prozess habe eine Weile gebraucht, um es richtig zu machen, aber es ist jetzt gut genug, um den Prozess und das Layout nach dem Spieltest weiter zu verbessern.

Ich hoffe, Sie finden meine Forschung und Experimente für Ihr Projekt nützlich. Wenn Sie Kommentare oder Vorschläge haben, lassen Sie es mich bitte wissen.

FAQs (FAQs) zum Erstellen von PDFs aus Markdown mit Pandoc und Latex

Wie installiere ich Pandoc und Latex in meinem System?

Um PANDOC zu installieren, können Sie es auf der offiziellen Website verwenden ( https://www.php.cn/link/8f1dd6e7a88b9cf615c146330c591ba9 .

Kann ich das Erscheinungsbild von PDFs mit Pandoc und Latex anpassen?

Ja, Sie können Latexvorlagen verwenden, um das Erscheinungsbild des PDF anzupassen. Pandoc verwendet die Standardvorlage, um PDFs zu generieren. Sie können jedoch Ihre eigenen Vorlagen mit der Option --template angeben. Sie können Ihre eigenen Vorlagen erstellen oder eine der vielen online verfügbaren Vorlagen verwenden, z.

Wie konvertieren Sie Markdown -Dateien mit Pandoc und Latex in PDF?

Um eine Markdown -Datei in ein PDF umzuwandeln, können Sie den folgenden Befehl in einer Terminal- oder Eingabeaufforderung verwenden: pandoc yourfile.md -o yourfile.pdf. Ersetzen Sie yourfile.md durch den Namen Ihrer Markdown -Datei und yourfile.pdf durch den gewünschten Namen Ihrer PDF -Datei. Dieser Befehl fordert PANDOC mit, um Markdown -Dateien mithilfe der Standard -Latex -Vorlage in PDF umzuwandeln.

(Der Rest des FAQ -Inhalts entspricht dem Originaltext, der hier weggelassen wird, um Duplizierung zu vermeiden)

Das obige ist der detaillierte Inhalt vonErstellen Sie PDFs aus Markdown mit Pandoc und Latex. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!