Crear un sitio web de documentación

la documentación viene en muchas formas y formatos puede que ya tengas algunos recursos o necesites empezar desde cero veamos cómo agregar contenido con archbee e scribe en archbee una vez que creas un nuevo documento, puedes comenzar a agregar contenido usando ya sea atajos de markdown o cualquiera de los más de 30 bloques personalizados los bloques personalizados te ayudan a dar formato al contenido como lo necesites para abrirlos, escribe una barra inclinada / en el editor y revisa las opciones los bloques se agrupan bajo básico , medios , desarrollador , incrustar , y reutilización de contenido por ejemplo, si quieres enlazar dinámicamente a otros documentos, escribe @ y el título del documento esto se conectará al id del documento si cambias el título o la posición del documento, el enlace siempre apuntará a él otro ejemplo es llamar el nombre del bloque pulsa / y escribe el nombre del bloque, por ejemplo, /verticalsplit , lo que filtrará el bloque que quieres usar la tercera opción es usar paréntesis y el nombre del bloque — por ejemplo (api) — lo cual agregará el bloque de endpoint api copiar pegar los hermanos del copiar y pegar de la vieja escuela ¿pero por qué cubrir este? como el editor de archbee admite markdown, si deseas pegar en este formato, podrías recibir el siguiente mensaje hemos detectado contenido markdown en tu portapapeles ¿estás intentando pegar markdown? si haces clic en el botón cancelar, el contenido no se representará, y si haces clic en aceptar en el cuadro de diálogo, convertiremos el markdown en bloques de archbee así que tienes un ejemplo de código que se representará como un bloque de editor de código en archbee importar archivos markdown o word copiar y pegar funciona perfectamente, pero si tienes archivos markdown o word, ¿por qué no importarlos a un espacio? antes de importar cualquier contenido, asegúrate de hacer clic en el espacio donde deseas importar los archivos acabas de hacer clic en el tipo de archivo que tienes y has ahorrado minutos de copiar y pegar desde otras fuentes importar archivos openapi/swagger o colecciones de postman cuando se trata de documentar apis, tienes múltiples opciones digamos que estás utilizando el estándar openapi (anteriormente swagger) esto permite una fácil importación y sincronización de los archivos una vez importado en archbee, el contenido se mostrará en un diseño de 3 columnas que permite una documentación fácil de gestionar sincronizar un repositorio de github ocurre que la documentación está escrita en un repositorio de github, y puedes seguir escribiendo en github y sincronizar el repositorio con un espacio de archbee el beneficio es que puedes publicar ese espacio en tu dominio personalizado y añadir otros espacios con información adicional, como referencias de api configura el dominio personalizado y el control de acceso antes de comenzar con el contenido, da un pequeño paso que marcará la diferencia más adelante configura tu subdominio para tener acceso a los entornos de vista previa y producción ve a la página de documentación https //docs archbee com/hosting spaces on a custom domain y sigue los pasos para añadir tu dominio personalizado múltiples opciones están disponibles en la pestaña general puedes desactivar la opción indexable por motores de búsqueda (si es público) desde la misma configuración del espacio a menudo quieres mantenerlo activado para que los usuarios encuentren tu sitio en la página de resultados del motor de búsqueda puedes ir a la opción de control de acceso público y elegir cualquiera de las cinco opciones para obtener más control ninguno hace exactamente lo que su nombre indica, mantiene tu configuración respecto al espacio público contraseña establece una contraseña para el espacio todos los que tengan el enlace y la contraseña podrán leer el contenido cuentas de invitado crea cuentas de invitado todos los que tengan el enlace y una cuenta de invitado pueden leer el contenido las cuentas de invitado no se cobran como asientos en archbee magic link introduces correos electrónicos específicos o permites dominios completos, y los usuarios se autentican usando un enlace que enviamos a su dirección de correo electrónico; autenticación jwt consulta la página de documentación https //docs archbee io/authentication options? hstc=59513074 901e138137246d5bde4ccdbd22c4c426 1657529807386 1664186053341 1664199496535 118& hssc=59513074 7 1664199496535& hsfp=13091307 para saber cómo configurarlo es una opción perfecta si no quieres que los usuarios inicien sesión cada vez comienza a construir páginas antes de escribir cualquier documentación, considera los temas principales que cubrirás esta vez un bolígrafo y papel pueden ayudarte a dibujar la estructura luego, crea un documento, conviértelo en una categoría y asígnale un nombre una vez que tengas esto, estarás listo para agregar documentos bajo cada categoría comienza con un documento que presente las cosas principales que un usuario encontrará en el sitio de documentación no tiene que ser complicado; así es como lo hicimos en nuestra guía de usuario y desarrollador primeros pasos editor documentos espacios espacios alojados organizaciones importar y exportar integraciones guías api pública varios cuando empiezas a añadir contenido, es esencial tener un flujo de trabajo aquí tienes uno posible, pero es posible que quieras adaptarlo inicia el borrador en documentos personales esto te ayudará a escribir cualquier cosa que aún no quieras compartir con el equipo cuando esté listo, muévelo al espacio avisa a un compañero que el documento está listo y necesita revisarlo si corresponde, agrega comentarios en línea donde se requiera la opinión de otros usuarios cuando estés conforme con los cambios, publícalo en vista previa para ver el sitio de pruebas si todo se ve bien, presiona publicar en producción y anuncia que todo está en vivo trabajar con plantillas facilita que los colaboradores comiencen a escribir contenido puedes guardar un conjunto de plantillas para ayudarte a iniciar la producción de contenido si necesitas inspiración, cuando crees un nuevo documento, verás un botón llamado comenzar con una plantilla en la parte inferior de la página para crear tus propias plantillas, ve a la navegación en el lado izquierdo, plantillas, y comienza a crear documentos con la estructura que tus documentos necesitan también puedes introducir los bloques personalizados que un autor utilizará o agregar ejemplos de otras fuentes enlaces permanentes y configuración de seo estas opciones están a nivel de documento así que debes hacer clic en los tres puntos ⋮ en la parte superior derecha y elegir controles de meta seo agrega un título relevante, cambia la url , escribe una meta descripción o sube una imagen para las vistas previas marca y personaliza tu sitio web de documentación en la pestaña apariencia , encontrarás las opciones de personalización como color de acento , logo , y favicon , junto con otras opciones para la plantilla crea un menú de navegación con múltiples productos o versiones de producto dependiendo del tipo de productos o servicios, es posible que quieras tener diferentes rutas de url para los espacios puedes tener un espacio como documentación principal y crear diferentes espacios para otros productos o incluso para sus versiones ¡hay un atajo! puedes crear un clon de cualquier espacio si los cambios son incrementales esto te ayudará a mantener la estructura y hacer las ediciones para la nueva versión así que, si necesitas versionado y múltiples productos, utiliza diferentes espacios y añádeles la ruta relevante o un dominio personalizado ir a enlaces de espacio https //docs archbee com/space links y comienza a construir tu navegación crea una página de inicio el objetivo principal de la página de inicio es ayudar al visitante a ir a la siguiente página crear una página de aterrizaje para tu sitio web de documentación no tiene que seguir las mismas prácticas que un sitio web de presentación la primera página del documento es importante para presentar tu producto o servicio a los usuarios, así que mantenerla breve y establecer expectativas ayuda mucho puedes usar la página de inicio personalizada https //docs archbee io/custom landing page? hstc=59513074 901e138137246d5bde4ccdbd22c4c426 1657529807386 1664186053341 1664199496535 118& hssc=59513074 7 1664199496535& hsfp=13091307 y agregar tu propio html para tener más control sobre la primera página hay muchas opciones de las cuales obtener inspiración, y si deseas cambiar el aspecto y la sensación de la primera página, esta es tu opción aquí se muestra cómo uno de nuestros clientes construyó su página inicial para su página de ayuda agregar código personalizado usa css personalizado https //docs archbee io/custom css? hstc=59513074 901e138137246d5bde4ccdbd22c4c426 1657529807386 1664186053341 1664199496535 118& hssc=59513074 7 1664199496535& hsfp=13091307 si quieres agregar tu propio \<font color="#a855f7">toque\</font> al sitio de documentación si estás familiarizado con las clases css, encontrarás algunos puntos de partida y podrás apuntar a ellos