Artikelen publiceren naar GitBook
Verbind GitBook met een persoonlijke toegangssleutel en publiceer Clevera-artikelen als pagina's in je GitBook-spaces. Waar je de sleutel aanmaakt, sites kiezen, hoe hints, stappen en tabbladen worden omgezet, wat bijwerken doet en veelvoorkomende fouten.
Publiceer een Clevera-artikel als een pagina in een GitBook-space. GitBook maakt verbinding met een persoonlijke toegangssleutel in plaats van een aanmelding, en de pagina verschijnt op het hoogste niveau van de space die je kiest.
Voordat je begint
- In Clevera: de workspace heeft het Pro- of Aangepast-abonnement en je bent eigenaar of beheerder om GitBook te verbinden. Zodra het is verbonden, kan iedereen die een artikel kan bewerken, dit publiceren. Zie Artikelen publiceren naar je andere tools.
- In GitBook: elk abonnement. De sleutel fungeert als de GitBook-gebruiker die deze heeft aangemaakt, dus die persoon heeft bewerkingsrechten nodig voor de spaces waarnaar je publiceert.
- Een artikel: genereer het eerst. Bij publiceren wordt alleen het artikel verzonden. Om een video toe te voegen, plaats je deze in het artikel; zie Een video tonen in een artikel.
Een GitBook-toegangssleutel aanmaken
- Open in GitBook je accountinstellingen en ga naar Developer (
app.gitbook.com/account/developer). - Maak een nieuwe persoonlijke toegangstoken aan, geef deze een naam zoals "Clevera" en kopieer deze. GitBook toont de sleutel slechts één keer.
GitBook verbinden
Het verbindingsvenster openen
Klik in Clevera op je workspacenaam in de zijbalk, kies Integraties, zoek GitBook en klik op Verbinden. Het venster GitBook verbinden zegt "Plak een sleutel. We controleren deze voordat we iets opslaan." en bevat een Open GitBook-link naar de Developer-pagina.
De sleutel plakken en controleren
Plak de sleutel in Toegangssleutel en klik op Sleutel controleren. Wanneer GitBook deze accepteert, zie je "Sleutel geaccepteerd."
De sites kiezen
Onder Sites om naar te publiceren toont Clevera je docs-sites (of spaces) en selecteert deze allemaal. Open de lijst om sites die je niet wilt uit te vinken, bijvoorbeeld "2 van 3 geselecteerd", en klik dan op Verbinden. Je ziet "GitBook verbonden.".
Clevera controleert de sleutel voordat er iets wordt opgeslagen.
Als je GitBook-account helemaal geen spaces heeft, maakt Clevera er een aan met de naam "Clevera" in je eerste organisatie, zodat je direct kunt publiceren.
De sleutel verloopt niet aan de kant van Clevera. Om de sleutel of de sites te wijzigen, open je het ⋯-menu bij de GitBook-verbinding, kies je Opnieuw verbinden en doorloop je hetzelfde venster; de nieuwe sleutel en keuze vervangen de oude.
Een artikel publiceren naar GitBook
Het tabblad Publiceren openen
Klik in de editor op Delen → Publiceren en klik op de GitBook-tegel onder Klaar om te publiceren.
Een space kiezen
Onder Waar het naartoe gaat, toont de lijst de spaces achter de sites die je hebt gekozen, met hun iconen.
Publiceren
Klik op Publiceren naar GitBook. Clevera zoekt eerst naar een bestaande kopie; als er al een pagina met dezelfde titel in de space staat, kies je wat je wilt doen (zie Een gepubliceerde pagina bijwerken). Wanneer het klaar is, zie je "Gepubliceerd naar GitBook." Klik op Openen in GitBook om de pagina te bekijken.
Je kunt het venster Delen sluiten terwijl het proces loopt; een melding laat je weten wanneer het klaar is.
De pagina wordt toegevoegd op het hoogste niveau van de space en het adres is afgeleid van de titel: "Set up billing" wordt /set-up-billing. Titels in andere schriften of met accenten worden eerst in Latijnse letters geschreven; een titel waar niets meer van overblijft krijgt een korte vaste code. Verplaats of hernoem de pagina daarna in GitBook als je wilt.
Hoe de pagina eruitziet in GitBook
De paginatitel is de titel van het artikel. De pagina bevat alleen het artikel: de video waar het artikel vandaan kwam, wordt niet toegevoegd.
| In Clevera | In GitBook |
|---|---|
| Koppen, alinea's | Koppen en tekst |
| Vet, cursief, doorhalen, inline code, links | Behouden |
| Markering, superscript, subscript | Behouden |
| Opsommingstekens en genummerde lijsten, checklists | Lijsten en takenlijsten |
| Citaten | Citaten |
| Codeblokken | Codeblokken met de taal en de codetitel |
| Scheidingslijnen | Scheidingslijnen |
| Tabellen | Tabellen met de tekst van elke cel |
| Callouts | Hint-blokken: info → Info, note → Info, tip → Success, success → Success, warning → Warning, danger → Danger |
| Genummerde stappen | Een GitBook-stappenplan, één stap per stap |
| Tabbladen | GitBook-tabbladen |
| Inklapbare secties | Uitklapbare blokken |
| Kaarten | Een lijst met links met hun beschrijvingen; kaarticonen worden weggelaten |
| Vergelijkingen | GitBook-wiskunde |
| Screenshots | Afbeeldingen geüpload naar de space, met het bijschrift |
| Video's en embeds in het artikel | Embed-blokken. Een Clevera-video wordt alleen opgenomen wanneer de deellink van die video aan staat. |
Screenshots worden als bestanden naar de space geüpload, dus ze blijven werken, zelfs als je het artikel in Clevera verwijdert. Een videobestand dat in het artikel is geüpload, blijft een link naar Clevera die na verloop van tijd verloopt; publiceer opnieuw om deze te vernieuwen.
Een gepubliceerde pagina bijwerken
Publiceren werkt maar in één richting. De GitBook-pagina wordt niet bijgewerkt wanneer je het artikel in Clevera bewerkt, en wijzigingen in GitBook komen nooit terug naar Clevera. Nadat je het artikel hebt bewerkt, publiceer je het opnieuw naar dezelfde space. Clevera zoekt naar een pagina met dezelfde titel (hoofdletters maken niet uit) of hetzelfde adres en toont "Dit artikel staat al in GitBook."
- Bestaand artikel bijwerken overschrijft de inhoud en titel van die pagina. Het adres blijft hetzelfde. Wijzigingen die sindsdien in GitBook zijn aangebracht, worden overschreven; met de geschiedenis van GitBook kun je ze terughalen. Klik op Bijwerken in GitBook.
- Nieuw artikel aanmaken voegt een tweede pagina toe onder de Nieuwe titel die je invoert (Clevera stelt er een voor zoals "Set up billing (2)"), met een eigen adres. Klik op Nieuw artikel aanmaken.
Verbinding verbreken en toegang intrekken
- Open in Clevera Integraties, klik op GitBook, dan op Verbinding verbreken en bevestig. Pagina's die je al hebt gepubliceerd, blijven in GitBook staan.
- Verwijder in GitBook de toegangssleutel op de Developer-pagina zodat deze niet meer kan worden gebruikt.
Probleemoplossing
| Je ziet | Wat te doen |
|---|---|
| "Plak eerst een sleutel." | Het sleutelveld is leeg. |
| "Ongeldige GitBook-toegangssleutel. Controleer en probeer het opnieuw." | De sleutel is onjuist of verwijderd. Maak een nieuwe aan en plak deze. |
| "Kon GitBook-toegangssleutel niet valideren." of "We konden die sleutel niet controleren. Probeer het opnieuw." | GitBook antwoordde niet. Probeer het over een moment opnieuw. |
| "Kies ten minste één site." | Vink ten minste één site aan vóór Verbinden. |
| "Geen GitBook-spaces of docs-sites gevonden en we konden er niet automatisch een aanmaken. Maak een space aan in GitBook en probeer het opnieuw." | Maak een space aan in GitBook en verbind dan opnieuw. |
| "Verbinding met GitBook mislukt. Controleer je toegangssleutel." | Controleer de sleutel en verbind opnieuw. |
| "Kon je GitBook-spaces niet laden. Probeer het opnieuw." | Klik op Opnieuw proberen. Als het blijft gebeuren, verbind GitBook opnieuw. |
| "Selecteer een space om naar te publiceren." | Kies eerst een space. |
| Een space ontbreekt in de lijst | Deze maakt geen deel uit van de gekozen sites, of de gebruiker van de sleutel kan deze niet zien. Verbind opnieuw en kies de site. |
| "GitBook heeft de pagina-inhoud geweigerd" of "GitBook kon het wijzigingsverzoek niet samenvoegen", met de reden van GitBook | De gebruiker van de sleutel kan die space niet bewerken, of GitBook heeft de wijziging geweigerd. Controleer de toegang in GitBook en klik dan op Opnieuw proberen. |
| "Toegangssleutel niet gevonden. Verbind GitBook opnieuw." | Verbind GitBook opnieuw met een sleutel. |
| "Artikelinhoud is leeg of ongeldig." | Het artikel heeft nog geen inhoud. Open het, controleer het en publiceer dan. |
| "De te vervangen pagina is niet gevonden in GitBook. Deze is mogelijk verplaatst of verwijderd." | Kies in plaats daarvan Nieuw artikel aanmaken. |
| "Publiceren naar GitBook mislukt. Probeer het opnieuw." of "Pagina in GitBook bijwerken mislukt. Probeer het opnieuw." | Klik op Opnieuw proberen. Als het blijft mislukken, verbind opnieuw met een nieuwe sleutel. |