Markdown-Dokumentation

Arbeitsblätter (Sheets), Transformationen (Actions), Projekte und Artefakte können eine Dokumentation in Markdown tragen. Die GUI zeigt das gerenderte Ergebnis und öffnet zum Bearbeiten einen geteilten Dialog: Markdown-Quelle auf der einen Seite und eine Live-Vorschau auf der anderen.

Wo Dokumentation verwendet wird

  • Arbeitsblätter (Sheets): Bei sichtbarem Explorer erscheint die Dokumentation des Arbeitsblatts darunter. Siehe Die Transformationen.
  • Transformationen (Actions): Im Dialog Edit Action nimmt der Bereich Documentation die Beschreibung der Transformation auf.
  • Projekte: Die Projektbeschreibung verwendet denselben Markdown-Betrachter und -Editor.
  • Artefakte: Die Artefaktbeschreibung verwendet denselben Markdown-Betrachter und -Editor.
  • Deployment-Hinweise: Ein Projekt kann zusätzlich einen Deployment-Hinweis in Markdown speichern.

Der Dokumentationstext liegt an der jeweiligen Entität. Beim Deployment eines Sheets, Projekts oder Artefakts wird die Dokumentation mit übertragen.

Anzeigen und Bearbeiten

Der Dokumentationsbereich zeigt das gerenderte Markdown unterhalb des Explorers. Die Schaltfläche in der Documentation-Titelzeile (Show oder Edit) öffnet einen größeren Dialog.

Arbeitsblatt mit Dokumentationsbereich und Dialog Edit Sheet Documentation

Der Dialog hat zwei Bereiche:

  • die Markdown-Quelle (Editor mit Syntaxhervorhebung)
  • eine Live-Vorschau, die sich während der Eingabe aktualisiert

Geteilter Editor: Markdown-Quelle links, Live-Vorschau rechts

Das ist keine Textverarbeitung mit verstecktem Markup. Bearbeitet wird die Markdown-Quelle; daneben erscheint das gerenderte Ergebnis. Die Werkzeugleiste bietet Bearbeiten, Speichern und add image.

Save schreibt den Text in die Entität. Cancel verwirft den Dialogpuffer und lässt die gespeicherte Dokumentation unverändert. Das Sheet, Projekt oder Artefakt muss im Bearbeitungsmodus sein, bevor die Dokumentation gespeichert werden kann.

Im Nur-Lesen-Modus wird nur die gerenderte Vorschau gezeigt.

Formatierung

Die GUI liest CommonMark-Markdown und ergänzt Tabellen im GitHub-Stil, Durchstreichung und automatische Links.

Typische Auszeichnung:

Auszeichnung Ergebnis
# … ###### Überschriften
**fett** oder __fett__ Fett
*kursiv* oder _kursiv_ Kursiv
~~Text~~ Durchgestrichen
- oder * Aufzählung
1. 2. Nummerierte Liste
`Code` Code im Fließtext
> Zitat
--- Trennlinie

Tabellen bestehen aus Kopfzeile, Trennzeile und Datenzeilen:

| Spalte A | Spalte B |
| :------- | :------- |
| Wert     | Wert     |

Verschachtelte Listen funktionieren wie in CommonMark: die untergeordneten Einträge werden unter dem Elterneintrag eingerückt.

Aufgabenlisten, Fußnoten und weitere Erweiterungen außerhalb von CommonMark plus den oben genannten Ergänzungen werden nicht als besondere Elemente dargestellt.

Links

Ein beschrifteter Link hat die Form [Beschriftung](https://example.com). Auch nackte http://- und https://-URLs im Text werden zu Links (Autolink).

Ein Klick auf einen http://- oder https://-Link öffnet den Systembrowser. Andere URL-Schemata werden nicht geöffnet.

Bilder

In der Werkzeugleiste des Editors gibt es die Schaltfläche add image. Sie fügt die gewählte Datei als eingebettetes Bild in den Dokumentationstext ein (gespeichert im Markdown, nicht als eigene Datei). Eingebettete Bilder erscheinen in voller Breite und zentriert.

Weil die Bilddaten im Dokumentationstext liegen, wird das Bild zusammen mit Sheet, Action, Projekt oder Artefakt gespeichert und deployed. Große Bilder vergrößern diesen Text.

Zusätzlich kann ein gewöhnliches Markdown-Bild ![Beschriftung](https://example.com/picture.png) oder ein HTML-img-Tag verwendet werden, wenn das Bild über eine URL erreichbar ist.

Codeblöcke

Abgegrenzte Codeblöcke verwenden drei Backticks oder drei Tilden. Ein Sprachkennzeichen schaltet die Syntaxhervorhebung ein:

```sql
SELECT id, name
  FROM customer
 WHERE active = 1;
```

Dieselbe Umrandung funktioniert mit ~~~sql … ~~~.

Hervorhebung gibt es für SQL und PL/SQL, Bash und Shell-Sessions, Java, JavaScript, Python, PowerShell, Docker, C, C++, C#, Go, Ruby, R, CSS, HTML/XML (Markup), AsciiDoc und ASP.NET. Ein Block ohne Sprachkennzeichen erscheint als vorformatierter Text.

Mermaid-Diagramme

Ein abgegrenzter Block mit der Sprache mermaid wird als Diagramm gezeichnet:

```mermaid
graph TD
    Extract --> Transform --> Load
```

Unterstützte Diagrammtypen sind unter anderem graph / flowchart, sequenceDiagram, classDiagram, stateDiagram / stateDiagram-v2, erDiagram, journey, gantt, pie, gitGraph und requirementDiagram.

Fehlt in der ersten Anweisung der Diagrammtyp, behandelt die GUI den Block als Flussdiagramm von oben nach unten (graph TD). Eine erste Zeile ohne Graph-Syntax wird zur Diagrammüberschrift, zum Beispiel:

```mermaid
Nächtlicher Ladevorgang
    Staging --> Core --> Mart
```

Suche

Wenn Sie in einem Arbeitsblatt suchen, werden Treffer in der Dokumentation in der gerenderten Vorschau hervorgehoben.

Erscheinungsbild

Die gerenderte Dokumentation verwendet das eingebaute Stylesheet der GUI. Eine Umgebung kann dieses Aussehen mit dem Konfigurationseintrag GUI / DOCU-VIEW / STYLESHEET (CSS) überschreiben. Ist der Wert leer, gilt das Standard-Stylesheet.