Artikel auf ReadMe veröffentlichen
Verbinde ein ReadMe-Projekt mit seinem API-Schlüssel und veröffentliche Clevera-Artikel als Anleitungen in der Kategorie deiner Wahl, wobei Screenshots direkt zu ReadMe hochgeladen werden. Erfahre, wie Callouts, Schritte und Videos konvertiert werden, wie Aktualisierungen funktionieren und wie du häufige Fehler behebst.
Veröffentliche einen Clevera-Artikel als Anleitung in deinem ReadMe-Projekt, abgelegt unter der von dir gewählten Kategorie für Anleitungen. Screenshots werden auf ReadMe hochgeladen.
Bevor du beginnst
- In Clevera: Dein Arbeitsbereich nutzt den Pro- oder Benutzerdefiniert-Plan und du bist Eigentümer oder Administrator, um ReadMe zu verbinden. Sobald die Verbindung besteht, kann jeder, der einen Artikel bearbeiten kann, ihn auch veröffentlichen. Siehe Artikel in deinen anderen Tools veröffentlichen.
- In ReadMe: Ein Projekt, das du verwalten kannst, mit mindestens einer Kategorie im Bereich Anleitungen. Ein Schlüssel verbindet ein Projekt.
- Ein aktuelles ReadMe-Projekt: Clevera veröffentlicht über die aktuelle (v2) API von ReadMe, die ReadMe für Projekte auf ReadMe Refactored anbietet. Projekte, die sich noch auf der älteren Plattform von ReadMe befinden, können nicht verbunden werden.
- Version: Clevera veröffentlicht in der Hauptversion (stabil) deiner Anleitungen.
- Ein Artikel: Erstelle ihn zuerst. Beim Veröffentlichen wird nur der Artikel gesendet. Um ein Video einzufügen, platziere es innerhalb des Artikels; siehe Ein Video in einem Artikel anzeigen.
Finde deinen ReadMe API-Schlüssel
Öffne in deinem ReadMe-Projekt Configuration → API Keys und kopiere einen Schlüssel (erstelle einen, falls die Liste leer ist). Der Schlüssel gewährt vollen Zugriff auf dieses Projekt, behandle ihn also vertraulich.
ReadMe verbinden
Das Verbindungsfenster öffnen
Klicke in Clevera in der Seitenleiste auf den Namen deines Arbeitsbereichs, wähle Integrationen, suche ReadMe und klicke auf Verbinden. Im Fenster ReadMe verbinden steht: „Füge einen Schlüssel ein. Wir prüfen ihn, bevor wir etwas speichern.“
Den Schlüssel einfügen und prüfen
Füge den Schlüssel in API-Schlüssel ein und klicke auf Schlüssel prüfen. Wenn ReadMe ihn akzeptiert, siehst du „Schlüssel akzeptiert.“ und dein Projekt unter Seiten, auf denen veröffentlicht werden soll.
Verbinden
Klicke auf Verbinden. Du siehst „ReadMe verbunden.“ und ReadMe erscheint unter Verbunden mit dem Namen deines Projekts.
Der Schlüssel läuft auf der Seite von Clevera nicht ab. Um ein anderes Projekt zu verbinden, verwende Erneut verbinden bei der ReadMe-Verbindung und füge den Schlüssel des neuen Projekts ein; er ersetzt den alten.
Einen Artikel auf ReadMe veröffentlichen
Den Tab „Veröffentlichen“ öffnen
Klicke im Editor auf Teilen → Veröffentlichen und klicke auf die ReadMe-Kachel unter Bereit zur Veröffentlichung.
Eine Kategorie für Anleitungen wählen
Unter Wohin soll es gehen zeigt Projekt das verbundene Projekt an. Wähle eine Kategorie für Anleitungen: „Der Artikel wird in den Anleitungen unter dieser Kategorie abgelegt.“ Falls du „Noch keine Kategorien für Anleitungen vorhanden“ siehst, erstelle zuerst eine in ReadMe.
Veröffentlichen
Klicke auf Auf ReadMe veröffentlichen. Clevera sucht zuerst nach einer vorhandenen Kopie; falls bereits eine Anleitung mit derselben Adresse existiert, wähle aus, was geschehen soll (siehe Eine Anleitung aktualisieren). Wenn der Vorgang abgeschlossen ist, siehst du „Auf ReadMe veröffentlicht.“ Klicke auf In ReadMe öffnen, um die Anleitung anzusehen.
Du kannst das Fenster „Teilen“ schließen, während der Vorgang läuft; eine Benachrichtigung informiert dich, wenn er abgeschlossen ist.
Die Adresse der Anleitung leitet sich aus ihrem Titel ab: „Set up billing“ wird zu /docs/set-up-billing auf deiner Dokumentationsseite. Titel in anderen Schriften oder mit Akzenten werden zuerst in lateinische Buchstaben umgewandelt. Wenn die Adresse bereits vergeben ist, gibt ReadMe der neuen Anleitung eine leicht abweichende Adresse.
Wie die Anleitung in ReadMe aussieht
Der Titel der Anleitung entspricht dem Titel des Artikels. Die Anleitung enthält nur den Artikel: Das Video, aus dem der Artikel stammt, wird nicht hinzugefügt.
| In Clevera | In ReadMe |
|---|---|
| Überschriften, Absätze | Überschriften und Text |
| Fett, kursiv, durchgestrichen, Inline-Code, Links | Beibehalten. Links zu anderen Clevera-Seiten behalten nur ihren Text. |
| Hervorhebung, hochgestellt, tiefgestellt | Beibehalten |
| Aufzählungs- und nummerierte Listen, Checklisten | Listen und Checklisten |
| Zitate | Zitate |
| Code-Blöcke | Code-Blöcke mit der Sprache und dem Code-Titel |
| Trennlinien | Trennlinien |
| Tabellen | Tabellen mit dem Text jeder Zelle |
| Callouts | ReadMe-Callouts mit dem Callout-Titel: 📘 für Info und Hinweis, 👍 für Tipp und Erfolg, 🚧 für Warnung, ❗️ für Gefahr |
| Nummerierte Schritte | Eine nummerierte Liste: der Titel jedes Schritts in Fett, sein Inhalt darunter eingerückt |
| Tabs | Das Label jedes Tabs in Fett, gefolgt von seinem Inhalt. Tabs, die nur Code enthalten, werden zu ReadMe-Code-Tabs. |
| Ausklappbare Bereiche | Ausklappbare Bereiche |
| Karten | Eine Liste von Links mit ihren Beschreibungen; Karten-Icons werden weggelassen |
| Gleichungen | Code |
| Screenshots | Bilder, die auf ReadMe hochgeladen wurden, mit der Bildunterschrift in Kursiv |
| Videos und Einbettungen im Artikel | ReadMe-Einbettungen. Ein Clevera-Video wird nur dann eingefügt, wenn der Freigabelink des Videos aktiviert ist. |
Geschweifte Klammern und spitze Klammern in deinem Text werden maskiert, sodass das Seitenformat von ReadMe sie so anzeigt, wie sie geschrieben wurden.
Screenshots werden auf ReadMe hochgeladen, sodass sie auch dann funktionieren, wenn du den Artikel in Clevera löschst. Ein Screenshot, dessen Upload fehlschlägt, oder eine Videodatei innerhalb des Artikels bleibt ein Link zu Clevera, der nach einer Weile abläuft; veröffentliche erneut, um ihn zu erneuern.
Eine Anleitung aktualisieren
Die Veröffentlichung funktioniert nur in eine Richtung. Die Anleitung wird nicht aktualisiert, wenn du den Artikel in Clevera bearbeitest, und in ReadMe vorgenommene Änderungen werden nie zurück nach Clevera übertragen. Nachdem du den Artikel bearbeitet hast, veröffentliche ihn erneut.
Clevera sucht überall in deinen Anleitungen nach einer Anleitung mit derselben Adresse und zeigt „Dieser Artikel ist bereits in ReadMe.“ Klicke auf Ansehen, um sie zu öffnen, und wähle dann:
- Den bestehenden Artikel aktualisieren überschreibt diese Anleitung: gleiche Adresse, neuer Titel und Inhalt. Klicke auf In ReadMe aktualisieren.
- Einen neuen Artikel erstellen erstellt eine neue Anleitung unter dem von dir eingegebenen Neuen Titel mit einer eigenen Adresse. Klicke auf Neuen Artikel erstellen.
Änderungen, die seit der letzten Veröffentlichung in ReadMe vorgenommen wurden, werden überschrieben, wenn Clevera eine Anleitung aktualisiert.
Verbindung trennen und Zugriff widerrufen
- Öffne in Clevera Integrationen, klicke auf ReadMe, dann auf Trennen und bestätige. Bereits veröffentlichte Anleitungen bleiben in ReadMe erhalten.
- Öffne in ReadMe Configuration → API Keys und lösche den Schlüssel, den du Clevera gegeben hast.
Fehlerbehebung
| Du siehst | Was zu tun ist |
|---|---|
| „Füge zuerst einen Schlüssel ein.“ | Das Schlüsselfeld ist leer. |
| „Ungültiger API-Schlüssel. Bitte prüfe deinen ReadMe API-Schlüssel.“ | Der Schlüssel ist falsch oder wurde gelöscht. Kopiere ihn erneut aus Configuration → API Keys. |
| „Projektinformationen konnten nicht von ReadMe abgerufen werden.“ oder „Wir konnten diesen Schlüssel nicht prüfen. Erneut versuchen.“ | ReadMe hat nicht geantwortet oder das Projekt befindet sich nicht auf ReadMe Refactored, was Clevera benötigt. Versuche es erneut, dann mit einem neuen Schlüssel; falls das Projekt auf der älteren Plattform von ReadMe liegt, kann es nicht verbunden werden. |
| „API-Schlüssel konnte nicht validiert werden. Bitte prüfe deinen ReadMe API-Schlüssel.“ oder „Verbindung zu ReadMe fehlgeschlagen. Bitte prüfe deinen API-Schlüssel.“ | Prüfe den Schlüssel und verbinde erneut. |
| „Noch keine Kategorien für Anleitungen vorhanden“ / „Erstelle eine Kategorie für Anleitungen in ReadMe, um hier zu veröffentlichen.“ | Füge deinen Anleitungen in ReadMe eine Kategorie hinzu und öffne dann den Tab „Veröffentlichen“ erneut. |
| „Wähle zuerst eine Kategorie.“ oder „Wähle eine ReadMe-Kategorie, in der diese Anleitung veröffentlicht werden soll.“ | Wähle vor dem Veröffentlichen eine Kategorie für Anleitungen. |
| „Du kannst dieses Element ansehen, aber nicht veröffentlichen. Frage jemanden, der es bearbeiten kann.“ | Du benötigst Bearbeitungszugriff auf den Artikel, um ihn zu veröffentlichen. |
| „API-Schlüssel nicht gefunden. Bitte verbinde ReadMe erneut.“ | Verbinde ReadMe erneut mit einem Schlüssel. |
| „Artikelinhalt ist leer oder ungültig.“ | Der Artikel hat noch keinen Inhalt. Öffne ihn, prüfe ihn und veröffentliche ihn dann. |
| „Konnte nicht auf ReadMe veröffentlichen“ mit einer Nachricht von ReadMe, z. B. bezüglich des Slugs oder der Kategorie | ReadMe hat die Anleitung abgelehnt. Prüfe, ob die Kategorie noch existiert, oder benenne den Artikel um und klicke auf Erneut versuchen. |
| „Anleitung in ReadMe konnte nicht aktualisiert werden“ | Die Anleitung, die du aktualisieren wolltest, wurde in ReadMe gelöscht oder umbenannt. Veröffentliche erneut und wähle Einen neuen Artikel erstellen. |
| „Veröffentlichung auf ReadMe fehlgeschlagen. Bitte versuche es erneut.“ | Klicke auf Erneut versuchen. Wenn es weiterhin fehlschlägt, verbinde dich erneut mit einem frischen Schlüssel. |