Para sitios web ligeros, aplicaciones y otros proyectos pequeños, cada vez más desarrolladores recurren a los generadores de sitios estáticos en lugar de WordPress u otros sistemas de gestión de contenidos (CMS). Los sitios estáticos ofrecen una forma sencilla y eficaz de crear sitios web y aplicaciones que son rápidos, seguros y fáciles de mantener.
Docusaurus es uno de esos generadores de sitios estáticos — y está ganando popularidad rápidamente en la comunidad de desarrolladores.
En este post, profundizaremos en los beneficios de usar Docusaurs como tu generador de sitios estáticos y por qué es uno de los favoritos de los desarrolladores.
¿Qué Es Docusaurus?
Docusaurus es un popular generador de sitios estáticos que utiliza React, una de las principales bibliotecas de JavaScript, como biblioteca de interfaz de usuario para la creación de páginas. Al igual que otros generadores de este tipo, es fácil de configurar y de modificar y, lo que es más importante, te proporciona todo lo que necesitas para poner en marcha tu sitio web estático.
Sin embargo, lo que diferencia a Docusaurus es que te ayuda a crear y gestionar un sitio web en el que el contenido desempeña un papel clave. Te permite crear rápida y fácilmente un sitio web completo — con función de blog — que destaque tu contenido desde el primer momento.
Como el contenido es el centro de atención con Docusaurus, es perfecto para crear sitios de documentación como wikis. También utiliza markdown, que es ideal tanto para la colaboración como para el almacenamiento en un repositorio git. Además, tiene un montón de funciones increíbles como i18n, búsqueda y temas personalizados, de las que hablaremos con más detalle más adelante.
Éstas son solo algunas de las características destacadas que hacen de Docusaurus una opción sólida:
- Construido con React
- Compatible con MDX v1
- Compatible con la incrustación de componentes React a través de Markdown
- Versionado de documentos
- Compatibilidad con Git, Crowdin y otros gestores de traducción para la traducción de documentos y el despliegue masivo o individual
¿Quién Utiliza Docusaurus?
Docusaurus fue creado por Facebook, así que no es de extrañar que actualmente lo utilicen muchas grandes marcas y empresas de toda la web.
Estas son sólo algunas de las empresas más importantes que utilizan Docusaurus en la actualidad (y pronto habrá más, ya que la popularidad de Docusaurus sigue creciendo):
Y cada día se suman más.
Cómo Instalar Docusaurus
Docusaurus es muy sencillo de instalar y solo requiere unos minutos. En este tutorial, construiremos un sitio de documentación con un blog, y personalizaremos el aspecto del sitio web.
Y aquí viene lo mejor: Tardaremos menos de una hora en ponerlo todo en marcha.
¡Manos a la obra!
Requisitos
Docusarus requiere Node.js 16.14 o posterior. Es un SSG de archivo plano, lo que significa que no necesitarás una base de datos adicional.
Si aún no tienes disponible Node js 16.14+, tendrás que empezar por instalar Node.js o actualizar tu versión actual. Después puedes pasar al proceso de instalación de Docusaurus que se indica a continuación.
También vamos a utilizar el sitio Docusaurus de ejemplo de este repositorio de GitHub. Puedes utilizarlo o hacer una instalación limpia de Docusaurus para este tutorial.
Proceso de Instalación
Para comenzar el proceso de instalación de Docusaurus, primero tienes que ejecutar el siguiente comando:
npx create-docusaurus@latest classicEsto creará una carpeta para tu proyecto y colocará el tema classic dentro de ella. El tema classic ya contiene algunas características preconfiguradas como un blog, páginas personalizadas y un framework CSS.
Tras la instalación, deberás ejecutar el siguiente comando para iniciar el servidor local:
npm startSi quieres crear una versión optimizada que esté lista para su despliegue, debes ejecutar esto en su lugar:
npm run buildEstructura
Una vez que hayas instalado tu instancia de Docusaurus, podrás abrir el directorio de tu proyecto y echar un vistazo más de cerca al «esqueleto» de tu nuevo sitio.
Este es el aspecto de la estructura de archivos:
my-website
├── blog
│ ├── 2019-05-28-hola.md
│ └── 2020-05-30-welcome.md
├── docs
│ ├── doc1.md
│ └── mdx.md
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── styles.module.css
│ └── index.js
├── static
│ └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lockHay algunos detalles a tener en cuenta en relación con algunos de estos archivos y carpetas:
/blog: Contiene todos los archivos relacionados con tu blog./docs: Contiene todos los archivos relacionados con tus documentos. Puedes personalizar su orden en el archivo sidebar.js./src: Contiene todos los archivos no relacionados con la documentación, como páginas o componentes personalizados./src/pages: Todos los archivos JSX/TSX/MDX se transformarán en páginas./static: Archivos estáticos que se copiarán en la carpeta de construcción final.docusaurus.config.js: Archivo de configuración de Docusaurus.packaged.json: Cada sitio Docusaurus es una aplicación React, por lo que aquí encontrarás todas las dependencias y scripts que utiliza para React.sidebar.js: Aquí puedes especificar el orden de los documentos en la barra lateral.
Personalizar Tu Instalación de Docusaurus
Como puedes ver por la simplicidad de su estructura de archivos, Docusaurus es fácil de usar y navegar. Del mismo modo, personalizar tu sitio Docusaurus es pan comido. Puedes abrir y editar estos archivos con tu editor de texto o IDE favorito.
Repasemos algunas de las opciones de personalización que tendrás desde el principio.
Página de Inicio
Lo primero que probablemente estarás deseando hacer es personalizar la página de inicio predeterminada para que muestre tu propio proyecto. Por suerte, no es complicado hacer los cambios que quieras en la página de inicio de Docusaurus.
Para modificar la página de inicio, abre el archivo src/pages/index.js y realiza los ajustes allí mismo. Es una página React típica, así que puedes alterarla o reconstruirla cambiando el contenido o creando componentes React personalizados.
Archivo de Configuración
A continuación, nos sumergiremos en el crucial archivo docusaurus.config.js y cambiaremos algunos detalles importantes para nuestra instancia.
Nombre y Descripción
En el archivo de configuración, encontrarás:
const config = {
title: 'My Site',
tagline: 'Dinosaurs are cool',
url: 'https://your-docusaurus-site.com',
baseUrl: '/',Cambia estos detalles para adaptarlos a las necesidades de tu sitio y, a continuación, guarda el archivo.
Barra de Navegación
Para editar tu barra de navegación, localiza el elemento navbar.
Para nuestro ejemplo, queremos añadir un enlace a Kinsta, cambiar el nombre del elemento «Tutorial» a «Documentación para principiantes» y añadir el logotipo de Kinsta.
Así es como lo haríamos:
navbar: {
title: 'Kinsta starters',
logo: {
alt: 'Kinsta Logo',
src: 'img/kinsta-logo-alpha-purple.png',
},
items: [
{
label: 'Kinsta starters',
to: '/docs/intro',
},
{to: '/blog', label: 'Blog', position: 'left'},
{
href: 'https://github.com/kinsta',
label: 'GitHub',
position: 'right',
},
],
},Pie de Página
La personalización del pie de página en Docusaurus se compone de dos secciones: el contenido del pie de página propiamente dicho y los enlaces del pie de página.
Contenido del Pie de Página
La mayor parte del contenido de tu pie de página (sin incluir la lista de enlaces) puede colocarse en tu archivo themeConfig.footer. Este es el lugar ideal para añadir un logotipo y un aviso de copyright.
Así es como hemos modificado la configuración de nuestro pie de página:
module.exports = {
themeConfig: {
footer: {
logo: {
alt: 'Kinsta Logo',
src: 'img/kinsta-logo.png',
href: 'https://kinsta.com',
width: 160,
height: 51,
},
copyright: `Copyright © ${new Date().getFullYear()} Kinsta. Built with Docusaurus.`,
},
},
};Enlaces del Pie de Página
Cambiar los enlaces del pie de página es similar a cambiar la barra de navegación superior: Busca la sección footer en docusaurus.config.js y edítala hasta que se ajuste a tus necesidades.
Este es el aspecto que hemos cambiado a nuestra sección footer:
footer: {
style: 'dark',
links: [
{
title: 'Docs',
items: [
{
label: 'Kinsta starters',
to: '/docs/intro',
},
],
},
{
title: 'Talk with us',
items: [
{
label: 'Discord',
href: 'https://discord.gg/vjRPMhFaBA',
},
{
label: 'Support',
href: 'https://kinsta.com/kinsta-support/',
},
{
label: 'Twitter',
href: 'https://twitter.com/kinsta',
},
],
},
{
title: 'More',
items: [
{
label: 'Application Hosting',
href: 'https://kinsta.com/application-hosting/',
},
{
label: 'Database Hosting',
href: 'https://kinsta.com/database-hosting/',
},
{
label: 'WordPress Hosting',
href: 'https://kinsta.com/wordpress-hosting/',
},
{
label: 'DevKinsta',
href: 'https://kinsta.com/devkinsta/',
},
],
},
],
};Colores y CSS
El preajuste classic de Docusaurus utiliza el marco CSS Infima. Teniendo esto en cuenta, los creadores de Docusaurus han creado una herramienta web muy útil para ayudarte a cambiar los colores y otros elementos y declaraciones CSS.
Una vez que hayas introducido tus preferencias en la página, la herramienta generará un archivo custom.css — completado con un atractivo suite de tonos complementarios — en cuestión de segundos. A continuación, puedes copiar este nuevo archivo CSS en el directorio /src/css de tu proyecto como referencia.
Documentación
Toda la documentación de tu nuevo sitio web se almacena en la carpeta /docs. Por supuesto, puedes cambiar el nombre de la carpeta en docusaurus.config.js.
Solo tienes que crear los archivos markdown en tu editor de texto o HTML y soltarlos en esa carpeta. Cada archivo debe tener este aspecto:
---
id: the-id
title: Title
---
# Rest of the documentBasándose en el ID, Docusaurus construye las URL de los artículos de esa subcarpeta: yourdomain.com/docs/{id}
También podemos crear subcarpetas si queremos dividir nuestra documentación en secciones diferentes y lógicas. Sin embargo, tendremos que hacer un poco de trabajo adicional para que estos subdirectorios funcionen como esperamos.
Digamos que creamos una nueva carpeta de documentos llamada Inicio. Si a continuación actualizamos la página de inicio y hacemos clic en el nuevo enlace «Iniciadores» añadido automáticamente a nuestra barra lateral, obtendremos un error, porque aún no existe una página índice en nuestra nueva carpeta.
La forma más sencilla de solucionar esto es crear un archivo _category_.json que genere el índice de todas las páginas que se almacenan en esta carpeta. Solo tienes que añadir el siguiente código:
{
"label": "Starters",
"position": 2,
"link": {
"type": "generated-index",
"description": "All Kinsta Starters"
},
};Como puedes ver, la barra lateral se regenera para ajustarse a la estructura de tus archivos. Esto se debe a que el archivo sidebar.js contiene este tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
Si prefieres ocuparte de esto por tu cuenta, puedes cambiarlo por algo como esto:
tutorialSidebar: [
'intro',
'hello',
{
type: 'category',
label: 'Tutorial',
items: ['tutorial-basics/create-a-document'],
},
],Blog
Docusaurus incluye un práctico módulo de blog. Tener un blog junto a tu sitio web principal puede ser muy útil para informar a tu base de usuarios de los cambios que se producen en tu proyecto, o para mantener notas del proyecto como una forma de registro de cambios.
Cada post consta de una parte principal, como ésta:
---
slug: docusaurus-starter
title: Docusaurus Starter
authors: palmiak
tags: [starters, docusaurus]
---…y, por supuesto, el contenido propiamente dicho. También tiene una etiqueta muy útil <!--truncate--> , que ayuda a limitar el resumen de la entrada que se muestra en todos los listados de entradas.
También es una gran idea crear un archivo authors.yml para los créditos. El archivo tiene este aspecto:
palmiak:
name: Maciek Palmowski
title: DevRel
url: https://github.com/palmiak
image_url: https://github.com/palmiak.pngGracias a este archivo, tendrás todos los datos del autor en un solo lugar para consultarlos fácilmente.
Cómo Desplegar Tu Sitio Web Docusaurus en Kinsta
Además de sitios WordPress, aplicaciones independientes y bases de datos, Kinsta puede alojar sitios estáticos.
Esto significa que es perfecto para tus sitios Docusaurus — y para gestionar todos tus proyectos web — directamente desde tu panel MyKinsta.
Asegúrate de enviar primero tu código a tu proveedor Git preferido (Bitbucket, GitHub o GitLab) y sigue estos pasos para desplegar tu sitio estático en Kinsta:
-
- Inicia sesión o crea una cuenta para ver tu panel MyKinsta.
- Autoriza a Kinsta con tu proveedor Git.
- Haz clic en Sitios Estáticos en la barra lateral izquierda, luego haz clic en Añadir sitio.
- Selecciona el repositorio y la rama desde la que deseas desplegar.
- Asigna un nombre único a tu sitio.
- Añade la configuración de construcción en el siguiente formato:
- Comando de construcción:
npm run build - Versión de Node:
18.16.0 - Directorio de publicación:
build
- Comando de construcción:
- Por último, haz clic en Crear sitio.
Si has llegado hasta aquí sin errores, enhorabuena — ¡has desplegado con éxito tu sitio Docusaurus a través de Kinsta!
Aquí puedes ver por primera vez nuestro sitio de ejemplo en Kinsta:
Como alternativa al Alojamiento de Sitios Estáticos, puedes optar por desplegar tu sitio estático con el Alojamiento de Aplicaciones de Kinsta, que proporciona una mayor flexibilidad de alojamiento, una gama más amplia de ventajas y acceso a funciones más robustas. Por ejemplo, escalabilidad, despliegue personalizado mediante un Dockerfile, y analíticas completas que abarcan datos históricos y en tiempo real.
Resumen
Con sus sorprendentes y potentes funciones, su diseño amigable, su navegación intuitiva y su enfoque en el contenido, no es difícil ver por qué Docusaurus se considera una herramienta excelente para cualquier desarrollador que busque desplegar y mantener fácilmente un sitio de documentación estática y/o un blog ágil y bien organizado.
Una vez que hayas llenado tu sitio con contenido que tus visitantes valoren, empezarás a tomar nota de las funciones adicionales incorporadas que resultan útiles. Por ejemplo, las capacidades de optimización para motores de búsqueda de Docusaurus son perfectas para ayudarte a obtener una mayor visibilidad a través de una audiencia más amplia mientras trabajas en otras técnicas para avanzar en los rankings SEO.
¿Has creado algo con Docusaurus? Comparte tus proyectos y experiencia con nosotros en la sección de comentarios más abajo.
Maciek es un desarrollador web que trabaja en Kinsta como Development Advocate Analyst (Analista de Desarrollo). Después del trabajo, pasa la mayor parte del tiempo programando, intentando encontrar noticias interesantes para sus newsletters, o bebiendo café.
Deja una respuesta