Crear un sitio web de documentación

la documentación viene en muchas formas y formatos es posible que ya tengas algunos recursos o que 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 formatear el contenido según lo necesites para abrirlos, escribe una barra diagonal / en el editor y revisa las opciones los bloques están agrupados en básico , medios , desarrollador , incrustar , y reutilización de contenido por ejemplo, si deseas enlazar dinámicamente 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 llamar el nombre del bloque presiona / y escribe el nombre del bloque, por ejemplo, /verticalsplit , lo cual filtrará el bloque que deseas usar la tercera opción es usar paréntesis y el nombre del bloque, por ejemplo (api) — esto añadirá el bloque de endpoint api copiar pegar los hermanos clásicos de copiar y pegar ¿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 procesará, 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 mostrará 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 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 supongamos que estás usando 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 sincronizar un repositorio de github sucede que la documentación está escrita en un repositorio de github, y puedes continuar 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 configurar 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 agregar tu dominio personalizado hay múltiples opciones disponibles en la pestaña general puedes desactivar la opción indexable por motores de búsqueda (si es pública) desde la misma configuración del espacio a menudo querrás tener esto 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 ninguna 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 enlace mágico introduces correos electrónicos específicos o permites dominios 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 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 configurarla es una opción perfecta si no quieres que los usuarios inicien sesión cada vez comienza a crear páginas antes de escribir cualquier documentación, considera los temas principales que cubrirás esta vez un bolígrafo y papel podrían 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, estará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; así es como lo hicimos en nuestra guía de usuario y desarrollador comenzando editor documentos espacios espacios alojados organizaciones importar y exportar integraciones guías api pública misceláneo cuando comienzas a añadir contenido, es esencial tener un flujo de trabajo aquí tienes uno posible, aunque podrías querer adaptarlo comienza 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 notifica a un compañero que el documento está listo y necesita revisarlo si es necesario, agrega comentarios en línea donde se requiera la aportación de otros usuarios cuando estés conforme con los cambios, publica para previsualizar y 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 empieza a crear documentos con la estructura que tus documentos necesitan también puedes introducir los bloques personalizados que un autor utilizará o añadir ejemplos de otras fuentes enlaces permanentes y configuraciones de seo estas opciones están a nivel del documento así que debes hacer clic en los tres puntos ⋮ en la parte superior derecha y seleccionar 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 el sitio web de tu documentación en la apariencia encontrarás las opciones de marca 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 productos dependiendo del tipo de productos o servicios, es posible que desees tener diferentes rutas de url de espacios puedes tener un espacio como la 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 complétalos con la ruta correspondiente 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 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, 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 para inspirarte y, si deseas cambiar el aspecto y la sensación de la primera página, esta es tu opción aquí tienes 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 deseas 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 usarlos como objetivo