Publicar artículos en GitBook
Conecta GitBook con una clave de acceso personal y publica artículos de Clevera como páginas en tus espacios de GitBook. Dónde crear la clave, cómo elegir sitios, cómo se convierten las sugerencias, los pasos y las pestañas, qué hace la actualización y errores comunes.
Publica un artículo de Clevera como una página en un espacio de GitBook. GitBook se conecta con una clave de acceso personal en lugar de un inicio de sesión, y la página aparece en el nivel superior del espacio que elijas.
Antes de empezar
- En Clevera: el espacio de trabajo debe estar en el plan Pro o Personalizado, y debes ser propietario o administrador para conectar GitBook. Una vez conectado, cualquier persona que pueda editar un artículo puede publicarlo. Consulta Publicar artículos en tus otras herramientas.
- En GitBook: cualquier plan. La clave actúa como el usuario de GitBook que la creó, por lo que esa persona necesita acceso de edición a los espacios donde publiques.
- Un artículo: genéralo primero. La publicación envía solo el artículo. Para incluir un video, colócalo dentro del artículo; consulta Mostrar un video en un artículo.
Crear una clave de acceso de GitBook
- En GitBook, abre la configuración de tu cuenta y ve a Developer (
app.gitbook.com/account/developer). - Crea un nuevo token de acceso personal, asígnale un nombre como "Clevera" y cópialo. GitBook solo lo muestra una vez.
Conectar GitBook
Abrir la ventana de conexión
En Clevera, haz clic en el nombre de tu espacio de trabajo en la barra lateral, elige Integraciones, busca GitBook y haz clic en Conectar. La ventana Conectar GitBook dice "Pega una clave. La verificaremos antes de guardar nada." y contiene un enlace Open GitBook a la página de desarrollador.
Pegar y verificar la clave
Pega la clave en Clave de acceso y haz clic en Verificar clave. Cuando GitBook la acepte, verás "Clave aceptada."
Elegir los sitios
En Sitios donde publicar, Clevera enumera tus sitios de documentación (o espacios) y los selecciona todos. Abre la lista para desmarcar los que no quieras, por ejemplo "2 de 3 seleccionados", y luego haz clic en Conectar. Verás "GitBook conectado."
Clevera verifica la clave antes de guardar nada.
Si tu cuenta de GitBook no tiene ningún espacio, Clevera creará uno llamado "Clevera" en tu primera organización para que puedas publicar de inmediato.
La clave no caduca por parte de Clevera. Para cambiar la clave o los sitios, abre el menú ⋯ en la conexión de GitBook, elige Reconectar y sigue los pasos en la misma ventana; la nueva clave y la nueva selección reemplazarán a las anteriores.
Publicar un artículo en GitBook
Abrir la pestaña Publicar
En el editor, haz clic en Compartir → Publicar y haz clic en el mosaico de GitBook en Listo para publicar.
Elegir un espacio
En Dónde se publica, la lista muestra los espacios detrás de los sitios que elegiste, con sus iconos.
Publicar
Haz clic en Publicar en GitBook. Clevera busca primero una copia existente; si ya hay una página con el mismo título en el espacio, elige qué hacer (consulta Actualizar una página que publicaste). Cuando termine, verás "Publicado en GitBook." Haz clic en Open in GitBook para ver la página.
Puedes cerrar la ventana Compartir mientras se realiza el proceso; una notificación te avisará cuando termine.
La página se añade en el nivel superior del espacio y su dirección proviene del título: "Set up billing" se convierte en /set-up-billing. Los títulos en otros alfabetos o con acentos se escriben primero en letras latinas; un título sin caracteres para transcribir obtiene un código corto fijo. Mueve o cambia el nombre de la página en GitBook después si lo deseas.
Cómo se ve la página en GitBook
El título de la página es el título del artículo. La página contiene solo el artículo: el video del que proviene el artículo no se añade.
| En Clevera | En GitBook |
|---|---|
| Encabezados, párrafos | Encabezados y texto |
| Negrita, cursiva, tachado, código en línea, enlaces | Se mantienen |
| Resaltado, superíndice, subíndice | Se mantienen |
| Listas con viñetas y numeradas, listas de tareas | Listas y listas de tareas |
| Citas | Citas |
| Bloques de código | Bloques de código con el lenguaje y el título del código |
| Divisores | Divisores |
| Tablas | Tablas con el texto de cada celda |
| Callouts | Bloques de sugerencias: info → Info, note → Info, tip → Success, success → Success, warning → Warning, danger → Danger |
| Pasos numerados | Un paso a paso de GitBook, un paso por cada paso |
| Pestañas | Pestañas de GitBook |
| Secciones plegables | Bloques expandibles |
| Tarjetas | Una lista de enlaces con sus descripciones; los iconos de las tarjetas se omiten |
| Ecuaciones | Matemáticas de GitBook |
| Capturas de pantalla | Imágenes subidas al espacio, con el pie de foto |
| Videos e incrustaciones en el artículo | Bloques de incrustación. Un video de Clevera solo se incluye cuando el enlace para compartir de ese video está activado. |
Las capturas de pantalla se suben al espacio como archivos, por lo que siguen funcionando incluso si eliminas el artículo en Clevera. Un archivo de video subido al artículo sigue siendo un enlace a Clevera que caduca después de un tiempo; publícalo de nuevo para renovarlo.
Actualizar una página que publicaste
La publicación es unidireccional. La página de GitBook no se actualiza cuando editas el artículo en Clevera, y las ediciones realizadas en GitBook nunca regresan a Clevera. Después de editar el artículo, publícalo de nuevo en el mismo espacio. Clevera busca una página con el mismo título (las mayúsculas no importan) o la misma dirección y muestra "Este artículo ya está en GitBook."
- Actualizar el artículo existente sobrescribe el contenido y el título de esa página. La dirección se mantiene igual. Los cambios realizados en GitBook desde entonces se sobrescriben; el historial de GitBook te permite recuperarlos. Haz clic en Actualizar en GitBook.
- Crear un nuevo artículo añade una segunda página bajo el Nuevo título que ingreses (Clevera sugiere uno como "Set up billing (2)"), con su propia dirección. Haz clic en Crear nuevo artículo.
Desconectar y revocar el acceso
- En Clevera, abre Integraciones, haz clic en GitBook, luego en Desconectar y confirma. Las páginas que ya publicaste permanecen en GitBook.
- En GitBook, elimina la clave de acceso en la página Developer para que no pueda volver a utilizarse.
Solución de problemas
| Ves | Qué hacer |
|---|---|
| "Pega una clave primero." | El campo de clave está vacío. |
| "Clave de acceso de GitBook no válida. Por favor, verifica e inténtalo de nuevo." | La clave es incorrecta o fue eliminada. Crea una nueva y pégala. |
| "Error al validar la clave de acceso de GitBook." o "No pudimos verificar esa clave. Inténtalo de nuevo." | GitBook no respondió. Inténtalo de nuevo en un momento. |
| "Elige al menos un sitio." | Marca al menos un sitio antes de Conectar. |
| "No se encontraron espacios o sitios de documentación de GitBook, y no pudimos crear uno automáticamente. Por favor, crea un espacio en GitBook e inténtalo de nuevo." | Crea un espacio en GitBook y luego conéctate de nuevo. |
| "Error al conectar con GitBook. Por favor, verifica tu clave de acceso." | Verifica la clave y conéctate de nuevo. |
| "No se pudieron cargar tus espacios de GitBook. Por favor, inténtalo de nuevo." | Haz clic en Inténtalo de nuevo. Si se repite, reconecta GitBook. |
| "Por favor, selecciona un espacio donde publicar." | Elige un espacio primero. |
| Falta un espacio en la lista | No forma parte de los sitios que elegiste, o el usuario de la clave no puede verlo. Reconecta y elige el sitio. |
| "GitBook rechazó el contenido de la página" o "GitBook no pudo fusionar la solicitud de cambio", con el motivo de GitBook | El usuario de la clave no puede editar ese espacio, o GitBook rechazó el cambio. Verifica el acceso en GitBook y luego haz clic en Inténtalo de nuevo. |
| "Clave de acceso no encontrada. Por favor, reconecta GitBook." | Reconecta GitBook con una clave. |
| "El contenido del artículo está vacío o no es válido." | El artículo aún no tiene contenido. Ábrelo, revísalo y luego publícalo. |
| "No se encontró la página a reemplazar en GitBook. Puede que se haya movido o eliminado." | Elige Crear un nuevo artículo en su lugar. |
| "Error al publicar en GitBook. Por favor, inténtalo de nuevo." o "Error al actualizar la página en GitBook. Por favor, inténtalo de nuevo." | Haz clic en Inténtalo de nuevo. Si sigue fallando, reconecta con una clave nueva. |