GitLab-Integration
Verwandeln Sie Bildschirmaufnahmen in Markdown-Dokumente in GitLab
Nehmen Sie einen Workflow einmal auf. Clevera schreibt die illustrierte Anleitung und überträgt sie als Markdown-Datei inklusive Screenshots in das GitLab-Projekt und den Ordner Ihrer Wahl, damit Ihre Docs-as-Code-Pipeline sie wie jede andere Änderung verarbeiten kann.
GitLab-flavoured Markdown
Screenshots direkt im Projekt
Funktioniert mit GitLab Pages und MkDocs
Keine Credits zum Veröffentlichen
Was Sie tun können
Docs-as-Code,
ohne dass jemand die Dokumentation schreiben muss.
Teams, die GitLab nutzen, behandeln Dokumentation bereits wie Code: Sie liegt in einem Projekt, hat eine Historie und wird über eine Pipeline veröffentlicht. Das Schwierige war nie die Pipeline, sondern das Schreiben der Anleitungen. Clevera erstellt diese aus einer Bildschirmaufnahme und legt sie direkt in den Ordner, den Ihre Pipeline ausliest.
Eine Anleitung für jeden Walkthrough
Zeigen Sie die Funktion einmal auf dem Bildschirm. Clevera verwandelt die Aufnahme in eine schriftliche Anleitung mit nummerierten Schritten und Screenshots, bereit für das Projekthandbuch oder die Produktdokumentation.
Ihre Pipeline erledigt den Rest
Jede Veröffentlichung ist ein normaler Commit auf dem Standard-Branch, sodass GitLab Pages, MkDocs oder Hugo die Seite genau so neu erstellen wie bei der Änderung eines Teammitglieds.
Bilder, die im Projekt leben
Screenshots werden neben der Markdown-Datei übertragen und über relative Pfade verlinkt. Sie sind nicht von Clevera abhängig und bleiben in einem privaten Projekt privat.
Updates als lesbare Commits
Bearbeiten Sie den Artikel in Clevera und veröffentlichen Sie ihn erneut. Die Datei und ihre Bilder werden in einem „Update article“-Commit überschrieben, sodass die Historie zeigt, was wann geändert wurde.
Jedes Projekt, jeder Ordner
Wählen Sie aus jedem GitLab-Projekt, in dem das verbundene Konto die Rolle „Developer“ oder höher hat, und geben Sie den Ordner an: docs, handbook/support oder das Projekt-Root-Verzeichnis.
Hält sich an Ihre Branch-Regeln
Clevera respektiert geschützte Branches. Wenn nur Maintainer auf mainpushen dürfen, verbinden Sie ein Maintainer-Konto oder erlauben Sie Entwicklern das Pushen.
So funktioniert es
Von der Aufnahme zum GitLab-Projekt
in vier Schritten.
Ein Inhaber oder Administrator verbindet GitLab einmalig. Danach kann jeder, der einen Artikel bearbeiten darf, diesen aus dem Editor heraus veröffentlichen.
- 1
GitLab.com verbinden
Melden Sie sich bei GitLab an und autorisieren Sie Clevera. Es werden die Projekte aufgelistet, in denen Ihr Konto die Rolle „Developer“ oder höher hat. - 2
Clevera schreibt die Anleitung
Aus der Bildschirmaufnahme erstellt Clevera den Hilfeartikel: Überschriften, nummerierte Schritte, Infoboxen und Screenshots. - 3
Projekt und Ordner wählen
Öffnen Sie in „Share“ den Bereich „Publish“, wählen Sie das GitLab-Projekt und den Ordner aus und klicken Sie auf „Publish to GitLab“. - 4
Ein Commit wird erstellt
Die Markdown-Datei und ihre Bilder landen gemeinsam in einem Commit auf dem Standard-Branch und Ihre Pipeline startet.
In Clevera ansehen
Veröffentlichung in GitLab,
über das „Share“-Fenster des Artikels.
Kein Exportieren, kein manuelles Kopieren von Markdown, kein Ziehen von Screenshots in ein Repository. Das „Share“-Fenster, das Ihnen einen Link und einen Einbettungscode liefert, überträgt die Daten auch direkt an GitLab.
Projekt und Ordner auswählen
Die Liste zeigt die Projekte, in denen das verbundene GitLab-Konto die Rolle „Developer“ oder höher hat, sortiert nach der letzten Aktualisierung. Geben Sie den Ordner an, in dem Ihre Dokumentation liegt, wie zum Beispiel docs/guides; Ordner, die noch nicht existieren, werden im selben Commit erstellt.
Clevera merkt sich das Projekt und den Ordner, sodass der nächste Artikel am selben Ort landet.
Erneutes Veröffentlichen ohne doppelte Dateien
Bevor Clevera schreibt, wird nach einer Datei mit demselben Namen in diesem Ordner gesucht. Wenn eine gefunden wird, haben Sie die Wahl: Überschreiben in einem neuen Commit oder Beibehalten und Veröffentlichen dieser Version unter einem neuen Titel.
Die Veröffentlichung funktioniert nur in eine Richtung. Änderungen, die jemand an der Datei in GitLab vornimmt, fließen nicht in den Clevera-Artikel zurück.
GitLab neben dem Rest Ihres Stacks
Manche Teams speichern Produktdokumentationen in GitLab und das interne Wiki an einem anderen Ort. Verbinden Sie jedes Tool einmal und veröffentlichen Sie denselben Artikel in GitLab, Confluence oder Notion über denselben Tab.
Automatisch ausgefüllt
Was jeder Commit enthält
und was Sie entscheiden.
Clevera schreibt Markdown, das GitLab in der Dateiansicht korrekt anzeigt und das von Static-Site-Generatoren sauber verarbeitet wird. Hier sehen Sie genau, was eine Veröffentlichung in Ihrem Projekt bewirkt.
- Projekt und OrdnerIhre Wahl
- Jedes GitLab.com-Projekt, in dem das verbundene Konto die Rolle „Developer“ oder höher hat, sowie jeder Ordner darin. Der Ordner beginnt mit
docs; lassen Sie das Feld leer für das Projekt-Root-Verzeichnis. - DateinameAutomatisch gesetzt
- Der Titel des Artikels in Kleinbuchstaben mit Bindestrichen, endend auf
.md. „Reset a customer password“ wird zureset-a-customer-password.md. Titel mit Akzenten und nicht-lateinischen Zeichen werden in lateinische Buchstaben umgewandelt, Namen werden bei 80 Zeichen gekürzt. - Front MatterAutomatisch gesetzt
- Ein YAML-Block mit
title,created_at,updated_atundsource. MkDocs, Hugo und Docusaurus lesen den Titel und ignorieren den Rest. - Infoboxen und FormatierungAutomatisch konvertiert
- Infoboxen werden zu GitLab-Alerts mit dem Titel in der gleichen Zeile, wie zum Beispiel
> [!WARNING] Careful. Tabellen, Aufgabenlisten, mathematische Formeln, Code-Blöcke mit Sprachangabe und einklappbare<details>-Bereiche werden so übernommen, wie GitLab sie rendert. - ScreenshotsAutomatisch gesetzt
- Übertragen nach
assets/<file name>/im selben Ordner, im selben Commit, mit jeder Bildunterschrift kursiv unter dem Bild. - CommitAutomatisch gesetzt
- Ein Commit auf dem Standard-Branch mit der Nachricht
Add article: …oderUpdate article: …, erstellt von dem GitLab-Konto, das Clevera verbunden hat. - VideosAutomatisch gesetzt
- Ein Video innerhalb des Artikels wird zu einem Vorschaubild, das zum Player verlinkt, plus einem ▶-Link mit dem Titel. Die ursprüngliche Aufnahme, aus der der Artikel stammt, wird nicht hinzugefügt.
Einrichtung
GitLab-Integration einrichten
in etwa zwei Minuten.
Sie benötigen einen Clevera-Workspace mit Pro- oder Custom-Plan und ein GitLab.com-Konto. Der Workspace-Inhaber oder ein Administrator verbindet GitLab; danach kann jeder, der einen Artikel bearbeiten kann, diesen veröffentlichen. Die Veröffentlichung verbraucht keine Credits.
- 1
Integrationen öffnen
Öffnen Sie in Clevera das Workspace-Menü, wählen Sie Integrations, suchen Sie GitLab unter Code repositories und klicken Sie auf Connect. - 2
Clevera auf GitLab.com autorisieren
GitLab fragt nach den api, read_user, read_repository und write_repository Scopes, die für die Datei-API zum Erstellen und Aktualisieren von Dateien benötigt werden. Klicken Sie auf Authorize. - 3
Rolle überprüfen
Verwenden Sie ein Konto, das in jedem Projekt die Rolle „Developer“ oder höher hat. Um auf einen geschützten Standard-Branch zu committen, ist normalerweise Maintainererforderlich; ein geteiltes Bot-Konto funktioniert hierfür gut. - 4
Artikel veröffentlichen
Klicken Sie im Artikel-Editor auf Share, öffnen Sie Publish, klicken Sie auf die GitLab-Kachel, wählen Sie Projekt und Ordner aus und klicken Sie auf Publish to GitLab. - 5
In GitLab öffnen
Wenn Sie „Published to GitLab.“ sehen, klicken Sie auf Open in GitLab , um die Datei und den Commit zu sehen.
Fragen zur GitLab-Integration
Aktuell nicht. Clevera verbindet sich nur mit GitLab.com. Selbst gehostete GitLab-Server werden nicht unterstützt, daher kann ein Projekt auf Ihrer eigenen GitLab-Instanz kein Ziel für die Veröffentlichung sein.
Nein. Clevera committet direkt auf den Standard-Branch des Projekts, normalerweise main, und Sie können keinen anderen Branch wählen. Wenn Ihr Team Dokumentationen in Merge Requests prüft, überprüfen Sie den Artikel in Clevera, bevor Sie ihn veröffentlichen, oder veröffentlichen Sie in ein Projekt, in dem direkte Commits erlaubt sind.
Fast immer liegt es an einem geschützten Branch. GitLab schützt den Standard-Branch und lässt normalerweise nur Maintainer darauf pushen. Geben Sie dem verbundenen Konto die Rolle „Maintainer“ oder erlauben Sie Entwicklern das Pushen unter Settings → Repository → Protected branches.
Ja. Geben Sie den Ordner an, aus dem Ihre Seite erstellt wird. Jede Veröffentlichung ist ein normaler Commit, sodass Ihre CI/CD-Pipeline wie gewohnt läuft und der Generator die Daten title aus dem Front Matter liest. Überprüfen Sie, ob Ihr Theme Alerts und einklappbare Bereiche korrekt rendert.
In GitLab ändert sich nichts, bis Sie erneut veröffentlichen. Dann findet Clevera die vorhandene Datei und ermöglicht es Ihnen, sie in einem neuen Commit zu aktualisieren. Wenn Sie den Artikel umbenannt haben, wird der neue Titel zu einer neuen Datei; löschen Sie die alte Datei selbst in GitLab. Clevera löscht niemals Dateien aus Ihrem Projekt.
Ein Workspace unterstützt eine GitLab-Verbindung; eine erneute Verbindung ersetzt die bestehende. Verwenden Sie ein Konto, das Mitglied in jedem Projekt ist, in das Sie veröffentlichen.
Die Veröffentlichung in GitLab ist Teil der Pro- und Custom-Pläne und verbraucht keine Credits. Die Erstellung des Artikels selbst verbraucht wie gewohnt Credits. Siehe Preise.
Ja. Verbinden Sie jedes Tool einmal und veröffentlichen Sie denselben Artikel an beliebig viele Ziele. Siehe die GitHub und Bitbucket Integrationen oder alle Integrationen.
Ihr nächster Leitfaden, bereits im Projekt.
Einmal aufnehmen. Clevera schreibt den Leitfaden und committet ihn inklusive Screenshots in GitLab.