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

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

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

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

Pero ¿por qué? ¿Por qué estamos creando un nuevo proyecto para generar documentación? Así que 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 cosas nuevas de código abierto. Y como mantenedor de código abierto, mi tiempo principal se ha gastado en mantener 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, y son implementados de manera diferente por diferentes personas, así que necesitamos una sola solución para nosotros mismos. Y ya hay muchas soluciones por ahí. ¿Por qué estamos creando una nueva? Así que primero, amamos next.js. Hay muchas personas ya familiarizadas con las APIs 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 puede ser bueno para la documentación también. ¿Por qué no simplemente usarlo? Y luego también tenemos algunas ideas nuevas para crear documentos, y queremos validar las ideas y iterarlas, e intentar construir algo increíble como producto. Y por último, puede ser algo más que documentación. Puede soportar más casos de uso como blogs y sitios web de portafolio también.

Así que aquí hay una vista rápida de Nextra. Así que 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 markdowns. Y lo bueno de Nextra es que puedes concentrarte simplemente en tu contenido, y no necesitas preocuparte por la arquitectura del sitio web y todo el compilador, las cosas del empaquetador. Nextra lo maneja por ti.

Y el mismo proyecto, cuando lo tienes en funcionamiento, puedes ver que el sitio web es básicamente el mismo 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 creas un nuevo archivo y escribes tu contenido. Puedes pasar la mayor parte de tu tiempo trabajando en el contenido tú mismo. Y obtienes un sitio web de buen aspecto.

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

Y se ve bastante bien, pero ¿qué más? Así que en primer lugar, el modo oscuro, ¿por qué no?, es algo que a todo el mundo le encanta. Y esto es algo más poderoso. Tiene una búsqueda de texto completo incorporada. No necesitas hacer nada. Solo escribes tu contenido, y obtienes una búsqueda de serie porque normalmente, tú necesitas configurar algún servicio y mantener un servidor y una API y haces un montón de cosas para ponerlo en marcha y luego lo tienes automáticamente sin escribir nada. Y se ve rápido, ¿verdad? No es speed up. Puedo mostrarte directamente. ¿Es rápido? Es muy rápido. Y puedes saltar a la posición directamente. Sí, básicamente lo obtienes gratis. Y como es MDX, puedes escribir código React dentro de tu contenido.

Y aquí tienes 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 esos clics. Puedes tener ambas sintaxis allí y también renderiza el estilo porque anteriormente no puedes tenerlos en cada nivel. Eso es lo bueno de la versión v2 y como está alimentado por Nexus porque Nexus y extra, obtienes un extra de poder de Nexus, como los enlaces normales de markdown pueden ser automáticamente convertidos a enlaces de Nexus. Eso significa que tienes la precarga de enlaces de serie y cuando pasas el ratón sobre un enlace, la página objetivo se precarga. Así que cuando haces clic en ella, es instantáneo. Y si solo estás escribiendo enlaces de markdown, cada clic resultará en una carga de página dura.

No obtienes experiencia SPA. Y también imágenes de markdown. Eso es algo difícil. Pero con Next.js, se convierte en imagen de Next.js automáticamente. Y Next.js tiene la optimización de imagen incorporada, que tiene dos cosas agradables. Una es que previene el cambio de diseño. Así que 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 será movido. Y eso es una mala experiencia. Otra cosa es, optimiza la imagen.

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

Así que 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 sea SSR'd cada vez porque es lento. No quieres que sea completamente estático, porque entonces el contenido no se actualiza. Y es complicado implementar eso por ti mismo porque es complicado. Tienes caché, revalidación, otras cosas. Next.js tiene un incorporado, ¿por qué no? Puedes tener eso en Next.js también. Y luego i18n y otras características de Next.js, CSS optimización, fuentes. Y puedes tener rutas JS normales también mezcladas con tu documentación. Así que es útil cuando estás, como, añadiendo documentación a tu proyecto de sitio web existente. Y tiene más características como el modo de vista previa, ruta de API, middleware, lo que quieras. Y este es un ejemplo de 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.

Así que puedes definir una función get static props 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 use SSG que pasa los props a tu componente como un contexto. Y luego puedes renderizarlo allí. Y podrías notar que hay un Revalidate16. Si estás familiarizado con Next.js, eso significa que cada minuto tu caché será invalidada. Y luego regenerarás eso estáticamente y lo almacenarás 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 fresco.

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

Así que tengo algunas vitrinas, donde nosotros y nuestra community, hicieron muchos sitios web de documentation basados en Next.jar. Uno es Minion.js. Se ve bien, ¿verdad? Porque básicamente puedes escribir cualquier React code allí, pero es un sitio de Next.jar, y obtienes búsqueda, y es muy rápido. Obtienes muchas características allí. Y el modo oscuro también, 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 documentation en un proyecto. Así que obtienes algún tipo de architecture de múltiples zonas allí. Están en el mismo proyecto de Next.js, impulsado por Next.js. Y luego puedes tener construcción de bloques también.

Y lo que escribes son básicamente solo archivos markdown, lo cual es increíble. Y tenemos a un miembro de la community, 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 de cada uno de los proyectos un sitio de documentation bajo el sitio web principal. Y todos son proyectos Nextra. Todos están anidados en la organización principal. Como puedes ver, la architecture puede ser muy, muy extensible. Y puedes hacer muchas cosas con ella. Y lo más importante es que es muy fácil de empezar. 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 aportar más ideas para mejorar tu user experience de tu sitio web de documentation sin hacer el proceso aburrido y complejo. Y si ya estás contento con Nextras, podrías querer probar Nextra para construir tus documentaciones.

Sí, y básicamente esa es mi charla. Y puedes probarlo. ¡Woo! ¡Woo! ¡Woo! ¡Woo! ¡Woo! ¡Woo! ¡Woo! ¡Woo! ¡Woo! Sí. ¿Quieres unirte a mí? Sí. Sí. Pasa al 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. Un par son sobre hipotéticos, uso, etc. Por ejemplo, ¿puede Extra reemplazar a Storybook para la documentación de la biblioteca de componentes, quizás? Sí, proporcionamos algunos componentes incorporados, como pestañas y algún componente de contenedor básico. Pero seguro que podemos hacer una vista previa de componentes y construir un editor, sí. Y de manera similar, ¿podría configurarse para otros casos de uso? Por ejemplo, parece que tiene todas las características para ser un generador de sitios de blogs increíble. Sí, mi blog personal probablemente también sea un Extra. Entonces, sí, es un buen caso de uso.

¿Dónde pueden encontrar eso las personas? Puedes encontrarlo en mi enlace de Twitter. Lo escuchaste aquí primero, gente. ¿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. Entonces, los componentes de React no serán indexados porque están usando código. Sí. Genial. ¿Nextra va a soportar la nueva carpeta de aplicaciones y los componentes del servidor de React? Lo estamos pensando. Pero es un gran cambio. Y de alguna manera se siente diferente que 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 están en conflicto entre sí. Entonces, 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 más fácil?

Ya está soportado. Puedes poner múltiples archivos con diferentes extensiones de los locales. Así, tendrás el cambio de idioma automáticamente. Yo recomendaría esa forma. Está en los docs.

Genial. Asombroso.

¿Qué forma recomiendas para trabajar en las fuentes de documentation de forma colaborativa?

Esa es una buena pregunta. Porque cuando estábamos diseñando inicialmente Nextra, queríamos que fuera un proyecto orientado a los sitios web de código abierto. Tenemos muchas características 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 llena la página y se etiqueta el problema con la etiqueta de comentarios, con la etiqueta de comentarios. Así que incluso si no tienes una API o database para almacenar esos comentarios de los usuarios, todas tus, todas tus secciones de documentation tendrán el enlace Crear Problema. Así que es muy fácil trabajar en eso en público. Y como cada página es sólo un simple archivo markdown. Así que es muy fácil para la gente contribuir.

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

Oh, esta es interesante. ¿Qué tan fácil es ahora, o será en el futuro, personalizar los Docs en términos de UI? ¿Qué tan personalizable?

Esa es una pregunta difícil. 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 sobrescribir todos los componentes existentes.

Pero dado que es un framework o tema con opiniones, no recomendamos que lo cambies. Así que solo muy ligeramente. Sí. Pero tiene una especie de ... todos serán muy reconocibles, supongo. Sí. Genial. Gracias por eso.

De manera similar a la UI, mostraste muchos sitios geniales en tu demostración. ¿Cómo configuras la barra de navegación / barra superior de los docs y las cosas que están alrededor de ella? Sí. Entonces, cuando tienes todos los archivos en el directorio, si quieres personalizar cuál debería ser colocado en la barra de navegación o la barra lateral, puedes tener un archivo meta.json en cualquier lugar de la carpeta de páginas. Y luego puedes simplemente especificar, bien, este archivo debe ser utilizado como una página en lugar de una sección en los docs. Así que, es un pequeño archivo json. Correcto. Nos encanta json. Gracias por eso.

Oh, genial. ¿Cuál es tu recomendación, y no sé si esto es posible, para combinar Nextra con documentación de API generada? Sí, esa es una buena pregunta. Esto está en realidad encima de Next.js, por lo que puedes tener SSR, SSG en todas partes. Entonces puedes obtener de tu fuente CMS en la función SSG, y sí, proporcionaremos más ejemplos sobre eso, pero es posible. Sí. ¿Eso significa que no es investigación indexada? Estamos trabajando en los docs, pero tenemos algunos proyectos trabajando de esa manera, pero no estamos documentando eso bien todavía. Bueno, tengo una gran herramienta que puedes usar para eso. ¿Soporta RTL, que supongo 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 RTL y la accessibility, por lo que pasamos mucho tiempo en eso. Todo el tema puede ser configurado para mostrar el idioma RTL y todo será volteado. Me encanta eso. ¿Debería ser desplegado en Vercel, o podemos auto-alojar? Puedes auto-alojar. Es Next. Puedes auto-alojar.

¡Poder para la gente! ¿Podría Nexture utilizarse para combinar la documentation y la vista en vivo de componentes para proyectos no-React? ¿Proyecto no-React? No creo que eso sea posible. Quizás puedes usar una caja de cosign o algo así, y luego puedes usar cualquier cosa. Eso podría ser bueno.

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

Sí, creo que estas son grandes herramientas, pero cuando estamos diseñando Next.js, nos gusta evitar el trabajo duplicado. Queremos que esté en la cima de Next.js, por lo que cada característica de Next.js estará en Next.js automáticamente, y luego podemos añadir algunas pequeñas innovaciones a la parte de la documentation en lugar de un servidor de desarrollo o compilador o cosas de bundler. Entonces, por ejemplo, las cosas que planeamos añadir, una es la generación de tarjetas sociales para cada página de Docs, por lo que cuando las compartes en las redes sociales, obtienes tarjetas bonitas. Y cosas como la búsqueda de búsqueda es algo que, hasta donde yo sé, el otro generador de Docs, no tienen. Necesitas configurarlo por ti mismo, al menos. Sí. Así que en parte es opinado, en parte se integra bien con el ecosystem, en parte podemos hacer lo que queremos, lo cual nos encanta. Sí. Genial.

Veamos si nos queda alguna de estas. Hablamos de auto-alojamiento. ¿Se planea alguna integración con Storybook o algo más? Todavía no, pero sí, podemos considerar que el primer hito es conseguir que sea estable y con todas las características y luego integrarlo en más APIs de back-end. Es posible ahora, pero queremos proporcionar la mejor user experience por lo que podemos optimizar para otros casos. Genial.

Ya estoy hinchado, déjame decirte. Ojalá tuviera más docs para escribir. Este es agradable. ¿next mientras todavía trabajas en otros proyectos de código abierto más pequeños? Vale. Así que ese es un problema común para los mantenedores de proyectos de código abierto. Así que la forma en que trabajo en las cosas es, normalmente cuando estás trabajando en un proyecto durante demasiado tiempo, te agotas muy fácilmente. Así que la forma en que trabajo en las cosas es cuando siento que estoy atascado en algo durante demasiado tiempo, quiero tener un proyecto diferente, totalmente diferente, para pensar en cosas diferentes y tal vez después pueda tener mejores ideas sobre el anterior y luego puedo volver a cambiar. Sí. Eso es genial. Así que de alguna manera se inspiran mutuamente. Sí, y puedo tomar un pequeño descanso 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 junto a la recepción si tienes más preguntas sobre Nextra. Muchas gracias por unirte a nosotros y compartir. Gracias. Gracias. Gracias.