Crear un sitio web de documentación

la documentación viene en muchas formas y formatos es posible que ya tengas algunos recursos o necesites empezar desde cero cubramos cómo agregar contenido con archbee es cribir en archbee una vez que creas un nuevo documento, puedes comenzar a agregar contenido usando ya sea atajos de markdown o cualquiera de los 30+ bloques personalizados los bloques personalizados te ayudan a formatear el contenido como lo necesites para abrirlos, escribe una barra diagonal / en el editor y revisa las opciones los bloques están agrupados bajo básico , medios , desarrollador , incrustar , y reutilización de contenido por ejemplo, si deseas vincular dinámicamente a otros documentos, escribe @ y el título del documento esto conectará con el id del documento si cambias el título o la posición del documento, el enlace siempre apuntará a él otro ejemplo es mencionar el nombre del bloque presiona / y escribe el nombre del bloque, por ejemplo, /verticalsplit , lo que filtrará el bloque que deseas usar la tercera opción es usar paréntesis, y el nombre del bloque por ejemplo, (api) añadirá el bloque de punto final de la api copiar pegar los hermanos de copiar y pegar a la antigua pero, ¿por qué cubrir este? dado que 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 de cancelar, el contenido no se renderizará, 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 renderizará como un bloque de editor de código en archbee importar archivos markdown o word copiar y pegar funciona muy bien, 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 solo hiciste clic en el tipo de archivo que tienes y ahorraste minutos de copiar y pegar de 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 a archbee, el contenido se mostrará en un diseño de 3 columnas que permite una documentación fácil de gestionar sincroniza un repositorio de github sucede 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 agregar 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 tarde configura tu subdominio para tener acceso a los entornos de vista previa y producción ve a la https //docs archbee com/hosting spaces on a custom domain y sigue los pasos para agregar tu dominio personalizado se encuentran disponibles múltiples opciones en la general pestaña puedes desactivar el indexable por motores de búsqueda (si es público) desde la misma configuración del espacio a menudo querrás que esto esté 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 tener más control ninguno hace exactamente lo que dice el nombre, mantiene tus configuraciones respecto al espacio público contraseña establece una contraseña para el espacio todos con el enlace y la contraseña podrán leer el contenido cuentas de invitado crea cuentas de invitado todos con el enlace y una cuenta de invitado pueden leer el contenido las cuentas de invitado no se cuentan como asientos en archbee enlace mágico introduces correos electrónicos específicos o permites nombres de dominio completos, y los usuarios se autenticarán usando un enlace que enviamos a su dirección de correo electrónico; autenticación jwt consulta la 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 a continuación, crea un documento, conviértelo en una categoría y dale un nombre una vez que tengas esto, estás listo para agregar documentos bajo cada categoría comienza con un documento que introduzca las principales cosas que un usuario encontrará en el sitio de documentación no tiene que ser complicado; aquí está cómo lo hicimos en nuestro guía de usuario y desarrollador comenzando editor documentos espacios espacios alojados organizaciones importar y exportar integraciones guías api pública varios cuando comienzas a agregar contenido, es esencial tener un flujo de trabajo aquí hay uno potencial, pero es posible que desees adaptarlo comienza el borrador en documentos personales esto te ayudará a escribir cualquier cosa que no quieras compartir con el equipo aún cuando estés listo, mueve esto al público espacio informa a un compañero de equipo que el documento está listo y necesita revisarlo si hay alguno, agrega comentarios en línea donde se requiera la entrada de otros usuarios después de que te sientas cómodo con los cambios, publica para vista previa para ver el sitio de staging 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 creas un nuevo documento, verás un botón llamado comenzar con una plantilla en la parte inferior de la página para construir 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 presentar los bloques personalizados que un autor estará utilizando o agregar ejemplos de otras fuentes enlaces permanentes y configuraciones de seo estas opciones están a nivel de documento así que necesitas hacer clic en los tres puntos ⋮ en la parte superior derecha y seleccionar controles meta de seo agrega un título , cambia la url , escribe una descripción meta o sube una imagen para las vistas previas marca y personaliza tu sitio web de documentos en la apariencia pestaña, encontrarás las opciones de agrupamiento como color de acento , logo , y favicon , junto con otras opciones para la plantilla crea un menú de navegación con versiones multiproducto o de producto dependiendo del tipo de productos o servicios, es posible que desees tener diferentes rutas de url de espacio puedes tener un espacio como los documentos principales y crear diferentes espacios para otros productos o incluso versiones de ellos ¡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 el versionado y multiproducto es algo que necesitas, utiliza diferentes espacios y añádelo con la ruta relevante o dominio personalizado ir a https //docs archbee com/space links y comienza a construir tu navegación crea una página de aterrizaje el objetivo principal de la página de inicio es ayudar al visitante a ir a la siguiente página construir 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, por lo que mantenerla breve y establecer expectativas es muy útil puedes usar la https //docs archbee io/custom landing page? hstc=59513074 901e138137246d5bde4ccdbd22c4c426 1657529807386 1664186053341 1664199496535 118& hssc=59513074 7 1664199496535& hsfp=13091307 y agregar tu html para tener más control sobre la primera página hay muchas opciones para inspirarse, y si deseas cambiar el aspecto y la sensación de la primera página, esta es tu opción aquí está cómo uno de nuestros clientes construyó su página de inicio para su página de ayuda agregar código personalizado usa https //docs archbee io/custom css? hstc=59513074 901e138137246d5bde4ccdbd22c4c426 1657529807386 1664186053341 1664199496535 118& hssc=59513074 7 1664199496535& hsfp=13091307 si deseas agregar tu propio sabor sabor al sitio de documentación si estás familiarizado con las clases css, encontrarás algunos ab iniciales y podrás apuntar a ellos