Home Artículos técnicos El Nuevo Layer0 (Edgio) Docs es el comienzo de un Nuevo Comienzo
Applications

El Nuevo Layer0 (Edgio) Docs es el comienzo de un Nuevo Comienzo

About The Author

Outline

El cambio es inevitable, y de vez en cuando viene. En los últimos años hay cambios que se nos han impuesto, 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 completa y rediseño 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 habíamos hecho antes. Y así, fuertemente inspirados por los documentos beta de React, nos pusimos sobre los hombros de los gigantes creando una instancia del repositorio base y afinándolo para nuestro caso de uso específico.‍

Lo primero es lo primero

El primer paso fue el canal Reactiflux Discord. En pocas palabras, la comunidad ayudó a identificar el repositorio de documentación beta del React.

El repo beta de 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 tenía razón 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: Paquete de módulos
  • Componentes estilizados: Styling
  • 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 permitirte incrustar JSX en cualquier documento 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 Ingredient y 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 esta entrada del blog. Hay un par de enfoques para obtener markdown en las páginas de Next.js, como tener un documento de markdown local y transformarlo en HTML usando 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 tratar con el contenido de nivel inferior, sigue el enfoque de equipo de React y DIY.

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 de páginas y cargarlas como páginas Next.js.

WebPack utiliza cargadores para preprocesar archivos. Uno de los casos de uso más comunes es la transpilación y uno de estos paquetes comunes es babel-loader (carga código ES2015+ y transpilas a ES5 usando Babel). Para cargar archivos `.mdx` con Webpack en Next.js, se utiliza @mdx-js/loader.

El rico ecosistema de plugins de remark/rehype puede ser llamado para ayuda 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 Styled Components, podemos crear estilos de componentes de una manera más colocada, modular, acoplada y menos intrusiva. Aprenda cómo usar componentes con estilo en React o explore el camino feliz de componentes con estilo para obtener más información sobre 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 la capacidad de respuesta para ofrecer 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 al 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 rico ecosistema de plugins, y es extensible con valores predeterminados sensibles para operaciones como la tematización.

Características

Mientras que el rediseño presenta un cambio en gran medida cosmético a 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.

Tematización

Cambiar entre temas es solo un clic de botón de distancia. Vaya del modo de luz al modo oscuro o viceversa o deje que su sistema operativo decida.

Navegación mejorada

Los dos modos principales de navegación (menú (a la izquierda) y tabla de contenido (a la derecha) se han rediseñado 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.

Códigos 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 sobre qué contenido se indexa para los resultados. Esto también funciona en dispositivos móviles.

Pero espera, hay más

El repo de React beta docs tiene mucho que hacer para él, y hemos sido capaces de aprovechar el poder del código abierto aquí. Hay algunas cosas que obtenemos casi fuera de la caja, como tabla-de-contenidos, paginación de documentos, breadcrumbs, SEO etc. Algunos de estos hemos modificado para servir mejor a nuestro contexto, y algunos todavía 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 continuamos ayudándote a hacer que tus sitios web sean más rápidos y seguros sin comprometer la experiencia del desarrollador. El código fuente de los documentos de desarrollador de Layer0 se encuentra en un repositorio abierto en GitHub y damos la bienvenida a los comentarios y solicitudes de extracción. Si has encontrado un error tipográfico o una mejor manera de explicar algo, ¡envía una solicitud de extracción o presenta un problema! Además, vea nuestras directrices de contribución.