Skip to content

Instantly share code, notes, and snippets.

@TorstenC

TorstenC/Pandoc-vs-AsciiDoc.md

Created May 19, 2025 01:56
Show Gist options
  • Save TorstenC/0a9c2e640ea2d5a2a4d86ec49b0e34a5 to your computer and use it in GitHub Desktop.
Save TorstenC/0a9c2e640ea2d5a2a4d86ec49b0e34a5 to your computer and use it in GitHub Desktop.
Download ZIP
🛟 Pandoc vs. AsciiDoc
Raw
Pandoc-vs-AsciiDoc.md

Welches Format ist das beste Ausgangsformat

Was ist das "beste" Ausgangsformat?

Pandoc unterstützt eine Vielzahl von Ausgabeformaten (“output formats”), darunter Dokumentformate, Präsentationsformate, HTML-Varianten, E-Book-Formate und viele mehr. Hier eine Übersicht der wichtigsten Formate:

Wichtige Pandoc-Ausgabeformate:

  • Markdown (verschiedene Varianten, z.B. pandoc, GitHub, CommonMark)
  • HTML (HTML5, HTML4)
  • LaTeX / PDF (über LaTeX)
  • Docx (Microsoft Word)
  • ODT (OpenDocument Text, z.B. LibreOffice)
  • EPUB (E-Books)
  • reStructuredText
  • RST
  • AsciiDoc
  • Rich Text Format (RTF)
  • Textile
  • MediaWiki
  • Org-mode (Emacs)
  • TeX (Plain TeX)
  • JATS (für wissenschaftliche Publikationen)
  • Man Page (groff man)
  • u.v.m. (Pandoc-Dokumentation: Output formats)

Was ist das "beste" Ausgangsformat?

Die beste Wahl als Ausgangsformat, um Informationsverluste zu vermeiden, ist das Pandoc-Markdown mit Pandoc-spezifischen Erweiterungen (markdown+...).

Begründung:

  • Pandoc-Markdown ist das interne Arbeitsformat von Pandoc. Es unterstützt die meisten Features (Formatierungen, Hyperlinks, Fußnoten, Tabellen, mathematische Formeln, Code-Block-Attribute, Metadaten, u.v.m.).
  • Andere Formate (z.B. docx, odt, HTML) unterstützen möglicherweise nicht alle Pandoc-Features und können bei Konvertierung Details verlieren.
  • Pandoc-Markdown mit aktivierten Extensions (markdown+all_extensions) ist die verlustärmste Variante, z.B.: 
    pandoc -t markdown+all_extensions
  • "Rundes Tripeln" (Konvertieren in verschiedene Formate und wieder zurück) funktioniert mit Markdown meist am besten.

Ausnahme:

  • Wenn das Ziel spezielle Layouts, Makros oder Formatierungen eines bestimmten Zielsystems erfordert (z.B. komplexes LaTeX, Docx-Styles), kann das native Format dieses Systems besser geeignet sein – allerdings nur für genau dieses Ziel.

Zusammenfassung

  • Pandoc-Markdown mit allen Extensions ist meist das beste Ausgangsformat, um Informationen zu erhalten.
  • Bei jedem Formatwechsel (besonders zwischen sehr unterschiedlichen Formaten) kann es trotzdem zu kleinen Verlusten kommen. Für maximale Kompatibilität immer im Pandoc-Markdown bleiben, solange möglich.

Tipp:
Wenn du Originaldokumente dauerhaft verlustfrei archivieren willst, speichere sie als Pandoc-Markdown (.md) mit allen Extensions und Metadaten. Von dort kannst du in alle anderen Formate exportieren.

Referenz:

Was ginge vielleicht verloren?

Die Formate reStructuredText (reST) und AsciiDoc sind beide mächtig und weit verbreitet, bieten aber jeweils andere Features und Schwerpunkte als Pandocs Markdown mit allen Extensions.

Was könnte beim Export nach reStructuredText oder AsciiDoc verloren gehen?

Allgemein zu beachten

Pandoc erweitert Markdown um viele Features, die in den „Standard“-Formaten von reST und AsciiDoc nicht immer ein direktes Äquivalent haben. Beim Konvertieren kann es daher zu Informationsverlust kommen, insbesondere bei:

  • Spezialformatierungen
  • Erweiterten Metadaten
  • Pandoc-spezifischen Features

Typische Beispiele für möglichen Verlust:

Feature Pandoc Markdown reStructuredText AsciiDoc Hinweis
Fußnoten Ja Ja Ja Übertragung meist möglich
Tabellen Ja (erweitert, viele Typen) Ja (Standard-Tabelle) Ja (versch. Stile) Komplexe Tabellen evtl. eingeschränkt
Mathematische Formeln (LaTeX Math) Ja Eingeschränkt Eingeschränkt reST/AsciiDoc oft nur mit Erweiterungen
Syntax-Highlighting für Code Ja Möglich Möglich Stil und Features können abweichen
Direktives, Filter, Attributes ({}) Ja (div. Extensions) Ja (Admonitions, Roles) Ja (Block-Attribute) Oft nicht 1:1 übertragbar
Metadaten-Header (YAML, TOML) Ja Nein (nur mit Sphinx, usw.) Nein (teils Workarounds) Meist verloren
Pandoc-spezifische Link- und Bild-Optionen Ja Nein Nein Gehen meist verloren
HTML- oder LaTeX-Umbrüche/Raw-Blocks Ja (raw_attribute) Ja (raw, aber anders) Ja (raw, aber anders) Syntax nicht 1:1, kann verloren gehen
Markierungen (z.B. ==Highlight==) Ja (mit Extension) Nein Nein Geht verloren, da kein Pendant
Unterstreichungen, Farben, Custom Styles Ja (mit Extension) Nein Nein Geht verloren
Definition Lists, Task Lists Ja (mit Extension) Ja (Definition List) Ja (beides) Task Lists oft nicht in reST

Speziell:

  • Pandoc Markdown kann beliebige YAML/TOML-Metadaten enthalten – das gibt es in reST/AsciiDoc nicht.
  • Markierungen (Highlight/Marked Text) kennt nur Pandoc Markdown (und evtl. HTML).
  • Task Lists (- [x]) gibt es in AsciiDoc, aber nicht in reST.
  • Custom Attributes an vielen Elementen (z.B. {.classname #id}) gehen meist verloren.

Fazit

  • Pandoc-Markdown mit Extensions ist am ausdrucksstärksten und verlustärmsten.
  • reStructuredText und AsciiDoc sind sehr leistungsfähig, aber jeweils unterschiedlich. Manche Pandoc-Features (z.B. Metadaten, Markierungen, manche Tabellenarten, spezielle Extensions) können beim Export verloren gehen oder müssen als „raw“ übernommen werden.
  • Für maximale Zukunftssicherheit und Feature-Kompatibilität empfiehlt sich Pandoc-Markdown als Arbeitsformat.

Tipp:
Wenn du einen „verlustfreien“ Workflow willst, behalte die Originalquelle immer als Pandoc-Markdown und exportiere bei Bedarf in reST, AsciiDoc, HTML, PDF etc.

Referenzen:

Welche VS Code Extension(s) sollte ich installieren?

Für markdown+all_extensions (also Pandoc Markdown mit allen Extensions) gibt es keine einzige VS Code Extension, die wirklich alles nahtlos unterstützt. Aber du kannst eine sehr gute Umgebung mit einer Kombination aus Extensions erreichen:

1. Syntax Highlighting & Grundlegende Features

  • Markdown All in One
    • Sehr gute Unterstützung für Standard-Markdown, Tabellen, TOC, Tastenkürzel, Formatierungen.
  • Markdown Extended
    • Bietet zusätzliche Syntax und arbeitet gut mit erweiterten Markdown-Features.
  • Better Markdown
    • Unterstützt zusätzliche Syntax-Elemente.

2. Autocompletion

3. Preview (Vorschau)

  • VS Code eingebaut
    • Mit Ctrl+Shift+V oder Klick auf „Vorschau öffnen“ kannst du Markdown standardmäßig als Vorschau sehen.
  • Markdown Preview Enhanced
    • Sehr empfehlenswert! Unterstützt Diagramme, mathematische Formeln (LaTeX), Fußnoten, Custom-Container, YAML-Header, Code-Block-Attribute u.v.m. — also viele Pandoc-Extensions!
    • Vorschau kann so konfiguriert werden, dass sie Pandoc verwendet (für maximale Kompatibilität).

4. Pandoc Integration

  • vscode-pandoc
    • Ermöglicht direktes Konvertieren/Exportieren mit Pandoc aus VS Code heraus.

Empfohlene Kombi für Pandoc Markdown:

  1. Markdown All in One
  2. Markdown Preview Enhanced
  3. vscode-pandoc (optional, für Export)

Damit hast du:

  • Syntax-Highlighting für fast alles, was Pandoc kann
  • Vorschau mit Unterstützung für LaTeX, Diagramme, Fußnoten, Custom-Container usw.
  • Autocompletion für Links, Bilder, Referenzen etc.
  • (Optional) Direkten Export in andere Formate

Hinweis

  • Nicht alle Pandoc-Extensions werden in der Vorschau perfekt unterstützt (z.B. spezielle YAML-Header, seltene Attribute, eigene Templates). Für die finale Ausgabe solltest du immer nochmal mit Pandoc selbst rendern.
  • Die Extensions können individuell konfiguriert werden, z.B. YAML-Header, KaTeX/MathJax für Formeln, Diagramm-Unterstützung usw.

Zusammenfassung (Kurzantwort)

Empfohlen für Pandoc Markdown mit allen Extensions:

Damit bist du für Autocompletion, Syntax Highlighting und Preview im Pandoc-Style sehr gut ausgestattet!

Tipp:
Teste in der „Markdown Preview Enhanced“ die Option, Pandoc als Renderer zu verwenden ("markdown-preview-enhanced.usePandocParser": true in den VS Code Einstellungen).

Worauf müsste ich bei Pandoc Markdown gegenüber AsciiDoc verzichten?

Gute und wichtige Frage!

1. Variablen ({...})

  • AsciiDoc:
    Unterstützt Variablen und Platzhalter, z.B. :name: Wert und dann {name} im Text.
  • Pandoc Markdown:
    Unterstützt keine Variablen/Platzhalter in dieser Form.
    Pandoc-Markdown kennt keine eigene Syntax für Variablen wie {name}.
    Es gibt jedoch begrenzte Möglichkeiten, Variablen aus YAML-Metadaten im Template (beim Export, also nicht im Markdown selbst) zu verwenden. Im Fließtext selbst geht das nicht.

2. ifdef/ifndef (Konditionale Inhalte)

  • AsciiDoc:
    Unterstützt ifdef::name[] ... endif::[] direkt im Text, um Inhalte abhängig von einer Variablen ein-/auszublenden.
  • Pandoc Markdown:
    Hat keine native Unterstützung für konditionale Blöcke im Text.
    Mit Pandoc lassen sich beim Export mit Templates und Filtern Inhalte ggf. steuern, aber nicht direkt im Markdown-Dokument.

3. include:: (inkludieren anderer Dateien)

  • AsciiDoc:
    Unterstützt direkt das Einbinden von anderen Dateien.
  • Pandoc Markdown:
    Unterstützt kein natives include:: in der Markdown-Syntax.
    Lösungen:
    • Vorverarbeitung/Skripte (z.B. mit cat, make, Pandoc-Filter, Pandoc-Preprocessor)
    • Pandoc-Filter wie pandoc-include
    • Manuelles Einfügen

Fazit:

Ja, auf diese Features müsstest du in Pandoc-Markdown verzichten, zumindest in der Form, wie AsciiDoc sie bietet.

  • Variablen, Includes und Konditionen sind in Markdown (+ Pandoc) nicht nativ möglich.
  • Workarounds: YAML-Metadaten, Pandoc-Filter, externe Tools oder Vorverarbeitung mit Skripten.

Für komplexe technische Dokumentation mit Variablen, Includes und Konditionen ist AsciiDoc weiterhin deutlich komfortabler und mächtiger als Markdown/Pandoc.

Tabelle: Feature-Vergleich

Feature AsciiDoc Pandoc Markdown Workaround möglich?
Variablen ({name}) Ja Nein Nur im Output-Template
ifdef/ifndef Ja Nein Mit Filtern, aber umständlich
include:: Ja Nein Mit Filtern/Vorverarbeitung

Weiterführend:

Quelle: https://github.com/copilot/c/f659ef81-b3d0-4812-998f-0c246f647013

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment