Wer einen Pull Request prüft, sollte das Dokument lesen, das er ändert, und kein Diff aus Sternchen. Diese Action veröffentlicht jede geänderte Markdown-Datei als gerenderte Seite und kommentiert die Links im Pull Request.
Zur Einrichtung in der Dokumentation
Ohne Dateiliste fragt die Action git, welche Markdown-Dateien der Pull Request berührt hat, veröffentlicht jede davon als schreibgeschützte Seite und kommentiert eine Tabelle mit Dateinamen, Wortzahlen und Links. Dateien, die der Branch gelöscht hat, werden übersprungen, ein entferntes Dokument lässt den Lauf also nicht scheitern.
Es ist eine Composite Action, `action.yml` im Wurzelverzeichnis des öffentlichen Repositorys, und sie führt den Kommandozeilen-Client aus demselben Repository aus: kein Container zum Herunterladen, keine Abhängigkeiten zu installieren, und dasselbe Rendering, das die Website und die API liefern.
Der Kommentar trägt die Überschrift Markdown preview. Eine Prüferin öffnet jeden Link im Browser wie jede andere Seite, ohne App und, bei einem Link, ohne Konto — so kann auch jemand, der das Diff nie öffnet, die Texte prüfen.
Ein Diff ist die richtige Ansicht für Code und die falsche für Prosa. Es zeigt, welche Wörter sich geändert haben, und verbirgt, ob sich der Abschnitt noch liest, ob eine Tabelle aufgeht oder ob eine nummerierte Liste mittendrin wieder bei eins beginnt. Die gerenderte Seite beantwortet das auf einen Blick, und wer kein Markdown schreibt, kann sie überhaupt erst lesen.
Ein vollständiger Workflow zum Kopieren liegt in `examples/publish-markdown.yml`. Er läuft bei `pull_request` mit einem `paths`-Filter für `**.md`, sodass ein Pull Request ohne Markdown-Änderung keinen Runner startet. Der Checkout braucht `fetch-depth: 0`, weil die geänderten Dateien gegen den Basis-Commit des Pull Requests ermittelt werden, und der Job braucht `pull-requests: write`, um den Kommentar zu schreiben.
Der Schritt selbst ist `uses: raudarlabs/transformpipe@main` mit einem einzigen Input, `api-key: ${{ secrets.TP_API_KEY }}`. Der Schlüssel ist ein TransformPipe-API-Schlüssel, als Repository-Secret hinterlegt, und die Action reicht ihn dem Client in einer Umgebungsvariablen weiter statt als Argument — so ist er nicht Teil des Befehls, der ins Log geschrieben wird.
`files` nimmt durch Leerzeichen getrennte Pfade anstelle der Liste geänderter Dateien; so veröffentlicht die Action bei einem Push auf einen Branch statt bei einem Pull Request. `share` ist standardmäßig `link`, `people` nur für benannte Leser oder `none`, um die Dokumente privat zu halten. `merge: true` verkettet die Dateien zu einem Dokument, benannt durch `name`.
`replaces` vermerkt ein einzelnes Dokument als neue Version eines früheren, `comment: false` lässt den Kommentar weg, und `host` zeigt auf eine andere Installation.
Für die nachfolgenden Schritte kommen zwei Outputs zurück: `urls`, die veröffentlichten Links zeilenweise, und `documents`, die Antwort der API für jedes Dokument, als JSON. Gibt es nichts zu veröffentlichen, sagt die Action das, lässt `urls` leer und `documents` als leere Liste und endet erfolgreich — ein späterer Schritt lässt sich also an `urls` absichern, statt zu scheitern.
Jeder Lauf veröffentlicht neue Dokumente, statt frühere zu überschreiben, sodass der Link in einem älteren Kommentar weiterhin zeigt, was dieser Commit gesagt hat. Der Preis ist ein Dokument pro Datei und Lauf im Konto, das 5.000 Dokumente und 250 MB fasst; alte Vorschauen lassen sich im Verlauf löschen.
Für einen öffentlichen Link braucht das Konto eine bestätigte E-Mail-Adresse, und bis dahin scheitert der Schritt mit genau diesem Satz. Ein Pull Request aus einem Fork läuft ohne die Secrets des Repositorys, der Schritt hat dort also keinen Schlüssel; überspringen Sie ihn mit `if: github.event.pull_request.head.repo.fork == false`.