El cambio es inevitable, y de vez en cuando viene alrededor. En los últimos años hay cambios que nos han sido forzados, cambios sobre los que no teníamos control directo. Pero en Layer0/Edgio, el cambio reciente es uno de nuestros propios hechos, uno que era muy necesario: Una reescritura y rediseño completos de la documentación de Edgio.
Esta revisión estaba destinada a ser fundamental y controlable. La verdad es que queríamos tomar el asunto en nuestras propias manos como nunca lo hemos hecho antes. Y así, fuertemente inspirados por los documentos beta de React, nos pusimos en marcha sobre los hombros de los gigantes creando una instancia del repositorio base y afinándola para nuestro caso de uso específico.
Lo primero es lo primero
El primer paso fue el canal de discordia Reactiflux. En pocas palabras, la comunidad ayudó a identificar el repositorio de documentación beta de React.
El repositorio beta React como un head-start
Pasamos un par de días investigando cómo se había construido el sitio beta de React Docs, qué tecnologías utiliza y cómo podemos aprovechar y construir sobre esta pila para satisfacer nuestras necesidades específicas. Nuestra corazonada sobre MDX y next.js estaba en lo cierto y nos encontramos con una ventaja.
Tecnologías
Estas son algunas de las principales tecnologías utilizadas:
- MDX: Marcado funcional con componentes React integrados
- Next.js: React framework
- Webpack: Módulo bundler
- Componentes estilizados: Estilismo
- Algolia: Búsqueda
- Prism: Resaltado de sintaxis de código
MDX: MDX es una forma extendida de Markdown para la era de componentes. Hace que el markdown sea funcional al permitirle incrustar JSX en cualquier documento de markdown, llevando la creación de contenido con markdown a un nuevo nivel.
Ya sabíamos lo que era MDX y lo poderoso que puede ser de artículos como MDX, The Secret Ingrediente and Front-End Documentation, Style Guides y The Rise of MDX. Esto allanó el camino para algunos de los componentes personalizados que creamos.
Next.js: Emparejar MDX con Next.js no es algo nuevo, así que el primer instinto fue leer la documentación oficial o este post del blog. Hay un par de enfoques para introducir markdown en las páginas next.js, como tener un documento de markdown local y transformarlo en HTML utilizando paquetes como Remark y Remark-html dentro de uno de getStaticProps, getStaticPaths o getServerSideProps
Otro enfoque es definir un archivo `.md` o `.mdx` directamente como páginas next.js con el paquete @next/mdx, o si te gusta lidiar con las cosas de nivel inferior, sigue el enfoque del equipo de React y el bricolaje.
Webpack: Next.config.js (o next.config.mjs) es utilizado por el servidor next.js y las fases de compilación. Aquí es donde puede configurar next.js para casos de uso avanzados, como dejar que markdown lea extensiones de archivo `.mdx` en el directorio Pages y cargarlas como páginas next.js.
Webpack utiliza cargadores para preprocesar archivos. Uno de los casos de uso más comunes es transpilar y uno de estos paquetes comunes es babel-loader (carga código ES2015+ y transpila a ES5 usando Babel). Para cargar archivos `.mdx` con Webpack en next.js, se usa @mdx-js/loader.
El rico ecosistema de plugins de remark/rehype puede ser solicitado por @mdx-js/loader para una transformación de grano fino de markdown a html.
Componentes con estilo: Si bien hay una gran cantidad de formas de escribir CSS en next.js, elegimos componentes con estilo. Con los componentes estilizados, podemos crear estilos de componentes de una manera más colocada, modular, acoplada y menos intrusiva. Aprenda a usar los componentes con estilo en React o explore la ruta Happy de los componentes con estilo para obtener más información sobre los componentes con estilo.
Algolia: Hemos actualizado a la última versión de DocSearch v3, que se basa en Algolia Autocomplete, proporcionando mejoras en la accesibilidad y capacidad de respuesta, lo que brinda una experiencia más fluida tanto en dispositivos de escritorio como móviles. Junto con eso está el Algolia Crawler para extraer la información más relevante a la hora de realizar su búsqueda.
Prism: Prism es el resaltador de sintaxis de código bien probado y confiable. No solo es más fácil comenzar, también tiene un ecosistema de plugins enriquecido, y es extensible con valores predeterminados sensibles para operaciones como la temática.
Características
Mientras que el rediseño presenta un cambio en gran medida cosmético a su valor nominal, hay otras características tales como:
Una nueva página de inicio con detalles importantes
Comience con los cuatro pilares de la plataforma Layer0 / Edgio y construya su camino hacia arriba y en más características que Layer0 / Edgio tiene para ofrecer.
Temática
Cambiar entre temas está a solo un clic de botón de distancia. Vaya del modo luz al modo oscuro o viceversa o deje que su sistema operativo decida.
Navegación mejorada
Los dos modos de navegación principales —menú (a la izquierda) y tabla de contenido (a la derecha)— han sido rediseñados para mejorar la navegación y el escaneo. Un nuevo control de paginación (en la parte inferior) le ayuda a saber qué guía es la siguiente y cuál viene antes.
Codeblocks mejorados
Con PrismJS, el resaltado de sintaxis y la personalización son muy simples.
Búsqueda mejorada
La búsqueda de Algolia se ha actualizado a v3, lo que nos da mucho más control de qué contenido se indexa para obtener resultados. Esto también funciona en dispositivos móviles.
Pero espera, hay más
El repositorio de React beta docs tiene mucho que hacer para ello, y hemos sido capaces de aprovechar el poder del código abierto aquí. Hay algunas cosas que casi sacamos de la caja, como la tabla de contenidos, la paginación de documentos, las migas de pan, SEO, etc. Algunas de ellas las hemos modificado para servir mejor a nuestro contexto, y otras aún las estamos explorando.
Contribución
Para nosotros esta es la nueva documentación, es un paso en la dirección correcta y el comienzo de un nuevo comienzo. Queremos que te unas a nosotros en este viaje mientras seguimos ayudándote a hacer que tus sitios web sean más rápidos y seguros sin comprometer la experiencia de los desarrolladores. El código fuente para los documentos de desarrolladores de Layer0 está en un repositorio abierto en GitHub y damos la bienvenida a las solicitudes de retroalimentación y extracción. Si ha encontrado un error tipográfico o una mejor manera de explicar algo, por favor envíe una solicitud de pull o presente un problema! Además, vea nuestras pautas de contribución.
