Artikelen publiceren naar ReadMe
Verbind een ReadMe-project met de bijbehorende API-sleutel en publiceer Clevera-artikelen als gidsen in de categorie van jouw keuze, waarbij schermafbeeldingen worden geüpload naar ReadMe. Hoe callouts, stappen en video's worden omgezet, hoe updates werken en veelvoorkomende fouten.
Publiceer een Clevera-artikel als een gids in je ReadMe-project, ondergebracht in de gidsencategorie die je kiest. Schermafbeeldingen worden geüpload naar ReadMe.
Voordat je begint
- In Clevera: de werkruimte heeft een Pro- of Aangepast-abonnement en je bent eigenaar of beheerder om ReadMe te verbinden. Zodra het is verbonden, kan iedereen die een artikel kan bewerken, het publiceren. Zie Artikelen publiceren naar je andere tools.
- In ReadMe: een project dat je kunt beheren, met ten minste één categorie in de sectie Gidsen. Eén sleutel verbindt één project.
- Een actueel ReadMe-project: Clevera publiceert via de huidige (v2) API van ReadMe, die ReadMe aanbiedt aan projecten op ReadMe Refactored. Projecten die nog op het oudere platform van ReadMe staan, kunnen niet worden verbonden.
- Versie: Clevera publiceert naar de hoofdversie (stabiel) van de Gidsen van je project.
- Een artikel: genereer dit eerst. Bij publicatie wordt alleen het artikel verzonden. Om een video toe te voegen, plaats je deze in het artikel; zie Een video tonen in een artikel.
Je ReadMe API-sleutel vinden
Open in je ReadMe-project Configuration → API Keys en kopieer een sleutel (maak er een aan als de lijst leeg is). De sleutel geeft volledige toegang tot dat project, dus houd deze privé.
ReadMe verbinden
Het verbindingsvenster openen
Klik in Clevera op je werkruimtenaam in de zijbalk, kies Integraties, zoek ReadMe en klik op Verbinden. In het venster ReadMe verbinden staat: "Plak een sleutel. We controleren deze voordat we iets opslaan."
De sleutel plakken en controleren
Plak de sleutel in API-sleutel en klik op Sleutel controleren. Wanneer ReadMe deze accepteert, zie je "Sleutel geaccepteerd." en je project onder Sites om naar te publiceren.
Verbinden
Klik op Verbinden. Je ziet "ReadMe verbonden." en ReadMe verschijnt onder Verbonden met de naam van je project.
De sleutel verloopt niet aan de kant van Clevera. Om een ander project te verbinden, gebruik je Opnieuw verbinden bij de ReadMe-verbinding en plak je de sleutel van dat project; dit vervangt de oude.
Een artikel publiceren naar ReadMe
Het tabblad Publiceren openen
Klik in de editor op Delen → Publiceren en klik op de ReadMe-tegel onder Klaar om te publiceren.
Een gidsencategorie kiezen
Onder Waar het heen gaat toont Project het verbonden project. Kies een Gidsencategorie: "Het artikel komt in de sectie Gidsen, onder deze categorie." Als je "Nog geen gidsencategorieën" ziet, maak er dan eerst een aan in ReadMe.
Publiceren
Klik op Publiceren naar ReadMe. Clevera zoekt eerst naar een bestaande kopie; als er al een gids met hetzelfde adres bestaat, kies dan wat je wilt doen (zie Een gids bijwerken). Wanneer het klaar is, zie je "Gepubliceerd naar ReadMe." Klik op Openen in ReadMe om de gids te bekijken.
Je kunt het venster Delen sluiten terwijl het proces loopt; een melding laat je weten wanneer het klaar is.
Het adres van de gids is afgeleid van de titel: "Set up billing" wordt /docs/set-up-billing op je documentatiesite. Titels in andere schriften of met accenten worden eerst in Latijnse letters geschreven. Als het adres al in gebruik is, geeft ReadMe de nieuwe gids een iets ander adres.
Hoe de gids eruitziet in ReadMe
De titel van de gids is de titel van het artikel. De gids bevat alleen het artikel: de video waar het artikel vandaan kwam, wordt niet toegevoegd.
| In Clevera | In ReadMe |
|---|---|
| Koppen, alinea's | Koppen en tekst |
| Vet, cursief, doorhalen, inline code, links | Behouden. Links naar andere Clevera-pagina's behouden alleen hun tekst. |
| Markeren, superscript, subscript | Behouden |
| Opsommingstekens en genummerde lijsten, checklists | Lijsten en checklists |
| Citaten | Citaten |
| Codeblokken | Codeblokken met de taal en de codetitel |
| Scheidingslijnen | Scheidingslijnen |
| Tabellen | Tabellen met de tekst van elke cel |
| Callouts | ReadMe-callouts met de callout-titel: 📘 voor info en opmerking, 👍 voor tip en succes, 🚧 voor waarschuwing, ❗️ voor gevaar |
| Genummerde stappen | Een genummerde lijst: de titel van elke stap vetgedrukt, de inhoud eronder genest |
| Tabbladen | Het label van elk tabblad vetgedrukt, gevolgd door de inhoud. Tabbladen die alleen code bevatten, worden ReadMe-codetabbladen. |
| Inklapbare secties | Uitklapbare secties |
| Kaarten | Een lijst met links met hun beschrijvingen; kaartpictogrammen worden weggelaten |
| Vergelijkingen | Code |
| Schermafbeeldingen | Afbeeldingen geüpload naar ReadMe, met het bijschrift cursief |
| Video's en embeds in het artikel | ReadMe-embeds. Een Clevera-video wordt alleen opgenomen als de deellink van die video is ingeschakeld. |
Accolades en punthaken in je tekst worden geëscaped, zodat de paginaindeling van ReadMe ze weergeeft zoals geschreven.
Schermafbeeldingen worden geüpload naar ReadMe, dus ze blijven werken, zelfs als je het artikel in Clevera verwijdert. Een schermafbeelding die niet kan worden geüpload, of een videobestand in het artikel, blijft een link naar Clevera die na verloop van tijd verloopt; publiceer opnieuw om deze te vernieuwen.
Een gids bijwerken
Publiceren werkt maar in één richting. De gids wordt niet bijgewerkt wanneer je het artikel in Clevera bewerkt, en wijzigingen in ReadMe worden nooit teruggezet naar Clevera. Nadat je het artikel hebt bewerkt, publiceer je het opnieuw.
Clevera zoekt overal in je Gidsen naar een gids met hetzelfde adres en toont "Dit artikel staat al in ReadMe." Klik op Bekijken om het te openen en kies vervolgens:
- Het bestaande artikel bijwerken overschrijft die gids: hetzelfde adres, nieuwe titel en inhoud. Klik op Bijwerken in ReadMe.
- Een nieuw artikel maken maakt een nieuwe gids onder de Nieuwe titel die je invoert, met een eigen adres. Klik op Nieuw artikel maken.
Wijzigingen die in ReadMe zijn aangebracht sinds de laatste publicatie worden overschreven wanneer Clevera een gids bijwerkt.
Verbinding verbreken en toegang intrekken
- Open in Clevera Integraties, klik op ReadMe, vervolgens op Verbinding verbreken en bevestig. Gidsen die je al hebt gepubliceerd, blijven in ReadMe staan.
- Open in ReadMe Configuration → API Keys en verwijder de sleutel die je aan Clevera hebt gegeven.
Problemen oplossen
| Je ziet | Wat te doen |
|---|---|
| "Plak eerst een sleutel." | Het sleutelveld is leeg. |
| "Ongeldige API-sleutel. Controleer je ReadMe API-sleutel." | De sleutel is onjuist of verwijderd. Kopieer deze opnieuw vanuit Configuration → API Keys. |
| "Kon projectinformatie niet ophalen van ReadMe." of "We konden die sleutel niet controleren. Probeer het opnieuw." | ReadMe antwoordde niet, of het project staat niet op ReadMe Refactored, wat Clevera vereist. Probeer het opnieuw, probeer dan een nieuwe sleutel; als het project op het oudere platform van ReadMe staat, kan het niet worden verbonden. |
| "Kon API-sleutel niet valideren. Controleer je ReadMe API-sleutel." of "Kon geen verbinding maken met ReadMe. Controleer je API-sleutel." | Controleer de sleutel en verbind opnieuw. |
| "Nog geen gidsencategorieën" / "Maak een gidsencategorie in ReadMe om hier te publiceren." | Voeg een categorie toe aan je Gidsen in ReadMe en open daarna het tabblad Publiceren opnieuw. |
| "Kies eerst een categorie." of "Kies een ReadMe-categorie om deze gids in te publiceren." | Kies een gidsencategorie voordat je publiceert. |
| "Je kunt dit item bekijken maar niet publiceren. Vraag iemand die het kan bewerken." | Je hebt bewerkingsrechten voor het artikel nodig om het te publiceren. |
| "API-sleutel niet gevonden. Verbind ReadMe opnieuw." | Verbind ReadMe opnieuw met een sleutel. |
| "Artikelinhoud is leeg of ongeldig." | Het artikel heeft nog geen inhoud. Open het, controleer het en publiceer dan. |
| "Kon niet publiceren naar ReadMe" met een bericht van ReadMe, zoals een bericht over de slug of categorie | ReadMe heeft de gids geweigerd. Controleer of de categorie nog bestaat, of hernoem het artikel en klik op Opnieuw proberen. |
| "Gids in ReadMe kon niet worden bijgewerkt" | De gids die je probeerde bij te werken is verwijderd of hernoemd in ReadMe. Publiceer opnieuw en kies Een nieuw artikel maken. |
| "Kon niet publiceren naar ReadMe. Probeer het opnieuw." | Klik op Opnieuw proberen. Als het blijft mislukken, verbind dan opnieuw met een nieuwe sleutel. |