Sie können pandoc unter Linux verwenden, um zwischen mehr als 40 Dateiformaten zu konvertieren. Sie können es auch verwenden, um ein einfaches Docs-as-Code-System zu erstellen, indem Sie in Markdown schreiben, in git speichern und in einem der unterstützten Formate veröffentlichen.
Inhaltsverzeichnis
Dokumentenkonvertierung und Docs-as-Code
Wenn Sie ein Dokument in einem der Pandocs haben viele unterstützte Dateiformate, die Umwandlung in einen der anderen ist ein Kinderspiel. Das ist ein praktisches Werkzeug!
Aber die wahre Stärke von Pandoc wird deutlich, wenn Sie es als Basis eines einfachen Docs-as-Code-Systems verwenden. Die Prämisse von docs-as-code besteht darin, einige der Techniken und Prinzipien der Softwareentwicklung zu übernehmen und sie auf das Schreiben von Dokumentationen, insbesondere für Softwareentwicklungsprojekte, anzuwenden. Sie können es jedoch auf die Entwicklung jeder Art von Dokumentation anwenden.
Softwareentwickler verwenden ihren Lieblingseditor oder integrierte Entwicklungsumgebung (IDE), um ihre Programme zu schreiben. Der von ihnen eingegebene Code wird in Textdateien gespeichert. Diese enthalten die Quellcode für das Programm.
Sie verwenden a Versionskontrollsystem, oder VCS (Git ist die beliebteste), um Änderungen am Quellcode während der Entwicklung und Verbesserung zu erfassen. Dies bedeutet, dass der Programmierer über eine vollständige Historie aller Versionen der Quellcodedateien verfügt. Er oder sie kann schnell auf jede frühere Version einer Datei zugreifen. Git speichert Dateien in einem Repository. Auf den Computern jedes Entwicklers gibt es ein lokales Repository und ein zentrales, gemeinsam genutztes Remote-Repository, das oft in der Cloud gehostet wird.
Wenn sie bereit sind, eine funktionierende Version des Programms zu erstellen, verwenden sie a Compiler um den Quellcode zu lesen und eine binäre ausführbare Datei zu generieren.
Indem Sie Ihre Dokumente in einer einfachen, textbasierten Auszeichnungssprache schreiben, können Sie ein VCS zur Versionskontrolle Ihres Schreibens verwenden. Wenn Sie bereit sind, ein Dokument zu verteilen oder zu veröffentlichen, können Sie pandoc verwenden, um beliebig viele verschiedene Versionen Ihrer Dokumentation zu generieren, einschließlich webbasierter (HTML), Textverarbeitung oder Schriftsatz (LibreOffice, Microsoft Word, TeX), portables Dokumentenformat (PDF), E-Book (ePub), und so weiter.
All dies können Sie mit einem einzigen Satz von versionierten, schlanken Textdateien erledigen.
Pandoc installieren
Um pandoc unter Ubuntu zu installieren, verwenden Sie diesen Befehl:
sudo apt-get install pandoc
Auf Fedora benötigen Sie den folgenden Befehl:
sudo dnf install pandoc
Auf Manjaro müssen Sie Folgendes eingeben:
sudo pacman -Syu pandoc
Sie können überprüfen, welche Version Sie installiert haben, indem Sie die Option –version verwenden:
pandoc --version
pandoc ohne Dateien verwenden
Wenn Sie pandoc ohne Befehlszeilenoptionen verwenden, akzeptiert es auch eingegebene Eingaben. Drücken Sie einfach Strg+D, um anzuzeigen, dass Sie mit der Eingabe fertig sind. pandoc erwartet, dass Sie im Markdown-Format eingeben, und generiert eine HTML-Ausgabe.
Schauen wir uns ein Beispiel an:
pandoc
Wir haben ein paar Zeilen Markdown eingegeben und sind dabei, Strg+D zu drücken.
Sobald wir dies tun, generiert pandoc die entsprechende HTML-Ausgabe.
Um mit pandoc etwas Nützliches zu tun, müssen wir jedoch wirklich Dateien verwenden.
Markdown-Grundlagen
Markdown ist eine leichtgewichtige Auszeichnungssprache, und bestimmten Zeichen wird eine besondere Bedeutung beigemessen. Sie können einen Nur-Text-Editor verwenden, um eine Markdown-Datei zu erstellen.
Markdown lässt sich gut ablesen, da keine optisch störenden Tags vom Text ablenken. Die Formatierung in Markdown-Dokumenten ähnelt der Formatierung, die sie darstellen. Im Folgenden sind einige der Grundlagen aufgeführt:
Um Text mit Kursivschrift hervorzuheben, schließen Sie ihn in Sternchen ein. *Das wird betont*
Verwenden Sie für fetten Text zwei Sternchen. **Dies wird fett gedruckt**
Überschriften werden durch das Nummernzeichen/die Raute (#) dargestellt. Der Text wird durch ein Leerzeichen vom Raute getrennt. Verwenden Sie einen Hash für eine Überschrift der obersten Ebene, zwei für eine Überschrift der zweiten Ebene und so weiter.
Um eine Liste mit Aufzählungszeichen zu erstellen, beginnen Sie jede Zeile der Liste mit einem Sternchen und fügen Sie vor dem Text ein Leerzeichen ein.
Um eine nummerierte Liste zu erstellen, beginnen Sie jede Zeile mit einer Ziffer gefolgt von einem Punkt und fügen Sie dann vor dem Text ein Leerzeichen ein.
Um einen Hyperlink zu erstellen, schließen Sie den Namen der Site in eckige Klammern ([]) und die URL in Klammern [()] so: [Link to How to Geek](https://www.wdzwdz.com/).
Um ein Bild einzufügen, geben Sie ein Ausrufezeichen direkt vor eckigen Klammern (![]). Geben Sie einen beliebigen alternativen Text für das Bild in die Klammern ein. Schließen Sie dann den Pfad zum Bild in Klammern ein [()“]. Hier ist ein Beispiel: .
Wir werden im nächsten Abschnitt weitere Beispiele für all dies behandeln.
Konvertieren von Dateien
Dateikonvertierungen sind unkompliziert. pandoc kann normalerweise anhand der Dateinamen herausfinden, mit welchen Dateiformaten Sie arbeiten. Hier generieren wir eine HTML-Datei aus einer Markdown-Datei. Die Option -o (Ausgabe) teilt pandoc den Namen der Datei mit, die wir erstellen möchten:
pandoc -o sample.html sample.md
Unsere Beispiel-Markdown-Datei sample.md enthält den kurzen Abschnitt von Markdown, der in der Abbildung unten gezeigt wird.
Eine Datei namens sample.html wird erstellt. Wenn wir auf die Datei doppelklicken, öffnet unser Standardbrowser sie.
Lassen Sie uns nun ein generieren Dokumentformat öffnen Textdokument, in dem wir öffnen können LibreOffice-Autor:
pandoc -o sample.odt sample.md
Die ODT-Datei hat denselben Inhalt wie die HTML-Datei.
Eine nette Geste ist, dass der alternative Text für das Bild auch verwendet wird, um automatisch eine Bildunterschrift für die Abbildung zu generieren.
Dateiformate angeben
Die Optionen -f (from) und -t (to) werden verwendet, um pandoc mitzuteilen, von und in welche Dateiformate Sie konvertieren möchten. Dies kann nützlich sein, wenn Sie mit einem Dateiformat arbeiten, das eine Dateierweiterung mit anderen verwandten Formaten teilt. Beispielsweise, TeX, und Latex beide verwenden die Erweiterung „.tex“.
Wir verwenden auch die Option -s (Standalone), damit pandoc alle LaTeX-Präambeln generiert, die für ein vollständiges, in sich geschlossenes und wohlgeformtes LaTeX-Dokument erforderlich sind. Ohne die Option -s (Standalone) wäre die Ausgabe immer noch wohlgeformtes LaTeX, das in ein anderes LaTeX-Dokument eingefügt werden könnte, es würde nicht richtig als eigenständiges LaTeX-Dokument geparst.
Wir geben folgendes ein:
pandoc -f markdown -t latex -s -o sample.tex sample.md
Wenn Sie die Datei „sample.tex“ in einem Texteditor öffnen, sehen Sie das generierte LaTeX. Wenn Sie einen LaTeX-Editor haben, können Sie die TEX-Datei öffnen, um eine Vorschau der Interpretation der LaTeX-Satzbefehle anzuzeigen. Durch das Verkleinern des Fensters, um es in das Bild unten einzupassen, sah das Display beengt aus, aber in Wirklichkeit war es in Ordnung.
Wir haben einen LaTeX-Editor namens . verwendet Texmaker. Wenn Sie es in Ubuntu installieren möchten, geben Sie Folgendes ein:
sudo apt-get install texmaker
In Fedora lautet der Befehl:
sudo dnf install texmaker
Verwenden Sie in Manjaro:
sudo pacman -Syu texmaker
Konvertieren von Dateien mit Vorlagen
Sie beginnen wahrscheinlich die Flexibilität zu verstehen, die Pandoc bietet. Sie können einmal schreiben und in fast jedem Format veröffentlichen. Das ist eine großartige Leistung, aber die Dokumente sehen ein wenig nach Vanille aus.
Mit Vorlagen können Sie bestimmen, welche Stile pandoc beim Generieren von Dokumenten verwendet. Beispielsweise können Sie pandoc anweisen, die in a . definierten Stile zu verwenden Cascading Style Sheets (CSS)-Datei mit der Option –css.
Wir haben eine kleine CSS-Datei erstellt, die den folgenden Text enthält. Es ändert den Abstand über und unter der Ebenenüberschrift um einen Stil. Es ändert auch die Textfarbe in Weiß und die Hintergrundfarbe in einen Blauton:
h1 {
color: #FFFFFF;
background-color: #3C33FF;
margin-top: 0px;
margin-bottom: 1px;
}
Der vollständige Befehl ist unten. Beachten Sie, dass wir auch die eigenständige Option (-s) verwendet haben:
pandoc -o sample.html -s --css sample.css sample.md
pandoc verwendet den einzelnen Stil aus unserer minimalistischen CSS-Datei und wendet ihn auf den Level-1-Header an.
Eine weitere Feinabstimmungsoption, die Ihnen beim Arbeiten mit HTML-Dateien zur Verfügung steht, besteht darin, HTML-Markup in Ihre Markdown-Datei aufzunehmen. Diese wird als Standard-HTML-Markup an die generierte HTML-Datei übergeben.
Diese Technik sollte jedoch reserviert werden, wenn Sie nur HTML-Ausgaben generieren. Wenn Sie mit mehreren Dateiformaten arbeiten, ignoriert pandoc das HTML-Markup für Nicht-HTML-Dateien und wird als Text an diese weitergegeben.
Wir können auch festlegen, welche Stile beim Generieren von ODT-Dateien verwendet werden. Öffnen Sie ein leeres LibreOffice Writer-Dokument und passen Sie die Überschriften- und Schriftstile an Ihre Bedürfnisse an. In unserem Beispiel haben wir auch eine Kopf- und Fußzeile hinzugefügt. Speichern Sie Ihr Dokument als „odt-template.odt“.
Wir können dies jetzt als Vorlage mit der Option –reference-doc verwenden:
pandoc -o sample.odt --reference-doc=odt-template.odt sample.md
Vergleichen Sie dies mit dem ODT-Beispiel von früher. Dieses Dokument verwendet eine andere Schriftart, hat farbige Überschriften und enthält Kopf- und Fußzeilen. Es wurde jedoch aus genau derselben Markdown-Datei „sample.md“ generiert.
Referenzdokumentvorlagen können verwendet werden, um verschiedene Phasen der Dokumenterstellung anzugeben. Beispielsweise könnten Sie Vorlagen mit den Wasserzeichen „Entwurf“ oder „Zur Überprüfung“ haben. Für ein fertiges Dokument wird eine Vorlage ohne Wasserzeichen verwendet.
PDFs erstellen
Pandoc verwendet standardmäßig die LaTeX-PDF-Engine, um PDF-Dateien zu generieren. Der einfachste Weg, um sicherzustellen, dass die entsprechenden LaTeX-Abhängigkeiten erfüllt sind, besteht darin, einen LaTeX-Editor wie Texmaker zu installieren.
Das ist jedoch eine ziemlich große Installation – Tex und LaTeX sind beide ziemlich umfangreich. Wenn Ihr Festplattenspeicher begrenzt ist oder Sie wissen, dass Sie TeX oder LaTeX nie verwenden werden, ziehen Sie es vielleicht vor, eine ODT-Datei zu generieren. Dann können Sie es einfach in LibreOffice Writer öffnen und als PDF speichern.
Docs-as-Code
Die Verwendung von Markdown als Schreibsprache bietet mehrere Vorteile, darunter die folgenden:
Das Arbeiten in Nur-Text-Dateien ist schnell: Sie werden schneller geladen als Textverarbeitungsdateien ähnlicher Größe und neigen dazu, sich auch schneller durch das Dokument zu bewegen. Viele Editoren, darunter gedit , Vim und Emacs, verwenden Syntaxhervorhebung mit Markdown-Text.
Sie haben eine Zeitleiste aller Versionen Ihrer Dokumente: Wenn Sie Ihre Dokumentation in einem VCS wie Git speichern, können Sie die Unterschiede zwischen zwei beliebigen Versionen derselben Datei leicht erkennen. Dies funktioniert jedoch nur dann wirklich, wenn es sich um Nur-Text-Dateien handelt, da dies von einem VCS erwartet wird.
Ein VCS kann aufzeichnen, wer wann Änderungen vorgenommen hat: Dies ist besonders hilfreich, wenn Sie häufig mit anderen an großen Projekten zusammenarbeiten. Es bietet auch eine zentrale Ablage für die Dokumente selbst. Viele Cloud-gehostete Git-Dienste wie GitHub, GitLab, und Bit Bucket, haben kostenlose Stufen in ihren Preismodellen.
Sie können Ihre Dokumente in mehreren Formaten generieren: Mit nur wenigen einfachen Shell-Skripten können Sie die Stile aus CSS und Referenzdokumenten abrufen. Wenn Sie Ihre Dokumente in einem VCS-Repository speichern, das in Kontinuierliche Integration und kontinuierliche Bereitstellung (CI/CD)-Plattformen können sie automatisch generiert werden, wenn die Software erstellt wird.
Abschließende Gedanken
Es gibt viele weitere Optionen und Funktionen in pandoc als das, was wir hier behandelt haben. Die Konvertierungsprozesse für die meisten Dateitypen können optimiert und verfeinert werden. Um mehr zu erfahren, sehen Sie sich die hervorragenden Beispiele im offiziellen (und äußerst detaillierten) Pandoc-Webseite.