Crear y Personalizar un Sitio Docusaurus (Con Función de Blog)

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.

¿Cansado de los lentos sistemas de gestión de contenidos? Te presentamos a Docusaurus. Un generador de sitios estáticos que hace el trabajo sin ralentizarte. Más información ✅Clic para Tuitear

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):

• Algolia DocSearch
• Jest
• React Native
• Supabase

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 [email protected]  classic

Esto 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 start

Si quieres crear una versión optimizada que esté lista para su despliegue, debes ejecutar esto en su lugar:

npm run build

Estructura

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.lock

Hay 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 document

Basá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   , 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.png

Gracias 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 de WordPress, aplicaciones independientes y bases de datos, Kinsta puede alojar sitios web estáticos.

Esto significa que es perfecto para tus sitios Docusaurs — y para gestionar todos tus proyectos web — directamente desde tu panel MyKinsta.

Una vez desplegada tu aplicación, podrás revisar las analíticas actuales de tu aplicación, tanto en tiempo real como históricas, con mediciones que incluyen:

• Uso de ancho de banda
• Tiempo de construcción
• Tiempo de ejecución
• Uso de la CPU
• Uso de memoria

Desde el principio hasta el final, el proceso de despliegue a través de MyKinsta sólo lleva unos minutos.

¡Vamos a empezar!

Requisitos Previos: Configurar tu Proyecto Docusaurus

Para alojar tu proyecto Docusaurus en la plataforma de Alojamiento de Aplicaciones de Kinsta, necesitarás:

1. Incluir un campo de nombre en tu archivo package.json. (Puede ser cualquiera y no afectará a su despliegue.)
2. Incluir un script de construcción en tu archivo package.json. (Tu proyecto Docusaurus ya debería incluirlo.)
3. Instalar el paquete serve npm y establecer el script de inicio como serve build.

Una vez marcadas estas opciones, puedes pasar a desplegar tu sitio.

Desplegar Tu Proyecto Docusaurus

Sigue estos sencillos pasos para conectarte a tu cuenta de GitHub y lanzar tu sitio Docusaurus:

1. Accede a tu cuenta MyKinsta y navega hasta la pestaña Aplicaciones del menú de la izquierda.
2. Haz clic en el botón azul Añadir servicio y elige Aplicación en el desplegable.

   

3. Si aún no te has conectado a tu cuenta de GitHub a través de MyKinsta, se te mostrará un modal animándote a hacerlo. Haz clic en el botón Continuar con GitHub para continuar.

   

4. Se abrirá una nueva ventana solicitando tu permiso para autorizar a Kinsta a acceder y gestionar tus recursos de GitHub. Asegúrate de que has iniciado sesión en la cuenta correcta de GitHub, y luego haz clic en el botón verde  Autorizar a Kinsta, cerca de la parte inferior.

   

5. Ahora has llegado al asistente de integración de GitHub. Este es el último paso antes de que puedas desplegar tu sitio. Considera cuidadosamente los campos presentados y rellénalos de acuerdo con tu configuración de GitHub y los requisitos de tu proyecto. Si tienes un Dockerfile en tu repositorio, puedes utilizarlo para configurar la imagen contenedora; de lo contrario, Kinsta configurará automáticamente una imagen contenedora por ti. Ten en cuenta que es posible que tengas que editar tus permisos de GitHub antes de poder proceder, sobre todo si es la primera vez que despliegas a través de Kinsta.
   

   

   Puedes elegir si quieres conceder a Kinsta acceso a todos los repositorios o sólo a algunos específicos. Estos permisos pueden ajustarse en cualquier momento desde la configuración de Aplicaciones de tu cuenta de GitHub.

   

6. Una vez que hayas hecho tus selecciones y confirmado tus elecciones, se te mostrarán los detalles de tu despliegue, así como las opciones de Cambiar la configuración o Volver a desplegar.
   

   

   Aquí es también donde verás cualquier error que se haya producido durante el despliegue, además de los detalles sobre la causa del fallo para que lo puedas solucionar fácilmente. Si tienes dificultades para solucionar el problema, puedes encontrar más información sobre los errores de despliegue en la documentación de Kinsta.

   

Si has llegado hasta aquí sin errores, enhorabuena — ¡acabas de desplegar tu sitio Docusaurus a través de Kinsta con éxito! Tu aplicación (es decir, tu sitio estático) estará disponible en cuanto hayas completado el asistente. Puedes verlo en la URL de tu aplicación, que suele ser https://your-docusaurus-site.kinsta.app.

Este es el primer vistazo a nuestro sitio de ejemplo en Kinsta:

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.

¡Cambia las reglas del juego del desarrollo web! Despídete de los pesados CMS y da la bienvenida a Docusaurus, un sencillo generador de sitios estáticos que está cambiando las reglas del juego. 💥 Compruébalo aquí ⬇️Clic para Tuitear

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.