Dokumentationen mit Joplin und Pandoc erstellen

Joachim on 18.4.2019

Ansatt Joplin kann auch jeder beliebiger Editor verwendet werden. Ich nutze Joplin um meine Notizen bzw. Dokumentationen zu verwalten. Ein Datenaustausch ist z.b. über Dropbox möglich, so habt Ihr überall eure Notizen griffbereit :-)

Als Beispiel nutze ich diese Dokumentation. Als Ziel soll eine Generierung nach Word (docx), OpenOffice (odt), PDF, und HTML stehen.

Was wird benötigt:

  1. Joplin
  2. Pandoc
  3. MiKTeX

1.1.1 Joplin

Joplin ist eine kostenlose Open-Source-Anwendung, die Notizen in Notizbüchern verwaltet und zudem noch To-Dos beherrscht. Die Notizen sind durchsuchbar, können direkt aus den Anwendungen oder aus dem eigenen Texteditor kopiert, markiert und verändert werden. Notizen können ganz normal verfasst werden, alternativ ist auch das Verfassen von Texten in Markdown möglich, hier lassen sich dann diverse Ansichtsmodi einstellen.

Joplin bietet viele Features, die man von einer Notizverwaltung erwartet. Hier ein Auszug:

  • ListeneintragApps für Linux/macOS/Windows/Android/iOS und den Terminal (ja, es gibt auch eine CLI-Version :))
  • ListeneintragEnde-zu-Ende-Verschlüsselung
  • Synchronisation mit verschiedenen Diensten, darunter NextCloud, WebDAV und OneDrive. Dropbox.
  • Import von Enex-Dateien (Evernote-Exportformat) und Markdown-Dateien.
  • Export von JEX-Dateien (Joplin Export Format) und Raw-Dateien.
  • Unterstützen Sie Notizen, To-Dos, Tags und Notebooks.
  • Sortierung der Notizen nach mehreren Kriterien – Titel, aktualisierte Zeit, etc.
  • Unterstützung von Alarmen (Benachrichtigungen) in mobilen und Desktop-Anwendungen.
  • Offline-Modus, die gesamten Daten sind auch ohne Internetverbindung immer auf dem Gerät verfügbar
  • Markdown Unterstützung, Bilder und und Formatierungen werden in Desktop- und mobilen Anwendungen angezeigt. Unterstützung für zusätzliche Funktionen wie Mathe-Notation und Checkboxen.
  • Unterstützung von Dateianhängen – Bilder werden angezeigt, andere Dateien werden verlinkt und können in der jeweiligen Anwendung geöffnet werden.
  • Suchfunktionalität
  • Geo-Location-Unterstützung
  • Web-Clipper
  • Unterstützt mehrere Sprachen

Zusammen mit pandoc u. MikTeX sind Exporte nach DOCX, RTF, PDT, ODT und HTML kein Problem :-)

1.1.2 Pandoc

Pandoc ist ein freier Parser für Multidokumentenformate. Das Computerprogramm dient zur Umwandlung verschiedener dokumentbasierter Dateiformate ineinander. Pandoc basiert hierbei auf einer erweiterten Variante der Auszeichnungssprache Markdown.

1.1.3 MiKTeX

MiKTeX ist eine TeX-Distribution für Windows. Die ergänzenden MiKTeX Tools wurden ebenso auf GNU/Linux portiert.

Mit einem Installationsprogramm werden die benötigten TeX-Pakete aus dem Internet oder von einem local package repository geladen und danach auf dem Rechner installiert. Ein Aktualisieren der Pakete ist möglich, außerdem werden benötigte, noch nicht vorhandene Pakete bei Bedarf nachgeladen und installiert.

TeX, ist ein von Donald E. Knuth ab 1977 entwickeltes und 1986 fertiggestelltes Textsatzsystem mit eingebauter Makrosprache (die ebenfalls TeX genannt wird). Im engeren Sinn ist TeX ein einzelnes Programm, das einfache Textdateien und Zeichensatzdateien einliest und eine binäre Dokumentdatei erzeugt, die von anderen Programmen ausgedruckt, angezeigt oder anderweitig für eine Ausgabe weiterverarbeitet werden kann.

1.1.4 Markdown

Markdown ist eine Auszeichnungssprache für Texte und folgt damit einem sogenannten WYSIWYM-Ansatz (What You See Is What You Mean). Für einige mag das nach einer Programmiersprache klingen – vorstellen sollte man sich das eher als einer einfache Konvention dafür, wie man Text in eine einfach Textdatei schreibt.

Schreibt man einen Text in Markdown, markiert man mit Sonderzeichen und Einrückungen im Text, wie diese so ausgezeichneten Stellen später einmal (wenn man den Text in ein anderes Format übersetzt) aussehen sollen.

2 Markdown - Syntax

Eine Leerzeile trennt Absätze voneinander.
Ein Zeilenumbruch wird durch zwei Leerzeichen vor dem Umbruch herbeigeführt.

2.1 Überschriften

# Überschrift 1. Grad 
## Überschrift 2. Grad 
### Überschrift 3. Grad 
#### Überschrift 4. Grad 
##### Überschrift 5. Grad 
###### Überschrift 6. Grad 

ergibt:

2.2 Text-Auszeichnung

*Kursiv*
**Fett**
***_Fett und Kursiv_***

ergibt:

Kursiv
Fett
Fett und Kursiv

2.3 Unsortierte Liste

Listeneintrag
* Listeneintrag
* Listeneintrag
    * (vorangestellter Tabulator)

ergibt:

  • Listeneintrag
  • Listeneintrag 2
  • Listeneintrag 3
    • (vorangestellter Tabulator)

Statt dem * kann auch ein + oder ein - verwendet werden.

2.4 Sortierte Liste

Punkt 1
1. Punkt 2
1. Punkt 3
1. Punkt 4

ergibt:

  1. Punkt 1
  2. Punkt 2
  3. Punkt 3
  4. Punkt 4

Die Nummerierung spielt dabei keine Rolle.

Verschachtelungen werden durch zwei Leerzeichen oder TAB eingerückt.

[Beschreibung](http://link.de)
<http://link.de>
<mail(at)adresse(dot)de>
[interner Link](https://www.baireuther.de/page/markdown_befehle/#listen)

ergibt:

Beschreibung
http://link.de
mail(at)adresse(dot)de

2.6 Grafiken

![Logo](../../_resources/a0cb294054cd4c01ba23463853c65719.png)

ergibt:

Logo
Logo

2.7 Zitate

Zitate wie
>in E-Mails

ergibt:

Zitate wie
in E-Mails

2.8 Trennlinie

---  

ergibt:


Mit einem Backslash “\” lassen sich Formatierungen abschalten.

Wenn in einem Text eine Fußnote[^anmerkung] erscheinen soll, so wird diese mit eckiger Klammer und ^ vermerkt.

[^anmerkung]: Text zur Anmerkung

Code-Blöcke werden durch eine Einrückung mittels Tabulator oder vier Leerzeichen markiert.
Code in einer Zeile wird durch `Code-Text` eingefügt.

Code-Text

2.9 Tabellen

| Links | Rechts | Zentriert | 
|-------|-------:|:---------:| 
| 1 | 3 | 5 | | 2 | 4 | 6 | 

ergibt:

Links Rechts Zentriert
1 3 5
2 4 6

2.10 Metadaten

Zu Beginn eines Dokuments kann man die Metadaten setzen:

% Titel
% Autor
% Jahr

Meta - Angaben des Dokuments lassen sich bei Pandoc als YAML-Header angeben.

Muster META-Daten:

---
title: "Muster"
author: Joachim Nyenhuis
email: j(dot)nyenhuis(at)kvw-muenster(dot)de
lang: de-DE
date: \today
titlepage: true
titlepage-color: "FFFFFF"
titlepage-text-color: "084F55"
titlepage-rule-color: "084F55"
titlepage-rule-height: 2
logo: "/Sicherung/Markdown/Images/logos/logokvw.pdf"
logo-width: 500
link-citations: true
...
LaTeX - Befehle
Hier steht der ganze Text!

Zwischen --- und ... befindet sich der YAML-Header. Nach dem Header folgen noch einige LaTeX-Befehle.

  • \pagenumbering{globble} verschluckt die Seitenzahlen, bis sie mit \pagenumbering{arabic} wieder aktiviert wird
  • \pagebreak Seitenumbrüche
  • \tableofcontens - Inhaltsverzeichnis

3 Generierung der Dokumentation

3.1 Pandoc Parameterbeschreibungen

-o → Output (Ausgabedatei)
-s → Standalone (Header und Footer werden erzeugt)
--template template → Vorlage übergeben,
 z.B. --template=vorlage.odt für OpenDocument
--toc → ein Inhaltsverzeichnis wird erzeugt
    --toc-depth=NUMBER → Tiefe des Inhaltsverzeichnisses
--number-sections : aktiviert die Nummerierung vor den jeweiligen Überschriften (1.,
 1.1,
 1.2 usw.)
-V lang=de-DE → deutsche Sprache
-V papersize=a4paper : Seitengröße ist A4-Papier
-V geometry:margin=2cm : 2cm Seitenrand überall
--pdf-engine=lualatex : für andere Schriftarten ist diese LaTex-Engine nötig
-V fontfamily=libertine : Linux Libertine als Standardschrift (muss als TeX-Font vorliegen)
-V monofont=inconsolata : Inconsolata als Code-Schriftart (muss als TeX-Font vorliegen)
-V fontsize=12pt : Schriftgröße
-V breakurl : lange URLs korrekt umbrechen
-V hyphens=URL : URLs korrekt trennen

3.2 Templates

Mit dem Parameter --data-dir kann der Pfad angegeben werden wo sich die Templates befinden. Ohne diesen Parameter sucht Pandoc im Verzeichnis:

C:\Benutzer\USERNAME\AppData\Roaming\pandoc\templates

3.3 Resourcen Verzeichnis

Mit dem Parameter –resource-path setz ich den Pfad wo sich die entsprechenden Resourcen befinden z.B. CSS-Datei, Bilder usw. Falls dieser Parameter unter Windows nicht gesetzt ist, sucht pandoc im Arbeitsverzeichnis.

3.4 DOCX

pandoc.exe --data-dir [VERZEICHNIS] "[VERZEICHNIS]/MD/Joachim/TODO/Dokumentationen mit Joplin und Pandoc erstellen.md"  -f markdown --toc -V toc-title:"Inhaltsverzeichnis" --number-sections -V lang=de-DE -V geometry=a4paper -V geometry:margin=2cm -o "[VERZEICHNIS]\Dokumente/Dokumentationen mit Joplin und Pandoc erstellen.docx"

3.5 LATEX

pandoc.exe --data-dir [VERZEICHNIS] "[VERZEICHNIS]/MD/Joachim/TODO/Dokumentationen mit Joplin und Pandoc erstellen.md" 
  -o "[VERZEICHNIS]\Dokumente/Dokumentationen mit Joplin und Pandoc erstellen.latex"

3.6 RTF

pandoc.exe --data-dir M:\Sicherung\Markdown -s "[VERZEICHNIS]/MD/Joachim/TODO/Dokumentationen mit Joplin und Pandoc erstellen.md" 
  -f markdown --toc -V toc-title:"Inhaltsverzeichnis" --number-sections -V lang=de-DE -V geometry=a4paper 
  -V geometry:margin=2cm -o "[VERZEICHNIS]\Dokumente/Dokumentationen mit Joplin und Pandoc erstellen.rtf"

3.7 ODT

pandoc.exe --data-dir [VERZEICHNIS] "[VERZEICHNIS]/MD/Joachim/TODO/Dokumentationen mit Joplin und Pandoc erstellen.md" 
  -f markdown --toc -V toc-title:"Inhaltsverzeichnis" --number-sections -V lang=de-DE -V geometry=a4paper 
  -V geometry:margin=2cm -o "[VERZEICHNIS]\Dokumente/Dokumentationen mit Joplin und Pandoc erstellen.odt"

3.8 PDF

pandoc.exe --data-dir [VERZEICHNIS] "[VERZEICHNIS]/MD/KVW/Datenbanken/Dokumentationen mit Joplin und Pandoc erstellen.md" 
  -f markdown --toc -V toc-title:"Inhaltsverzeichnis" --number-sections -V lang=de-DE -V geometry=a4paper 
  -V geometry:margin=2cm --template eisvogel.latex --pdf-engine=xelatex --highlight-style tango 
  -o "[VERZEICHNIS]\Dokumente/Dokumentationen mit Joplin und Pandoc erstellen.pdf"

Für die PDF-Generierung benutze ich das Template Eisvogel! Das Template einfach in den Ordner C:\Benutzer\USERNAME\AppData\Roaming\pandoc\templates kopieren oder in dem Templateverzeichnis, was mit dem Parameter --data-dir angegeben wurde!

Link: Template Eisvogel

Mit dem Parameter --listings gibt es Probleme das die Box auf dem vorherigen Text liegt!

Lösung:

Im YAML-Header folgendes eintragen:

header-includes: |
  \usepackage{fvextra}
  \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,commandchars=\\\{\}}

fvextra provides several extensions to fancyvrb, including automatic line breaking and improved math mode.

3.9 PDF-Präsentation

ACHTUNG: Spezielle Seitengestaltung!

pandoc.exe --data-dir [VERZEICHNIS] -t beamer  "[VERZEICHNIS]/MD/Joachim/TODO/Dokumentationen mit Joplin und Pandoc erstellen.md" 
  -o "[VERZEICHNIS]\Dokumente/Dokumentationen mit Joplin und Pandoc erstellen_P.pdf"

3.10 HTML

pandoc.exe --data-dir [VERZEICHNIS] -f markdown --toc -V toc-title:"Inhaltsverzeichnis" 
  --number-sections -V lang=de-DE -V geometry=a4paper -V geometry:margin=2cm --template GitHub.html5 
  --self-contained "[VERZEICHNIS]/MD/Joachim/TODO/Dokumentationen mit Joplin und Pandoc erstellen.md" 
  -o "[VERZEICHNIS]\Dokumente/Dokumentationen mit Joplin und Pandoc erstellen.html"

Mit dem Parameter --self-contained werden die Bilder in der HTML-Datei eingebettet - BASE64-Kodierung!

Es kann bei der Konvertierung zu Problemen kommen - Speicherschutzverletzungen! Wenn dem so ist, den Parameter entfernen. Es muss aber darauf geachtet werden das die Bilder sich im passenden Verzeichnis befinden. Am besten die HTML-Datei öffnen und gegebenfalls den Pfad anpassen.

Fehler_Konvertierung.png
Fehler_Konvertierung.png

3.11 HTML-Präsentation

ACHTUNG: Spezielle Seitengestaltung!

pandoc.exe --data-dir [VERZEICHNIS] -i --section-divs -V theme=white
  -V transition=convex -t revealjs -s "[VERZEICHNIS]/MD/Joachim/TODO/Dokumentationen mit Joplin und
  Pandoc erstellen.md" -o "[VERZEICHNIS]\Dokumente/Dokumentationen mit Joplin und Pandoc erstellen_P.html"

Für HTML-Präsentation müsst Ihr folgende Vorbereitungen treffen: reveal.js herunterladen und entpacken. Den entpackten Ordner in reveal.js umbenennen. Der Ordner reveal.js muss sich im gleichen Verzeichnis wie die Präsentation befinden.

3.12 TXT-Datei

pandoc.exe --data-dir [VERZEICHNIS] -f markdown -t plain --wrap=auto "[VERZEICHNIS]/MD/KVW/Informationen.md" -o "[VERZEICHNIS]\Dokumente/Informationen.txt"

3.13 Brief

Download Vorlage: Pandoc-letter-DIN5008

Anpassung Vorlage:

Damit ß - Zeichen sauber angezeigt bzw. gedruckt werden, muss \usepackage[T1]{fontsec} in \usepackage{fontspec} angepasst werden!

Die Markdown-Datei sieht wie folgt aus:

---
author: Joachim Nyenhuis
phone: +49 174 9449323
email: joachim(at)nyenhuis(dot)org
date: \today
lang: de-DE
place: Ohne
subject: Titel vom Brief
return-address:
 - Bentheimer Diek 18
 - 48465 Ohne
address:
Musterfirma GmbH
- Max Mustermann
- Musterstraße
- 12345 Musterstadt
opening: Sehr geehrte Damen und Herren,
closing: Mit freundlichen Grüßen
encludes: Anlage,
 Anlage,
 Anlage
...
Far far away,
 behind the word mountains,
 far from the countries
 Vokalia and Consonantia,
 there live the blind texts. Separated they live in Bookmarksgrove right at the coast of the Semantics,
 a large language ocean. A small river named Duden flows by their place and supplies it with the necessary regelialia.

Konvertierung mit folgendem Befehl:

pandoc.exe --data-dir [VERZEICHNIS] -s "[VERZEICHNIS]/MD/Joachim/Schriftverkehr/000_Briefvorlage .md" 
 -V geometry=a4paper -V geometry:margin=2cm --pdf-engine=xelatex
 --template letter.latex
 -o "[VERZEICHNIS]\Dokumente/Schriftverkehr/2019_04_08_000_Briefvorlage.pdf"

Ausgabe:

Briefvorlage
Briefvorlage
  1. Joplin
  2. Pandoc
  3. MiKTeX
  4. Template Eisvogel
  5. Template Pandoc-Letter-DIN5008
  6. Wissenschaftliche Texte schreiben – mit Markdown und Pandoc
  7. Markdown - Befehlsübersicht
  8. Pandoc - Dokumente konvertieren

5 Anlagen/Download

  1. Dokumentation als Markdown-Datei
  2. Als Word (docx) Datei
  3. Als PDF-Datei

Zurück