Nextra 2.0: Crea un sitio de documentación completo en 5 minutos

Gracias, es un placer estar aquí. Así que siguiente disparo. Bonito logo, ¿verdad? Sí.

Permítanme presentarme primero. Mi nombre es Szu-Din, y he estado trabajando en proyectos de código abierto durante casi nueve años. Pasé cuatro años en Versailles, y allí hice tanto trabajo de diseño como de ingeniería. Y actualmente estoy trabajando en Next.js, y anteriormente creé bibliotecas como SWR y Satori, y ese es mi nombre de usuario de Twitter si quieres contactarme.

Y hoy voy a hablar de un proyecto llamado Next.js. Es una herramienta para generar sitios web de documentación completos en minutos. Es muy fácil de usar. Y puede generar sitios de documentación muy elegantes o fáciles de usar, y también impulsa muchos de nuestros proyectos internos o de código abierto.

Pero, ¿por qué? ¿Por qué estamos creando un nuevo proyecto para generar documentación? Primero, tanto Vercell como yo tenemos demasiados proyectos para mantener, como cada par de meses, tenemos un nuevo proyecto en el que trabajar. Tenemos un nuevo experimento o nuevas cosas de código abierto. Y como mantenedor de código abierto, la mayor parte de mi tiempo lo he pasado manteniendo la documentación. Y es realmente importante para nuestros usuarios y para la comunidad. Pero cada vez que creamos un sitio de documentación ad hoc, se implementan de manera diferente por diferentes personas, así que necesitamos una solución única para nosotros. Y ya hay muchas soluciones disponibles. ¿Por qué estamos creando una nueva? En primer lugar, amamos next.js. Muchas personas ya están familiarizadas con las API de next.js, y es súper poderoso. Es una base sólida y está bien mantenido. Así que no queremos aprender una nueva herramienta para generar nuestros sitios, porque next.js también puede ser bueno para la documentación. ¿Por qué no usarlo? Y luego también tenemos algunas ideas nuevas para crear documentación, y queremos validar las ideas y mejorarlas, y tratar de construir algo increíble como producto. Y por último, puede ser más que documentación. También puede admitir casos de uso como blogs y sitios web de cartera.

Así que aquí tienes un vistazo rápido de Nextra. Es solo un proyecto normal de Next.js si ya estás familiarizado con él. Tienes una carpeta de páginas, y en lugar de archivos JavaScript, solo tienes una lista de archivos markdown MDX. Y puedes anidarlos en carpetas y nombrarlos, y son solo archivos markdown. Y lo bueno de Nextra es que puedes centrarte en tu contenido y no tienes que preocuparte por la arquitectura del sitio web y todo el compilador, el empaquetador, etc. Nextra se encarga de eso por ti.

Y el mismo proyecto, cuando lo tienes en funcionamiento, puedes ver el sitio web básicamente igual que la estructura de tu sistema de archivos. Y como puedes ver, tus páginas coinciden exactamente con la barra lateral de tu sitio web. Así que no necesitas configurar nada. Solo tienes que crear un nuevo archivo y escribir tu contenido. Puedes pasar la mayor parte de tu tiempo trabajando en el contenido tú mismo. Y obtienes un sitio web con un aspecto agradable.

Y hay más cosas que eso, como la tabla de contenidos. Se genera automáticamente en función de tu archivo. Y esa es la primera impresión del proyecto. Es fácil de configurar porque solo tienes que crear archivos. Y luego puedes centrarte en el contenido. Y es intuitivo gestionar las rutas porque normalmente necesitas crear alguna configuración compleja como especificar esas páginas, rutas, carpetas y directorios, y ahora solo necesitas mantener el sistema de archivos, las carpetas.

Y se ve bastante bien, pero ¿qué más? Primero que nada, el modo oscuro, ¿por qué no?, es algo que a todos les encanta. Y esto es algo más poderoso. Tiene una búsqueda de texto completo incorporada. No necesitas hacer nada. Solo escribe tu contenido y obtendrás una búsqueda lista para usar porque normalmente, necesitas configurar algún servicio y mantener un servidor y una API y hacer un montón de cosas para ponerlo en funcionamiento y aquí lo tienes automáticamente sin escribir nada. Y se ve rápido, ¿verdad? No está acelerado. Puedo mostrártelo directamente. ¿Es rápido? Es muy rápido. Y puedes ir directamente a la posición. Sí, obtienes eso de forma gratuita básicamente. Y como es MDX, puedes escribir código React dentro de tu contenido.

Y aquí hay un elemento de encabezado dos, hola MDX, y puedes simplemente poner un componente React dentro. En la versión v2 de MDX, puedes tener markdowns dentro de tus componentes, como ese clic. Puedes tener ambas sintaxis allí y también se renderiza el estilo porque anteriormente no podías hacerlo en todos los niveles. Eso es algo bueno de la versión v2 y como está impulsado por Nexus porque Nexus y extra, obtienes poder adicional de Nexus, como la conversión automática de enlaces markdown a enlaces de Nexus. Eso significa que tienes precarga de enlaces lista para usar y cuando pasas el cursor sobre un enlace, la página de destino se precarga. Así que cuando haces clic en él, es instantáneo. Y si solo estás escribiendo enlaces markdown, cada clic resultará en una carga de página completa.

No obtienes una experiencia de SPA. Y también las imágenes de markdown. Eso es algo complicado. Pero con Next.js, se convierten automáticamente en imágenes de Next.js. Y Next.js tiene la optimización de imágenes incorporada, lo cual tiene dos ventajas. Una es que evita cambios en el diseño. Entonces, cuando estás cargando la página, tu contenido no se empuja hacia arriba o hacia abajo, porque la imagen no se carga inicialmente. Y luego, cuando se carga, tu contenido se moverá. Y eso es una mala experiencia. Otra cosa es que optimiza la imagen.

Y cuando estás cargando la página inicialmente, ves un marcador de posición borroso allí. Y luego el contenido completo se carga más tarde. Lo cual es agradable. Y hay mucho más que esto. Porque Next.js es un framework con muchas características diferentes, algunas son poderosas, algunas son cosas pequeñas y agradables.

Entonces, una cosa importante aquí es SSG, SSR e ISR. Porque normalmente no escribes todo como archivos estáticos. A veces quieres que el contenido sea un poco dinámico. Digamos que tengo una página que muestra cuántas estrellas tiene mi proyecto en GitHub. Y no quieres que eso se renderice en el servidor cada vez porque es lento. No quieres que sea completamente estático, porque entonces el contenido no se actualiza. Y es complicado implementarlo por ti mismo porque es complicado. Tienes caché, revalidación, entre otras cosas. Next.js lo tiene incorporado, ¿por qué no usarlo? También puedes tener eso en Next.js. Y luego i18n y otras características de Next.js, optimización de CSS, fuentes. Y también puedes tener rutas JS normales mezcladas con tu documentación. Es útil cuando estás agregando documentación a tu proyecto de sitio web existente. Y tiene más características como el modo de vista previa, rutas de API, middleware, lo que necesites. Y este es un ejemplo de cómo hacer ISR, regeneración estática incremental, en MDX con Next.js. Así que parece un archivo JavaScript, pero en realidad es un archivo MDX.

Entonces puedes definir una función getStaticProps aquí, que obtiene la API de GitHub para saber cuántas estrellas tienen tus proyectos. Y luego defines un componente que renderiza los data. Hay un hook useSSG que pasa las props a tu componente como un contexto. Y luego puedes renderizarlo allí. Y puedes notar que hay un Revalidate16. Si estás familiarizado con Next.js, eso significa que tu caché se invalidará cada minuto. Y luego se regenerará estáticamente y se almacenará en caché en el servidor. Así que cada carga de página es rápida, es instantánea, porque es estática. Y cada 60 segundos se regenera. Así que el número siempre está actualizado, siempre es fresco.

Y tengo un ejemplo. Así se ve, es una página estática. Y cada vez que el número se actualiza... Nadie lo ha iniciado aún. Sí. Pero, ¿ves? Se actualiza. Y esas son solo algunas características generales, pero hay muchas más. Básicamente puedes combinar todas las características de Next.js con Next.jar. El tema y el diseño de la documentación en sí mismo también son muy ampliables.

Así que tengo algunos ejemplos, donde nosotros y nuestra comunidad, hemos creado muchos sitios web de documentación elegantes basados en Next.jar. Uno de ellos es Minion.js. Se ve bien, ¿verdad? Porque básicamente puedes escribir cualquier código React allí, pero es un sitio Next.jar, y obtienes búsqueda, y es muy rápido. Obtienes muchas características allí. Y también el modo oscuro se ve bien. Y Turbo, el sitio web de Turbo es un poco más complicado. Tiene proyectos Turbo Repo y Turbo Pack. Así que puedes tener múltiples documentaciones en un solo proyecto. Obtienes algún tipo de arquitectura de múltiples zonas allí. Están en el mismo proyecto Next.js, impulsado por Next.js. Y también puedes tener construcción de bloques.

Y lo que escribes son básicamente solo archivos markdown, lo cual es increíble. Y tenemos un miembro de la comunidad, The Good. Están haciendo algo aún más sofisticado. Son un ecosistema de muchos proyectos de código abierto. Y muchas empresas hacen eso. Tienes muchos proyectos, muchas cosas que mantener. Y hacen que cada uno de los proyectos sea un sitio de documentación dentro del sitio web principal. Y todos son proyectos de Nextra. Todos están anidados en la organización principal. Como puedes ver, la arquitectura puede ser muy, muy personalizable. Y puedes hacer muchas cosas con ella. Y lo más importante es que es muy fácil comenzar. Y hoy estamos lanzando la versión V2 de Nextra, que tiene muchas cosas buenas incorporadas. Y sí, esa es una de nuestras regiones. Nuestra visión es traer más ideas para mejorar la experiencia del usuario de tu documentación sitio web sin que el proceso sea aburrido y complejo. Y si ya estás satisfecho con Nextras, es posible que desees probar Nextra para construir tus documentaciones.

Sí, y esa es básicamente mi charla. Y puedes probarlo. ¡Woo! ¡Woo! ¡Woo! ¡Woo! ¡Woo! ¡Woo! ¡Woo! ¡Woo! ¡Woo! Sí. ¿Quieres unirte a mí? Sí. Sí. Siéntate en el asiento caliente. Gracias por esa charla. Fue genial. Siento que aprendí mucho. Ahora quiero ir a escribir cosas.

Ya tenemos algunas preguntas para ti, así que eso es genial. Algunas son sobre hipotéticos, uso, etc. Por ejemplo, ¿Extra puede reemplazar a Storybook para la documentación de la biblioteca de componentes, tal vez? Sí, proporcionamos algunos componentes integrados, como pestañas y algunos componentes de contenedor básicos. Pero definitivamente podemos crear una vista previa de componentes y un editor, sí. Y de manera similar, en la misma línea, ¿se puede configurar para otros casos de uso? Por ejemplo, parece que tiene todas las características para ser un increíble generador de sitios de blogs. Sí, mi blog personal también es probablemente un Extra. Así que sí, es un buen caso de uso.

¿Dónde pueden encontrarlo las personas? Puedes encontrarlo en el enlace de mi Twitter. Lo escuchaste aquí primero, amigos. ¿Cómo interactúan los componentes de React con la búsqueda incorporada? ¿Aparece su contenido? Entonces, la búsqueda solo indexa el contenido de markdown. Por lo tanto, los componentes de React no se indexarán porque utilizan código. Sí. Genial. ¿Nextra va a admitir la nueva carpeta de aplicaciones y los componentes del servidor de React? Estamos pensando en ello. Pero es un cambio importante. Y de alguna manera se siente diferente a mantener un directorio de contenido. Es más como una cosa de aplicación anidada. Pero lo bueno es que puedes usar páginas y aplicaciones al mismo tiempo. No entran en conflicto entre sí. Así que sí.

Genial. Me encanta el futuro de cómo todas las cosas se mezclan. Estoy seguro de que algún día todo será muy interdependiente. ¿Recomiendas algo para el soporte de localización con Nextra, o es la forma incorporada un poco más fácil?

Ya está soportado. Puedes colocar varios archivos con diferentes extensiones para los idiomas. Así, tendrás el cambio de idioma automáticamente. Recomendaría esa forma. Está en la documentación.

Genial. Increíble.

¿Qué forma recomiendas para trabajar en las fuentes de documentación de manera colaborativa?

Esa es una buena pregunta. Porque cuando estábamos diseñando inicialmente Nextra, queríamos que fuera un proyecto orientado a sitios web de código abierto. Tenemos muchas funciones incorporadas, como en cada página, tienes el enlace de proporcionar comentarios. Y cuando haces clic en ese enlace, se abre la página de problemas de GitHub y automáticamente se rellena la página y etiqueta el problema con la etiqueta de comentarios. Entonces, incluso si no tienes una API o base de datos para almacenar esos comentarios de los usuarios, todas tus, todas tus secciones de documentación tendrán el enlace de Crear Problema. Así que es muy fácil trabajar en eso en público. Y como cada página es solo un archivo markdown simple. Es muy fácil para que las personas contribuyan.

Sí. Creo que es muy amigable con GitHub. Sí. De hecho, tenemos un amigo de la comunidad que dijo que después de cambiar a Nexra y hacer que los archivos markdown sean más limpios porque antes era algo mezclado con una configuración de encabezados y ahora son solo archivos markdown simples, muy limpios y bien estructurados. En realidad, recibieron más solicitudes de extracción para contribuir a los documentos, lo cual es muy agradable. Sí. Me encanta eso. Las contribuciones a la documentación son muy importantes.

Oh, esto es interesante. ¿Qué tan fácil es ahora, o será en el futuro, personalizar la interfaz de usuario de los documentos? ¿Qué tan personalizable?

Esa es una pregunta complicada. De hecho, tenemos una forma de permitirte configurar el color principal, el color del tema del sitio web. Pero sí, siempre puedes proporcionar el CSS para anular todos los componentes existentes.

Pero dado que es un marco o tema con opiniones, no recomendamos que lo cambies. Así que solo muy ligeramente. Sí. Pero será muy reconocible, supongo. Sí. Genial. Gracias por eso.

Siguiendo la misma línea de la interfaz de usuario, mostraste muchos sitios geniales en tu demostración. ¿Cómo configuras la barra de navegación o barra superior de la documentación y las cosas que la rodean? Sí. Entonces, cuando tienes todos los archivos en el directorio, si quieres personalizar qué se debe colocar en la barra de navegación o la barra lateral, puedes tener un archivo meta.json en todas partes en la carpeta de páginas. Y luego simplemente puedes especificar, okay, este archivo debe usarse como una página en lugar de una sección en la documentación. Es un pequeño archivo json. Correcto. Amamos json. Gracias por eso.

Oh, genial. ¿Cuál es tu recomendación, y no sé si esto es posible, para combinar Nextra con la generación de documentación de API? Sí, esa es una buena pregunta. Esto se basa en Next.js, por lo que puedes tener SSR, SSG en todas partes. Entonces puedes obtener datos de tu fuente CMS en la función SSG, y sí, proporcionaremos más ejemplos al respecto, pero es posible. Sí. ¿Eso significa que no está indexado en la investigación? Estamos trabajando en la documentación, pero tenemos algunos proyectos que funcionan de esa manera, pero aún no lo documentamos bien. Bueno, tengo una gran herramienta que puedes usar para eso. ¿Admite RTL, que supongo que es la biblioteca de pruebas de React y no de derecha a izquierda? No uses acrónimos. La respuesta es sí. Nos tomamos muy en serio el RTL y la accesibilidad, así que dedicamos mucho tiempo a eso. Se puede configurar todo el tema para mostrar el idioma RTL y todo se volteará. Me encanta eso. ¿Debería implementarse en Vercel, o podemos autohospedarnos? Puedes autohospedarte. Es Next. Puedes autohospedarte.

¡Poder para la gente! ¿Se podría utilizar Nexture para combinar la documentación y la vista en vivo de componentes para proyectos no-React? ¿Proyecto no-React? No creo que eso sea posible. Tal vez puedas usar una caja de cosignación o algo así, y luego puedes usar cualquier cosa. Eso podría ser bueno.

Hay un par de preguntas en la cola que son como, ¿cómo lo ves diferente de algunas de las alternativas, como DocuSource o un sitio de documentación personalizado de Gatsby? ¿Hay algo que quieras compartir? Sé que estas preguntas siempre son difíciles.

Sí, creo que estas son herramientas geniales, pero cuando estamos diseñando Next.js, nos gusta evitar el trabajo duplicado. Queremos que esté por encima de Next.js, por lo que todas las características de Next.js estarán en Next.js automáticamente, y luego podemos agregar algunas pequeñas innovaciones a la parte de documentación en lugar de un servidor de desarrollo o un compilador o cosas de bundler. Por ejemplo, cosas que planeamos agregar, una es la generación de tarjetas sociales para cada página de Docs, para que cuando las compartas en las redes sociales, obtengas tarjetas agradables. Y cosas como la búsqueda, es algo que, hasta donde sé, el otro generador de Docs no tiene. Necesitas configurarlo tú mismo, al menos. Sí. Parte opinión, parte se integra bien con el ecosistema, parte podemos hacer lo que queramos, lo cual nos encanta. Sí. Genial.

Déjame ver si nos queda alguna de estas. Hablamos sobre la autohospedaje. ¿Hay alguna integración planificada con Storybook u otra cosa? Aún no, pero sí, podemos considerarlo. El primer hito es que sea estable y tenga todas las funciones y luego integrarlo con más API de backend. Ahora es posible, pero queremos brindar la mejor experiencia de usuario para poder optimizar para otros casos. Genial.

Ya estoy lleno, déjame decirte. Ojalá tuviera más documentación para escribir. Esta es buena. ¿Continuar trabajando en otros proyectos de código abierto más pequeños mientras trabajas en otros o en Next.js? Vale. Ese es un problema común para los mantenedores de proyectos de código abierto. La forma en que trabajo en las cosas es que, por lo general, cuando trabajas en un proyecto durante mucho tiempo, te agotas muy fácilmente. Entonces, la forma en que trabajo en las cosas es que cuando siento que estoy atascado en algo durante mucho tiempo, me gusta tener un proyecto diferente, completamente diferente, para pensar en cosas diferentes y tal vez después pueda tener mejores ideas sobre el proyecto anterior y luego puedo volver a cambiar. Sí. Eso es genial. Así se inspiran mutuamente de alguna manera. Sí, y puedo descansar un poco para pensar en cosas diferentes. Sí. Fresco en la mente. Sí. Muy bien. Bueno, ese es todo el tiempo que tenemos para preguntas aquí, pero Xu estará en la sala de preguntas y respuestas del orador cerca de la recepción si tienes más preguntas sobre Nextra. Muchas gracias por unirte y compartir. Gracias. Gracias. Gracias.