Konzept

Überblick

Wie an anderer Stelle ausgeführt, möchte ich Texte in Markdown schreiben und dann als HTML- und PDF-Dateien nutzen.
Die Konvertierung nach meinen Wünschen erledigt mein Pythonprogramm mdmachine. Es nutzt dabei Pandoc und den Chrome-Browser. Ggf. sind noch Java, Mermaid und MathJax beteiligt.
Github

flowchart
  subgraph mdmachine
    subgraph Zusatzfunktionen
        direction LR
        MHS@{ shape: docs, label: "Markdown, HTML, YAML" }
        MHS --> SB@{ shape: docs, label: "sidebar, sitemap
usw." }

    end
    subgraph PDF-Erzeugung
            direction LR
            H@{ shape: doc, label: "HTML" }
            P@{ shape: doc, label: "PDF" }
            GC@{ shape: lean-r, label: "Google
Chrome" }

            H --> GC--> P
            CSS@{ shape: hex} --> GC
            Pix@{ shape: hex} --> GC
            Font@{ shape: hex} --> GC
    end
    subgraph Basisworkflow
            direction LR
            M --> PP --> PD ==>|mehrere| HS

            M@{ shape: doc, label: "Markdown
(single source
of truth)" }
            HS@{ shape: docs, label: "HTML" }
            PP@{ shape: lean-r, label: "Prä-
prozessor" }
            PD@{ shape: lean-r, label: "Pandoc" }
            
    end
  end
  style mdmachine fill: lightblue

Single Source of Truth

Im Gegensatz zu den Einstellungen in Office-Programmen, sollen hier alle Inhalte und Vorgaben in textueller Form vorliegen. So sind sie eindeutig und nachvollziehbar sowie versionierbar. Nach Möglichkeit sollen dabei keine Redundanzen vorkommen.

Diese Anforderung erfüllen Markdowndateien, die einen führenden YAML-Block erhalten, kombiniert mit reinen YAML-Dateien für allgemeine Einstellungen.

Die Konfigurationen jenseits der Inhalte finden an vier Stellen statt, die thematisch zugeordnet sind:

• Für einen Konvertiervorgang: an der Kommandozeile mit den Parametern beim Aufruf von mdmachine.
• Für eine Markdowndatei: in ihrem YAML-Block.
• Für ein Verzeichnis: in der in diesem Verzeichnis liegenden mdm_dir.yaml.
• Für einen Verzeichnisbaum: in der im obersten Verzeichnis liegenden mdm_root.yaml. Die Datei legt dabei fest, welches das “oberste Verzeichnis” (root) ist.

Die Formatierungen werden gewählt durch die Auszeichnungen in den Markdowndateien:

• Markdown-Standardformatierungen (fett, kursiv, Überschriften, Aufzählungen, Bilder, Quelltext).
• Pandoc-Erweiterungen von Markdown (Tabellen, Definitionen, Spalten).
• Definition von DIVs mit Pandocs “fenced div” und diese ggf. mehreren CSS-Klassen zuordnen. Details siehe CSS-Klassen.
• Definition von SPANs mit “[…]” und Zuordnung zu Klassen.

Die Formatierungen werden definiert in den eingebundenen CSS-Dateien.

Anmerkung: Man kann in Markdowndateien weitere Formatierungen vornehmen, in dem man style-Tags (im Text) oder style-Strings (bei Objekten) hinzufügt sowie pures HTML (z.B. “<br>”) ergänzt. Das sollte einzelnen Ausnahmen vorbehalten sein, da man immer universelle Lösungen anstreben sollte.

Christian Bienmüller