Muy buenas, soy Luis y para hoy les traigo este nuevo artículo.
Índice
Una breve guía sobre cómo crear y lanzar sus propios complementos para Docusaurus v2
Hemos estado usando Docusaurus v2 para nuestro sitio web. Después de un par de meses de usarlo, podemos decir con confianza que estamos muy contentos con nuestra elección.
Docusaurus viene con baterías incluidas, por lo que obtienes mucho valor de inmediato, mientras que es lo suficientemente flexible como para adaptarlo a tus necesidades si hay algo que te gusta de manera diferente. Además, su documentación es excelente, como cabría esperar de un marco que debe su existencia a su capacidad para crear sitios web de documentación.
Docu-¿qué?
Para cualquiera que no esté familiarizado con Docusaurus, Docusaurus es un marco de código abierto creado por Facebook para crear sitios web de documentación para todas sus herramientas de código abierto. Si ha estado trabajando en algunos proyectos de NodeJS, es probable que haya utilizado documentación generada por Docusaurus, solo por nombrar algunos ejemplos: Broma, Crear aplicación Reacty Redux.
Ahora Facebook está trabajando en la próxima versión de Docusaurus, llamada Docusaurus v2. Lo que lo convierte en un generador de sitios estáticos de alto rendimiento para crear rápidamente todo tipo de sitios web. El soporte para la documentación sigue siendo un ciudadano de primera clase, pero ahora puede usarlo para crear lo que desee. Oficialmente todavía está en alfa, pero según nuestra experiencia ya es muy estable y se animan nuevos proyectos de Facebook para adoptar Docusaurus v2.
¿Por qué necesitaría complementos?
La razón principal por la que existen complementos en el ecosistema Docusaurus es la reutilización. Hay muchos bits de código que tienen un propósito genérico, con complementos puede compartir estos bits de código entre estos proyectos. Docusaurus usa complementos para separar la lógica para crear blogs o páginas de documentación del núcleo Docusaurus. Los complementos también se pueden utilizar para agregar funcionalidades que no están directamente orientadas al usuario, por ejemplo, existen complementos oficiales para optimizar imágenes, agregar Google Analytics o crear mapas de sitio.
Los complementos oficiales son muy útiles, pero es posible que no satisfagan su caso de uso. En nuestro caso, utilizamos un proveedor de análisis diferente al de Google Analytics. Los complementos son muy útiles aquí, ya que puede usarlos para inyectar el código de seguimiento en cada página generada.
El proceso
Primero repasemos el proceso de creación de su propio complemento, luego los repasaremos paso a paso para profundizar en cada uno de ellos. Para el contexto, seguiremos nuestro proceso de agregar análisis de GoatCounter a nuestra documentación, que ahora vive en docusaurus-plugin-goatcounter a npm. Puede resultar útil consultar el código fuente de los complementos oficiales como inspiración sobre cómo implementar un complemento que se ajuste a su caso de uso. Usamos el ‘@ docusaurus / plugin-google-analytics’ como nuestro punto de partida.
- Prototipo localmente: Docusaurus le permite crear un complemento en el mismo código fuente que su proyecto actual. Esto le permite experimentar y obtener resultados muy rápidamente.
- Mover el complemento a una base de código separada: Inicie un nuevo proyecto donde vivirá el código base de su complemento Docusaurus.
- Publica tu complemento: Por último, publicaremos su complemento en NPM, de modo que ahora pueda incluirlo en todos sus proyectos.
1. Creación de prototipos a nivel local
La documentación de Docusaurus v2 cubre brevemente cómo crear complementos. Esas instrucciones tienen como objetivo la creación de un nuevo complemento directamente en su proyecto actual. Descubrimos que esto reduce enormemente la barrera de entrada y permite una experimentación rápida. Si está creando un plugin grande, entonces es posible que desee omitir este paso y comenzar a construir desde una base de código separada, ya que eso también le dará sugerencias de tipo ya que agregaremos TypeScript.
Este es el compromiso completo que agrega nuestra versión inicial para análisis de GoatCounter a nuestro proyecto. Aquí usaremos una versión ligeramente simplificada, de modo que podamos centrarnos en la funcionalidad principal. Para cualquiera que no esté familiarizado con GoatCounter, necesitamos el complemento para agregar el siguiente HTML a cada página:
Primero crea plugins/goatcounter/index.js y agregue el siguiente contenido:
Ahora en docusaurus.config.js agregue su complemento:
const path = require('path')
module.exports = {
// ...
themeConfig: {
// ...
goatcounter: {
code: 'MYCODE',
},
},
plugins: [path.resolve(__dirname, 'plugins', 'goatcounter')],
};
Reinicie Docusaurus y ahora todas las páginas deberían tener sus análisis incluidos en el HTML 🎉.
2. Creación de un complemento independiente
Tener el complemento en la misma base de código que su sitio web Docusaurus puede ser fácil para la creación de prototipos. Sin embargo, no permite reutilizar esta lógica. Además, es posible que su sitio web Docusaurus no esté usando TypeScript, que podemos agregar a nuestro proyecto de complemento para tener sugerencias de tipo para nuestro complemento.
Para arrancar nuestro proyecto vamos a utilizar TSDX, configura un paquete completo de desarrollo de TypeScript para nosotros.
npx tsdx create docusaurus-plugin-goatcounter
Luego agregue los tipos de Docusaurus. Definimos explícitamente la función deseada, ya que la etiqueta ‘más reciente’ no se mantiene actualizada. Ver npm para la última versión.
yarn add --dev @docusaurus/types@2.0.0-alpha.65
Ahora puede copiar el contenido de plugins/goatcounter/index.js y colocarlo en src/index.ts de su nuevo proyecto.
Dado que estamos migrando de JS simple a TypeScript, necesitamos algunas modificaciones menores. Reemplazar esto de plugins/goatcounter/index.js:
Con esto en src/index.ts:
Para probar su complemento, ejecute yarn build && yarn link en el directorio de su complemento recién creado. Luego, en su proyecto Docusaurus, ejecute yarn link docusaurus-plugin-goatcounter y modificar docusaurus.config.js para importar el complemento como un paquete, en lugar del archivo:
module.exports = {
// ...
// plugins: [path.resolve(__dirname, 'plugins', 'goatcounter')],
plugins: ['docusaurus-plugin-goatcounter'],
};
3. Publica tu complemento
Publicar su complemento es tan simple como ejecutar npm publish y siguiendo los pasos que da.
Si anteriormente vinculó su complemento a su proyecto Docusaurus, primero debe ejecutar yarn unlink docusaurus-plugin-goatcounter en su proyecto Docusaurus. Luego puede agregar su dependencia desde npm:
yarn add docusaurus-plugin-goatcounter
Reinicie Docusaurus y ahora está utilizando su complemento Docusaurus independiente recién creado 🥳.
Solución de problemas
¿Algo que no está claro? Consulte el código fuente del enchufar y un Proyecto Docusaurus utilizando el complemento.
¿Disfrutaste este artículo? Si es así, espero tu comentario.
Añadir comentario