Autoren-Leitfaden

Dieses Dokument beschreibt die erweiterten Funktionen der SIEVERS Dokumentationsplattform, die über das Standard-DocFx hinausgehen.

---

DataTables — Interaktive Tabellen

Große Tabellen können mit Suche, Sortierung, Paginierung und CSV/XLSX-Export ausgestattet werden.

Aktivierung

Umschließen Sie die Markdown-Tabelle mit einem <div class="datatable">:

<div class="datatable">

| Spalte A | Spalte B | Spalte C |
|----------|----------|----------|
| Wert 1   | Wert 2   | Wert 3   |
| ...      | ...      | ...      |

</div>

Wichtig

Die Leerzeilen zwischen <div> und der Tabelle sind Pflicht — ohne sie erkennt DocFx die Markdown-Tabelle nicht.

Funktionen

Funktion	Beschreibung
Suche	Freitext-Suchfeld filtert alle Spalten in Echtzeit
Sortierung	Klick auf Spaltenüberschrift sortiert (natürliche Sortierung: BT-1, BT-2, ..., BT-10)
Paginierung	Standardmäßig 10 Zeilen pro Seite mit Navigation
CSV-Export	Button „CSV" exportiert die aktuelle (gefilterte) Ansicht
XLSX-Export	Button „XLSX" exportiert als Excel-Datei
Klick-zum-Aufklappen	Klick auf eine Zeile zeigt den vollständigen Text abgeschnittener Zellen

Wann verwenden?

• Tabellen mit mehr als 15 Zeilen
• Tabellen mit breiten Spalten, die horizontal scrollen
• Referenztabellen, in denen Kunden nach bestimmten Werten suchen

Für kleine Tabellen (unter 10 Zeilen) ist die normale Markdown-Tabelle ausreichend.

---

Änderungshervorhebung (Change Highlighting)

Zeigt Kunden, welche Abschnitte seit der letzten Version geändert wurden. Erzeugt automatisch ein Änderungsprotokoll am Seitenanfang.

So funktioniert es

1. Pro Produkt wird in docfx.json eine aktuelle Versionsnummer hinterlegt
2. In den Markdown-Dateien werden geänderte Abschnitte mit einem <div> oder <span> markiert
3. Beim Seitenaufruf vergleicht ein Script die markierte Version mit der Produkt-Version:
   • Version der Markierung ≥ Produkt-Version → Abschnitt wird hervorgehoben + im Änderungsprotokoll verlinkt
   • Version der Markierung < Produkt-Version → Markierung wird transparent (normaler Text)

Konfiguration in docfx.json

Im Abschnitt fileMetadata werden zwei Einträge pro Produkt benötigt:

"fileMetadata": {
  "highlight_changes": {
    "sievers-e-rechnung/**": true,
    "sievers-datev/**": true
  },
  "show_changes_since": {
    "sievers-e-rechnung/**": "0.178",
    "sievers-datev/**": "1.150"
  }
}

• highlight_changes: Aktiviert das Feature für alle Dateien des Produkts
• show_changes_since: Die aktuelle (veröffentlichte) Version — alles ab dieser Version wird hervorgehoben

Einen Abschnitt als geändert markieren

Ganzer Abschnitt (Block)

<div class="changed" data-version="0.179">

## Neuer Export-Abschnitt

Dieser gesamte Abschnitt wurde in Version 0.179 hinzugefügt.

| Spalte A | Spalte B |
|----------|----------|
| ...      | ...      |

</div>

Einzelner Satz (Inline)

Normaler Text und <span class="changed" data-version="0.179">dieser Satz wurde geändert</span> in Version 0.179.

Nur eine Überschrift markieren

<div class="changed" data-version="0.179">

## Geänderte Überschrift

</div>

Der restliche Inhalt bleibt ohne Hervorhebung.

Hinweis

Die Leerzeilen innerhalb des <div> sind wichtig, damit DocFx den Markdown-Inhalt korrekt rendert.

Neue Version veröffentlichen

Wenn Version 0.179 veröffentlicht wird:

1. Öffnen Sie docfx.json
2. Ändern Sie "sievers-e-rechnung/**": "0.178" → "sievers-e-rechnung/**": "0.179"
3. Alle Markierungen mit 0.178 und darunter verschwinden
4. Nur Markierungen ab 0.180 (nächste Version) werden künftig hervorgehoben

Die alten <div class="changed"> Markierungen können im Markdown stehen bleiben — sie werden einfach nicht mehr angezeigt, sobald die Version überholt ist.

Was der Kunde sieht

Wenn es Änderungen auf einer Seite gibt, erscheint am Anfang des Artikels ein rotes Änderungsprotokoll:

Änderungsprotokoll

In den folgenden Abschnitten gibt es wichtige Änderungen:

• Export CII ZUGFeRD
• Import

Die verlinkten Abschnitte sind zusätzlich am linken Rand rot hervorgehoben.

Best Practices

Tipp	Beschreibung
Nur wichtige Änderungen markieren	Tippfehler-Korrekturen oder Formatierungsanpassungen nicht markieren
Version erhöhen, nicht ersetzen	Alte Markierungen stehen lassen, neue mit höherer Version hinzufügen
Blöcke bevorzugen	<div> ist besser lesbar als <span> für größere Änderungen
Kombination mit DataTables	DataTables-Wrapper und Changed-Wrapper können verschachtelt werden

Verschachtelung mit DataTables

<div class="changed" data-version="0.179">

## Neue Tabelle

</div>

<div class="datatable">

| Spalte A | Spalte B |
|----------|----------|
| ...      | ...      |

</div>

Tipp

Die changed-Markierung um die Überschrift, das datatable-Wrapper um die Tabelle. Nicht verschachteln, sondern nebeneinander setzen.

---

Änderungsprotokoll auf der Produktstartseite

Neben dem seiteninternen Änderungsprotokoll (das automatisch per JavaScript auf jeder Seite erscheint) gibt es ein aggregiertes Änderungsprotokoll auf der Startseite jedes Produkts. Dieses wird durch das Script generate-changelogs.ps1 erzeugt.

Funktionsweise

Das Script:

1. Liest docfx.json aus und ermittelt alle Produkte mit highlight_changes: true
2. Durchsucht alle .md-Dateien des Produkts nach <div class="changed" data-version="X"> Markierungen
3. Vergleicht die markierte Version mit show_changes_since
4. Erzeugt auf der index.md des Produkts eine Zusammenfassung aller geänderten Seiten und Abschnitte

Ergebnis auf der Startseite

Auf der Produktstartseite erscheint ein Hinweiskasten wie:

Hinweis

Aenderungen seit Version 0.178:

BC-Felder - BT-Felder Mapping (docs/de/bc-felder-bt-felder-mapping.html)

• Export CII ZUGFeRD

Die Links führen direkt zu den geänderten Seiten.

Markierungen in der index.md

Das Script fügt automatisch die Markierungen <!-- changelog-start --> und <!-- changelog-end --> in die index.md ein. Bei jedem erneuten Lauf wird nur der Inhalt dazwischen aktualisiert. Die Markierungen dürfen nicht manuell entfernt werden.

Build-Workflow

Vor jedem Build muss das Changelog-Script ausgeführt werden:

# 1. Changelogs auf Startseiten generieren
.\generate-changelogs.ps1

# 2. DocFx bauen
docfx build

Wichtig

Das Script muss vor docfx build laufen, da es die index.md-Dateien verändert, die dann von DocFx verarbeitet werden.

---

Produktdokumentation automatisch per Pipeline aktualisieren

Jedes Produktrepo pflegt seine Dokumentation direkt als DocFx-Dateien in einem doc/docfx/-Ordner. Eine Azure DevOps Pipeline checkt alle Produktrepos aus, kopiert die fertigen DocFx-Inhalte und baut die Plattform.

Konzept

Produktrepos (Azure DevOps)           DocFxDokumentation Pipeline
───────────────────────────           ────────────────────────────
PD-ERP/Candis                         1. Alle Produktrepos auschecken
  doc/docfx/de/             ──────►   2. doc/docfx/ nach sievers-*/docs/ kopieren
    toc.yml                            3. generate-changelogs.ps1
    seite-a.md                         4. docfx build
    images/                            5. Site deployen
                              
PD-DATEV/DATEV
  doc/docfx/de/             ──────►
  doc/docfx/en/

Autoren arbeiten dauerhaft in doc/docfx/ des jeweiligen Produktrepos. Es findet keine automatische Konvertierung statt — die Markdown-Dateien sind bereits im DocFx-Format.

Hinweis

Die Produkt-Scaffolding-Dateien (sievers-{produkt}/toc.yml und sievers-{produkt}/index.md) verbleiben in DocFxDokumentation und werden von der Pipeline nicht überschrieben.

---

Ordnerstruktur im Produktrepo

Jedes Produktrepo enthält einen doc/docfx/-Ordner mit der folgenden Struktur:

doc/
  docfx/
    de/
      toc.yml          ← Inhaltsverzeichnis für diese Sprache
      einleitung.md
      installation.md
      images/
        screenshot.png
    en/                ← optional, nur wenn EN-Doku vorhanden
      toc.yml
      introduction.md

Der de/- bzw. en/-Ordner wird direkt nach sievers-{produkt}/docs/de/ bzw. sievers-{produkt}/docs/en/ kopiert.

---

Pipeline-YAML

Die Pipeline wird im DocFxDokumentation-Repository als build.yml abgelegt und referenziert alle Produktrepos per resources.

# build.yml — in DocFxDokumentation repo
trigger:
  branches:
    include:
      - master

resources:
  repositories:
    - repository: Candis
      type: git
      name: PD-ERP/Candis
      ref: refs/heads/master
    - repository: DATEV
      type: git
      name: PD-DATEV/DATEV
      ref: refs/heads/master
    # weitere Produktrepos hier ergänzen

pool:
  name: PD Pool

steps:
  - checkout: self
    path: DocFxDokumentation

  - checkout: Candis
    path: Candis

  - checkout: DATEV
    path: DATEV

  - powershell: |
      # Candis (nur DE)
      $src  = "$(Agent.BuildDirectory)/Candis/doc/docfx"
      $dest = "$(Agent.BuildDirectory)/DocFxDokumentation/sievers-candis/docs"
      Remove-Item $dest -Recurse -Force -ErrorAction SilentlyContinue
      Copy-Item $src -Destination $dest -Recurse

      # DATEV (DE + EN)
      $src  = "$(Agent.BuildDirectory)/DATEV/doc/docfx"
      $dest = "$(Agent.BuildDirectory)/DocFxDokumentation/sievers-datev/docs"
      Remove-Item $dest -Recurse -Force -ErrorAction SilentlyContinue
      Copy-Item $src -Destination $dest -Recurse
    displayName: 'Copy DocFx content from product repos'

  - powershell: |
      cd "$(Agent.BuildDirectory)/DocFxDokumentation"
      .\generate-changelogs.ps1
      docfx build
    displayName: 'Generate changelogs and build DocFx'

  - task: PublishBuildArtifacts@1
    inputs:
      PathtoPublish: '$(Agent.BuildDirectory)/DocFxDokumentation/_site'
      ArtifactName: 'docfx-site'
    displayName: 'Publish built site'

---

Produktrepo-seitige Pipeline (optional)

Um den DocFx-Build automatisch auszulösen, wenn sich Dokumentation in einem Produktrepo ändert, kann dort ein Pipeline-Trigger ergänzt werden:

# In Candis/doc/doc.yml — Trigger für DocFxDokumentation
- task: TriggerBuild@3
  displayName: 'Trigger DocFxDokumentation build'
  inputs:
    definitionIsInCurrentTeamProject: false
    teamProject: 'PD-Tools'
    buildDefinition: 'DocFxDokumentation'
    queueBuildForUserThatTriggeredBuild: false
    useSameBranch: false
    branchToUse: 'master'
  condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/master'))

Hinweis

Hierfür wird die Azure DevOps Marketplace-Extension TriggerBuild benötigt, oder alternativ ein REST-API-Aufruf mit einem Service-Connection-Token.

---

Neues Produkt einbinden

1. Produktrepo — doc/docfx/de/ (und ggf. doc/docfx/en/) mit toc.yml und Markdown-Dateien anlegen
2. build.yml — Neues Repository unter resources.repositories ergänzen, checkout-Schritt und Copy-Item-Block hinzufügen
3. DocFxDokumentation — sievers-{produkt}/toc.yml und sievers-{produkt}/index.md anlegen (einmalig)
4. Root toc.yml — Produkteintrag ergänzen

---

Erstmalige Migration eines bestehenden Produkts

Für Produkte, die noch eine monolithische documentation_de.md verwenden, kann Convert-MDToDocFx.ps1 zur einmaligen Migration genutzt werden:

# Einmalig: monolithische Doku in DocFx-Seiten aufteilen
& "C:\Repos\SNC-Tools\Markdown\Convert-MDToDocFx.ps1" `
    -SourceFile "C:\Repos\Candis\doc\documentation_de.md" `
    -ImageFolder "C:\Repos\Candis\doc\images-de" `
    -OutputPath  "C:\Repos\Candis\doc\docfx\de"

Das Ergebnis (de/toc.yml + einzelne .md-Dateien + images/) wird dann in doc/docfx/de/ committed. Danach wird die monolithische documentation_de.md nicht mehr benötigt.

---

Manueller Lauf (lokale Entwicklung)

Ohne Pipeline kann der Inhalt manuell kopiert und die Site lokal gebaut werden:

# Beispiel: Candis lokal einspielen
$src  = "C:\Repos\Candis\doc\docfx"
$dest = "C:\Repos\DocFxDokumentation\sievers-candis\docs"
Remove-Item $dest -Recurse -Force -ErrorAction SilentlyContinue
Copy-Item $src -Destination $dest -Recurse

cd C:\Repos\DocFxDokumentation
.\generate-changelogs.ps1
docfx build
docfx serve _site --port 8088

Tipp

Für alle Produkte auf einmal kann import-all-docs.ps1 angepasst werden, sodass es statt Add-DocFxDocumentation einfach den jeweiligen doc/docfx/-Ordner kopiert.