Markdown und Pandoc

markdown-pandoc

Umfang: 200 Seiten (PDF)
ISBN (PDF): 978-3-902643-33-9
Erschienen: Oktober 2018

Kostenloser Download (PDF)

Inhalt

Die Markdown-Syntax hilft dabei, formatierte Dokumente mit minimalem Overhead im Textmodus zu verfassen. Pandoc macht daraus HTML- und PDF-Dateien, E-Books, Vortragsfolien. Außerdem kann Pandoc Texte in vielen anderen Formaten importieren und exportieren, z.B. LaTeX, Word, OpenOffice/LibreOffice Writer oder Word.

Dieses E-Book gibt eine Einführung in die großartige Markdown-Welt und ihre vielfältigen Anwendungsmöglichkeiten. Nach einem kurzen Einführungskapitel werden die folgenden Themen im Detail behandelt:

  • Markdown-Tools (Installation, Markdown-Editoren)
  • Markdown-Syntax inklusive der Pandoc-spezifischen Erweiterungen
  • Pandoc-Optionen und -Anwendungskonzepte
  • HTML-Dokumente erstellen
  • E-Books (EPUB und Mobi)
  • LaTeX-Export und PDF-Erzeugung
  • Vortragsfolien (Slides)
  • Docker-Setup und andere fortgeschrittene Arbeitstechniken

Natürlich freue ich mich über jeden Leser, jede Leserin; wenn es Ihnen aber nur darum geht, für Ihr Content Management System (CMS) hin und wieder einen Blog-Beitrag in Markdown-Syntax zu verfassen, dann reicht es vermutlich aus, wenn Sie sich schnell die Markdown-Syntaxzusammenfassung in der Wikipedia durchlesen.

Die eigentliche Zielgruppe dieses E-Books sind fortgeschrittene Benutzer, die längere Texte (Diplomarbeiten, Bücher etc.) schreiben und publizieren möchten, die also z.B. PDFs und EPUBs erzeugen wollen. Bei aller Begeisterung für Markdown und Pandoc muss ich zugeben, dass die Realisierung eigener Layout-Wünsche jedoch mit viel Mühe und Handarbeit verbunden ist. Oftmals sind eigene Header-Dateien (LaTeX) oder gar Scripts erforderlich, die den von Pandoc generierten Code nachbearbeiten. Benutzer mit Programmier- und LaTeX-Erfahrung sind hier klar im Vorteil. Insofern eignet sich die Kombination aus Markdown und Pandoc gut für technical writing, wo dieser Hintergrund zumeist gegeben ist.

Beispieldateien, Errata

Beispieldateien

Errata zur 1. Auflage des Buchs

Zur 2. Auflage gibt es noch keine Errata.

Inhaltsverzeichnis

  • Einführung
  • Werkzeuge
    • Pandoc installieren
    • Markdown-Editoren
  • Die Markdown-Syntax
    • Absätze, Zeichensätze, Sonderzeichen
    • Dokumentstruktur und Überschriften
    • Textformatierung
    • Aufzählungen und Listen
    • Einrückungen und Zitat
    • Listings / Programmcode
    • Lins und Querverweise
    • Bilder und Tabellen
    • Fußnoten
    • HTML- und LaTeX-Code einbetten
  • Das pandoc-Kommando
    • Input- und Output-Formate
    • Pandoc-Erweiterungen
    • Optionen
    • Templates
    • Filter
  • HTML-Dokumente
    • Aufbau
    • CSS-Formatierung
  • E-Books (EPUB und Mobi)
    • Aufbau der Formate
    • Tools, EPUB-Validierung, kindlegen
    • Formatierung
  • LaTeX und PDF
    • LaTeX-spezifische Pandoc-Optionen
    • Template-Aufbau und -Variablen
    • Tipps und Tricks zur Formatierung
  • Folien
    • HTML-Folien (S5, Slidy, Slideous, DZSlides etc.)
    • PDF-Folien (Beamer inkl. Handouts)
  • Fortgeschrittene Arbeitstechniken
    • Atom und Pandoc
    • Der Satz dieses E-Books
    • Pandoc und Docker
    • Kollaborativ schreiben mit GitLab (Axel Dürkop und Tina Ladwig, TU Hamburg)

21 Gedanken zu „Markdown und Pandoc“

  1. Erst mal Danke für dieses schöne Buch.

    Was mir zur Zeit fehlt:

    Ich habe keinen Hinweis in dem Buch gefunden, wie ich deutsche Anführungszeichen korrekt setzen kann, so dass sie beim Export in ein ‚pdf‘ oder ‚html‘ File (mit ‚Uberwriter‘ unter Ubuntu 12.04.5 LTS) korrekt dargestellt werden.

    Auch eine — vielleicht zu oberflächliche Suche meinerseits — im Internet hat mir dazu keine Antwort geliefert.

    Haben Sie dazu vielleicht eine Lösung?

    Vielen Dank schon mal für eine Antwort.

  2. Danke für die Antwort. Entschuldigung, dass ich da noch einmal nach haken muss: Mir gelingt es auch nicht, in Markdown französische Anführungszeichen zu erzeugen, die dann in einem PDF-Dokument korrekt erscheinen. Ist es allgemein irgendwie möglich, Unicode-Zeichen als Code in ein Markdown-Script ein zu fügen, die dann im PDF oder html korrekt dargestellt werden? (Etwa die Unicode Zeichen: U+00AB et U+00BB, U+201C et U+201D, U+2018 et U+2019, U+0022, U+0027.

    1. Ich kann die Probleme nicht nachvollziehen. Folgender Markdown-Text:

      Lorem ipsum »dolor« sit "amet", consetetur 'sadipscing' elitr, sed „diam“
nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
voluptua.

      HTML und PDF-Version erzeugen:

      pandoc datei.md -o out.html
pandoc datei.md -o out.pdf

      HTML-Ergebnis sieht so aus:

      Lorem ipsum »dolor« sit "amet", consetetur ’sadipscing‘ elitr, sed „diam“ nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.

      Das PDF-Ergebnis (hier als Bild eingebettet):

  3. O.K. Danke. Von der Kommandozeile aus geht es soweit.
    Mit der Zeile

    pandoc -s -S -f markdown -t latex -o ausgabe.tex eingabe.md

    bekomme ich auch noch gleich einen LaTeX-Vorspann mitgeliefert.

    Nur von Uberwriter 12.07.9 aus klappt der direkte Export in ein PDF-Dokument nicht …

    Die Anführungszeichen bekomme ich unter Linux Ubuntu 12.4.5 LTS mit Tastenkombinationen wie
    AltGr + y = » , AltGr + v = „ , AltGr + b = “, AltGr + Shift + v = ‚ , AltGr + Shift + b = ‘

  4. Die Inkompatibilität betrifft nur ein Script, das eine von Pandoc erzeugtes LaTeX-Datei »nachbehandelt«. Das Problem besteht unverändert, und ich bin aktuell leider nicht in der Lage, mich darum zu kümmern. Sorry.

  5. Privat als auch beruflich nutze ich das Gespann Markdown/Pandoc gerne und freue mich auf die 2. Auflage. Was ist neu? Ich selbst nutze Debian/testing AMD64 und wünsche mir dass die entsprechenden Programm-Versionen unterstützt werden. Vielen Dank im voraus für die Beantwortung meiner Fragen.

    1. Das E-Book berücksichtigt Pandoc 2.3. Im Wesentlichen ist es eine Aktualisierung, neu ist ein Kapitel mit fortgeschrittenen Arbeitstechniken (Satz des E-Books, Docker, GitLab). Wer die 1. Auflage auf ebooks.kofler gekauft hat, bekommt auf Anfrage ein kostenloses Update.

  6. Guten Tag,
    ich benötige Pandoc um von Markdown/LaTeX in docx (in Stil eines speziellen reference-docs) zu konvertieren. Gibt es dazu Infos in dem Buch, oder geht es hauptsächlich um PDF-Export?

    1. Bedaure, docx kommt im Buch praktisch nicht vor. Ich habe Pandoc in der Vergangenheit für Umwandlungen docx -> Markdown verwendet, was mäßig gut funktioniert hat. In die umgekehrte Richtung habe ich gar keine Erfahrungen.

  7. Ein tolles Buch! Empfehlen Sie für das Ausgabeformat PDF eine eigene cover.pdf mit der von pandoc generierten PDF z.B. per pdftk zu verschweißen oder gibt es einen besseren Weg?

    1. Ich habe das Cover mit LaTeX-Code als Bild in die erste Seite eingebettet (mit dem wallpaper-Package).

  8. Manche meiner .eps-Grafiken im Fließtext der PDF sind nur halb so hoch wie Kleinbuchstaben. Andere hingegen skalieren mit height=13px wunderbar. Keine Ahnung warum.

    Um Grafiken im Fließtext verläßlich auf Zeilenhöhe zu skalieren, schwebt mir statt
    {height=13px} #40px oder 100% bringen bei mir gar nix:
    so etwas vor:
    {height=\LATEX-BEFEHL-DER-ZEILENHÖHE-IN-PX-AUSGIBT-PLUS-px-HINTEN-DRAN}

    Ist das eine gute Idee?
    Sonst könnte ich mir nur vorstellen, dass die Konvertierung ins EPS-Format irgendwelche Seiteneffekte hat:
    #!/bin/bash
    for filename in *.png; do
    epsname=${filename%.png}.eps
    echo „processing $filename $epsname“
    convert -quiet -flatten -background white $filename eps3:$epsname
    done

    Die problematische PNG-Grafik ist 22 x 24 Pixel gross.
    Eine 20×20 Pixel große skaliert hingegen problemlos.

    1. Mit fällt ad-hoc nichts ein. Ich habe allerdings auch noch nie Grafiken in den Fließtext eingebettet, bei mir sind die Grafiken immer abgesetzt.

  9. Die geringe Auflösung war schuld. Ich habe die 22×24 Pixel Grafik mit dem kostenlosen Grafikprogramm Gimp auf 220×240 Pixel skaliert. Nun greift die Skalierung per {height=13px} wunderbar.

  10. Das Stichwortverzeichnis meiner PDF wird beim Anklicken im Inhaltsverzeichnis nicht richtig angesprungen. Ich lande stattdessen auf der letzten Markdown-Überschrift vor dem Index. Mache ich einen Fehler?

    Mein Quellcode:
    <…>

    Letzte Markdown-Überschrift vor dem Index

    Blabla.


    \pagebreak

    \addcontentsline{toc}{section}{Index}
    \printindex

    1. Das Problem hatte ich auch schon. Ich kann leider nicht sagen, woran das liegt. Eigentlich habe ich den Verdacht, dass der Fehler bei LaTeX und nicht bei Pandoc liegt, aber ich bin dem nicht weiter nachgegangen.

  11. 2 Lösungsvorschläge um Index aus Inhaltsverzeichnis korrekt anzuspringen:

    KOMA-Script Klasse \documentclass[index=totoc]{scrbook} statt book

    • Vorteil: Für mich die schönste Lösung. Spring zur Indexseite wie gewünscht und nicht auf den ersten Index-Eintrag wie beim nachfolgenden Lösungsvorschlag. Mit einem einfachen Beispiel erfolgreich getestet.
    • Nachteil: Die Umstellung Ihres komplexen Beispielprojekts von book auf scrbook ist zumindest mir noch nicht gelungen. Übersetzung wirft noch Fehler

    Mit Paket tocbibind

    • Vorteil: book als Dokumentklasse bleibt. Funktoniert auf Anhieb mit Ihrem komplexen Beispielprojekt
    • Nachteil: Der Sprung aus dem Inhaltsverzeichnis erfolgt (anders als bei Kapiteln) zum ersten Index-Eintrag. Die Überschrift „Index“ ist dadurch verdeckt. Aber immerhin lande ich schon mal auf der Index-Seite und nicht davor.

    Beispiel-LaTeX-Quellcode:

    \documentclass{book}
...
\usepackage[nottoc]{tocbibind}
\usepackage[pdftex,hyperindex]{hyperref}
...
\clearpage
\phantomsection
\printindex

  12. Hallo,
    mir ist ein kleiner Fehler auf Seite 159 des PDFs (2. Auflage) aufgefallen. Dort wird in der ersten Zeile von „Pandex“ gesprochen, was inhaltlich auch tatsächlich Sinn machen würde…

  13. Ein kleiner Fehler ist mir beim Experimentieren mit Listen aufgefallen, druch dden man auf die Idee kommen könnte, dass auch das Komma in Markdown einem Listenpunkt vorangestellt werden kann.

    Im Abschnitt „3.6 Aufzählungen und Listen“ auf S. 44 der PDF-Ausgabe fehlen im folgenden Absatz nämlich zweimal die Sternchen *, die in Markdown als Listenpunkte verwendet werden. Diese Zeichen hätten im Quelltext quotiert werden müssen:

    „Simple Aufzählungen ohne Nummerierung erzeugen Sie, indem Sie den Einträgen die
    Zeichen , + oder – voranstellen. Die Zeichen sind gleichbedeutend, Sie können sie sogar
    innerhalb einer Aufzählung mischen (ein Punkt mit , der nächste mit +).“

    Man erkennt das Problem auch daran, dass im PDF-Dokument der Text „, + oder – voranstellen. Die Zeichen sind gleichbedeutend, Sie können sie sogar innerhalb einer Aufzählung mischen (ein Punkt mit“ kursiv dargestellt wird :-)

Kommentare sind geschlossen.