Pubblica articoli su ReadMe
Connetti un progetto ReadMe con la sua Chiave API e pubblica gli articoli Clevera come Guide nella categoria che scegli, con screenshot caricati su ReadMe. Come vengono convertiti callout, passaggi e video, come funzionano gli aggiornamenti e gli errori comuni.
Pubblica un articolo Clevera come guida nel tuo progetto ReadMe, archiviato nella categoria di guide che scegli. Gli screenshot vengono caricati su ReadMe.
Prima di iniziare
- In Clevera: lo spazio di lavoro deve avere un piano Pro o Personalizzato e devi essere un proprietario o un amministratore per connettere ReadMe. Una volta connesso, chiunque possa modificare un articolo può pubblicarlo. Vedi Pubblica articoli sui tuoi altri strumenti.
- In ReadMe: un progetto che puoi gestire, con almeno una categoria nella sua sezione Guide. Una chiave connette un progetto.
- Un progetto ReadMe attuale: Clevera pubblica tramite l'API attuale (v2) di ReadMe, che ReadMe offre ai progetti su ReadMe Refactored. I progetti ancora sulla vecchia piattaforma di ReadMe non possono essere connessi.
- Versione: Clevera pubblica nella versione principale (stabile) delle Guide del tuo progetto.
- Un articolo: generalo prima. La pubblicazione invia solo l'articolo. Per includere un video, inseriscilo all'interno dell'articolo; vedi Mostra un video in un articolo.
Trova la tua Chiave API ReadMe
Nel tuo progetto ReadMe, apri Configuration → API Keys, quindi copia una chiave (creane una se l'elenco è vuoto). La chiave fornisce l'accesso completo a quel progetto, quindi tienila privata.
Connetti ReadMe
Apri la finestra di connessione
In Clevera, clicca sul nome del tuo spazio di lavoro nella barra laterale, scegli Integrazioni, trova ReadMe e clicca Connetti. La finestra Connetti ReadMe dice "Incolla una chiave. La controlliamo prima di salvare qualsiasi cosa."
Incolla e controlla la chiave
Incolla la chiave in Chiave API e clicca Controlla chiave. Quando ReadMe la accetta, vedrai "Chiave accettata." e il tuo progetto sotto Siti su cui pubblicare.
Connetti
Clicca Connetti. Vedrai "ReadMe connesso." e ReadMe apparirà sotto Connesso con il nome del tuo progetto.
La chiave non scade dal lato di Clevera. Per connettere un progetto diverso, usa Riconnetti sulla connessione ReadMe e incolla la chiave di quel progetto; sostituirà quella vecchia.
Pubblica un articolo su ReadMe
Apri la scheda Pubblica
Nell'editor, clicca Condividi → Pubblica e clicca il riquadro ReadMe sotto Pronto per la pubblicazione.
Scegli una categoria di guida
Sotto Dove va, Progetto mostra il progetto connesso. Scegli una Categoria di guida: "L'articolo va nella sezione Guide, sotto questa categoria." Se vedi "Nessuna categoria di guida ancora", creane una prima in ReadMe.
Pubblica
Clicca Pubblica su ReadMe. Clevera cerca prima una copia esistente; se esiste già una guida con lo stesso indirizzo, scegli cosa fare (vedi Aggiorna una guida). Quando ha finito, vedrai "Pubblicato su ReadMe." Clicca Apri in ReadMe per vedere la guida.
Puoi chiudere la finestra Condividi mentre è in esecuzione; una notifica ti avviserà quando ha finito.
L'indirizzo della guida deriva dal suo titolo: "Set up billing" diventa /docs/set-up-billing sul tuo sito di documentazione. I titoli in altri alfabeti o con accenti vengono traslitterati prima in lettere latine. Se l'indirizzo è già occupato, ReadMe assegna alla nuova guida uno leggermente diverso.
Come appare la guida in ReadMe
Il titolo della guida è il titolo dell'articolo. La guida contiene solo l'articolo: il video da cui proviene l'articolo non viene aggiunto.
| In Clevera | In ReadMe |
|---|---|
| Intestazioni, paragrafi | Intestazioni e testo |
| Grassetto, corsivo, barrato, codice inline, link | Mantenuti. I link ad altre pagine Clevera mantengono solo il loro testo. |
| Evidenziato, apice, pedice | Mantenuti |
| Elenchi puntati e numerati, checklist | Elenchi e checklist |
| Citazioni | Citazioni |
| Blocchi di codice | Blocchi di codice con il linguaggio e il titolo del codice |
| Separatori | Separatori |
| Tabelle | Tabelle con il testo di ogni cella |
| Callout | Callout di ReadMe con il titolo del callout: 📘 per info e nota, 👍 per suggerimento e successo, 🚧 per avviso, ❗️ per pericolo |
| Passaggi numerati | Un elenco numerato: il titolo di ogni passaggio in grassetto, il suo contenuto annidato sotto di esso |
| Schede | L'etichetta di ogni scheda in grassetto, seguita dal suo contenuto. Le schede che contengono solo codice diventano schede di codice ReadMe. |
| Sezioni comprimibili | Sezioni espandibili |
| Schede (Cards) | Un elenco di link con le loro descrizioni; le icone delle schede vengono omesse |
| Equazioni | Codice |
| Screenshot | Immagini caricate su ReadMe, con la didascalia in corsivo |
| Video e incorporamenti nell'articolo | Incorporamenti ReadMe. Un video Clevera è incluso solo quando il link di condivisione di quel video è attivo. |
Le parentesi graffe e angolari nel tuo testo vengono sottoposte a escape, quindi il formato della pagina di ReadMe le mostra come scritte.
Gli screenshot vengono caricati su ReadMe, quindi continuano a funzionare anche se elimini l'articolo in Clevera. Uno screenshot che non viene caricato, o un file video all'interno dell'articolo, rimane un link a Clevera che scade dopo un po'; pubblica di nuovo per rinnovarlo.
Aggiorna una guida
La pubblicazione è a senso unico. La guida non si aggiorna quando modifichi l'articolo in Clevera e le modifiche apportate in ReadMe non tornano mai in Clevera. Dopo aver modificato l'articolo, pubblicalo di nuovo.
Clevera cerca una guida con lo stesso indirizzo ovunque nelle tue Guide e mostra "Questo articolo è già in ReadMe." Clicca Visualizzalo per aprirlo, quindi scegli:
- Aggiorna l'articolo esistente sovrascrive quella guida: stesso indirizzo, nuovo titolo e contenuto. Clicca Aggiorna in ReadMe.
- Crea un nuovo articolo crea una nuova guida sotto il Nuovo titolo che inserisci, con il suo indirizzo. Clicca Crea nuovo articolo.
Le modifiche apportate in ReadMe dall'ultima pubblicazione vengono sovrascritte quando Clevera aggiorna una guida.
Disconnetti e revoca l'accesso
- In Clevera, apri Integrazioni, clicca ReadMe, quindi Disconnetti e conferma. Le guide che hai già pubblicato rimangono in ReadMe.
- In ReadMe, apri Configuration → API Keys ed elimina la chiave che hai dato a Clevera.
Risoluzione dei problemi
| Vedi | Cosa fare |
|---|---|
| "Incolla prima una chiave." | Il campo della chiave è vuoto. |
| "Chiave API non valida. Controlla la tua Chiave API ReadMe." | La chiave è errata o è stata eliminata. Copiala di nuovo da Configuration → API Keys. |
| "Impossibile recuperare le informazioni sul progetto da ReadMe." o "Non siamo riusciti a controllare quella chiave. Riprova." | ReadMe non ha risposto, o il progetto non è su ReadMe Refactored, che è necessario per Clevera. Riprova, quindi prova una nuova chiave; se il progetto è sulla vecchia piattaforma di ReadMe, non può essere connesso. |
| "Impossibile convalidare la Chiave API. Controlla la tua Chiave API ReadMe." o "Impossibile connettersi a ReadMe. Controlla la tua Chiave API." | Controlla la chiave e connettiti di nuovo. |
| "Nessuna categoria di guida ancora" / "Crea una categoria di guida in ReadMe per pubblicare qui." | Aggiungi una categoria alle tue Guide in ReadMe, quindi riapri la scheda Pubblica. |
| "Scegli prima una categoria." o "Scegli una categoria ReadMe in cui pubblicare questa guida." | Scegli una categoria di guida prima di pubblicare. |
| "Puoi visualizzare questo elemento ma non pubblicarlo. Chiedi a qualcuno che possa modificarlo." | Hai bisogno dell'accesso di modifica all'articolo per pubblicarlo. |
| "Chiave API non trovata. Riconnetti ReadMe." | Connetti di nuovo ReadMe con una chiave. |
| "Il contenuto dell'articolo è vuoto o non valido." | L'articolo non ha ancora contenuti. Aprilo, controllalo, quindi pubblica. |
| "Impossibile pubblicare su ReadMe" con un messaggio da ReadMe, come uno sullo slug o sulla categoria | ReadMe ha rifiutato la guida. Controlla che la categoria esista ancora, o rinomina l'articolo e clicca Riprova. |
| "Impossibile aggiornare la guida in ReadMe" | La guida che hai provato ad aggiornare è stata eliminata o rinominata in ReadMe. Pubblica di nuovo e scegli Crea un nuovo articolo. |
| "Impossibile pubblicare su ReadMe. Riprova." | Clicca Riprova. Se continua a fallire, connettiti di nuovo con una chiave nuova. |