Crear un sitio estático con VitePress para una documentación de ayuda atractiva

Introducción

Siempre he sido un fan de los generadores de sitios estáticos como una forma de crear un sitio web HTML basado en texto (normalmente en Markdown) con el apoyo de la comunidad temática. Esto permite dedicar más tiempo a escribir contenidos que a gestionar la infraestructura de un sistema de gestión de contenidos (CMS) como WordPress, que requiere una base de datos y una interfaz de usuario para introducir contenidos. Si pudiera resumir mis tres razones por las que me gustan los generadores de sitios estáticos, serían:

• Rendimiento (las páginas están pre-renderizadas)

• La posibilidad de tener temas

• No requieren la ejecución de código en el servidor.

Vamos a saltar en uno popular llamado, VitePress.

vitepressmain.png

Introducción a VitePress

VitePress es VuePress y está desarrollado por Vite y Vue.js. Para aquellos que no lo saben, Vite es una herramienta de construcción que tiene como objetivo proporcionar una experiencia de desarrollo más rápido y más delgado para proyectos web modernos, por lo que podría tener sentido para emparejarlo con un generador de sitio estático como VitePress. Vue.js es un framework JavaScript progresivo para la construcción de interfaces de usuario web. Uno de los problemas originales con VuePress era que era una aplicación Webpack, y tomó mucho tiempo para hacer girar un servidor de desarrollo para un simple doc. VitePress resuelve estos problemas con un arranque del servidor casi instantáneo, una compilación bajo demanda que sólo compila la página que se está sirviendo, y un HMR rapidísimo. ¡Vamos a empezar!

Empezar de cero y crear un sitio web estático que funcione

En primer lugar, crea una carpeta donde desarrollarás tu sitio estático.

A continuación, inicialícelo con Hilo o NPM. Para este ejemplo, usaremos Yarn. Si no tiene Yarn instalado, puede instalarlo en la página de descargas página de descargas. Para aquellos que utilicen NPM, la documentación de VitePress se encuentra aquí.

Se le plantearán una serie de preguntas, que puede rellenar aquí o dejar en blanco, como hice yo.

yarn init
yarn init v1.22.19
question name (static-starter):
question version (1.0.0):
question description:
question entry point (index.js):
question repository url:
question author:
question license (MIT):
question private:
success Saved package.json
Done in 26.93s.

Nota: Siempre puede rellenar estos campos más tarde cuando configure el sitio.

En este punto, sólo tendrá un único package.json archivo. Ahora debe agregar VitePress y Vue como dependencias de desarrollo para el proyecto.

yarn add --dev vitepress vue

Ahora necesitamos un lugar para almacenar los documentos que vamos a crear y añadir un documento de ejemplo.

mkdir docs 
cd docs
touch index.md

Edite el contenido de index.md para incluir el siguiente texto:

# Hello VitePress.

Ahora debería tener los siguientes archivos y carpetas:

docs 
├── index.md
node_modules 
package.json 
yarn.lock

Tenemos que añadir la siguiente sección scripts a nuestra sección package.json.

{
  "name": "static-starter",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "devDependencies": {
    "vitepress": "^1.0.0-alpha.21",
    "vue": "^3.2.41"
  },
    "scripts": {
      "docs:dev": "vitepress dev docs",
      "docs:build": "vitepress build docs",
      "docs:serve": "vitepress serve docs"
  }
}

Eso nos permitirá tener diferentes perfiles en función de la situación.

Puede desplegar el servidor ejecutando yarn docs:dev como se muestra a continuación.

yarn docs:dev
yarn run v1.22.19
$ vitepress dev docs
vitepress v1.0.0-alpha.21

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

VitePress soporta "recarga en caliente", lo que significa que después de guardar un archivo en el proyecto, no tendrás que reconstruir el sitio para ver tus cambios.

Ahora debería tener un servidor en ejecución, y normalmente se ejecuta en la siguiente ubicación: http://localhost:5173.

helloworld.gif

¡Enhorabuena! Nuestra aplicación está funcionando ahora, y ya se puede notar algunas de las características y funcionalidades que hemos recibido utilizando VitePress, tales como:

• Sitio responsivo con animaciones

• Construir con la filosofía "Mobile-first

• Modo oscuro y claro integrados

Añadir más páginas y comprender la estructura de archivos

Vamos a añadir otra página a la que el usuario final puede navegar una vez que el sitio se carga. En primer lugar, cree un archivo llamado another-page.md dentro de la carpeta docs carpeta. Añade el siguiente texto al contenido del archivo # Another Page.

Ahora su docs debería tener este aspecto.

docs
├── index.md
├── another-page.md

No lo encontrará si intenta navegar a another page.md en su navegador. Puede acceder a la página manualmente siguiendo la URL: http://localhost:5173/another-page.

Nota: Observe que la estructura de directorios se corresponde con la ruta URL.

¿Cómo podemos solucionarlo?

Añadir navegación

Tenemos lo básico de un sitio web, pero le falta capacidad de navegación para encontrar las demás páginas. Normalmente, el menú de la barra lateral se utiliza para los sitios de documentación. Para añadirlos, tenemos que hacer algunas cosas primero.

Para personalizar y añadir navegación a su sitio, primero vamos a crear un directorio .vitepress dentro de su directorio docs directorio. Una vez completado, añadir otro archivo llamado config.js. Esta carpeta es donde se colocarán todos los archivos de configuración específicos de VitePress. La estructura de tu proyecto debería ser como la siguiente

docs
├── index.md
├── another-page.md
└── .vitepress
    └── config.js

Abra su vitepress/config.js y añade el siguiente código:

export default {
  title: 'VitePress',
  description: 'Vonage Loves Developers.'
}

Esto proporcionará un título y una descripción predeterminados para el sitio, que los motores de búsqueda indexarán.

A continuación, configuraremos nuestra barra de navegación de nivel superior para que tenga dos elementos adicionales para nuestra Hoja de ruta y formas para que nuestros usuarios Comentarios. Añada lo siguiente a su archivo vitepress/config.js después del campo description campo

themeConfig: {
 nav: [
  { text: 'Roadmap', link: '/roadmap' },
  { text: 'Feedback', link: '/feedback' }
]

toplevelnavigation.png

¡Increíble! ¡Nuestro sitio está tomando forma! Ahora, vamos a añadir nuestro barra lateral debajo del elemento nav que acabamos de crear.

export default {
  title: 'VitePress',
  description: 'Vonage Loves Developers.',
  themeConfig: {
    nav: [
      { text: 'Roadmap', link: '/roadmap' },
      { text: 'Feedback', link: '/feedback' }
    ],
    sidebar: [
      {
        text: 'Guide',
        items: [
          { text: 'Introduction', link: '/introduction' },
          { text: 'Getting Started', link: '/getting-started' },
        ]
      }
    ]
  }
}

¡Ahora nuestro sitio está empezando a tomar forma! Hemos añadido un nivel superior y una barra lateral de navegación. También tenemos una Página siguiente que irá a la Introducción (una vez que la hayamos creado).

sidelevelnavigation.png

Sigamos adelante y agreguemos todas las páginas que acabamos de crear:

Cree los siguientes archivos llamados roadmap.md, feedback.md, introduction.md y getting-started.md en la carpeta docs y dales una cabecera con el mismo nombre.

Por ejemplo, # Roadmap se introduciría dentro del archivo roadmap.md archivo. Haga lo mismo para todos los ficheros.

Una vez guardado todo, vuelva a su sitio para comprobar que todos los enlaces funcionan ahora como es debido.

navigationadded.gif

Otras características destacables

Enlaces de edición de GitHub o GitLab

Puede crear automáticamente un enlace en cada página para que sus lectores contribuyan a la precisión de la página a través de servicios de gestión Git como GitHub o GitLab. Para activarlo, añada themeConfig.editLink a su configuración como se muestra a continuación:

export default {
  themeConfig: {
    editLink: {
      pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
      text: 'Edit this page on GitHub'
    }
  }
}

Ahora, cada página renderizada tendrá un enlace de vuelta a GitHub (o GitLab) para que el usuario pueda realizar una pull request.

editpage.png

Contenedores a medida

Hay soporte incorporado para contenedores personalizados cuando se quiere llamar la atención de un lector sobre algo, por ejemplo, información, consejo, cuadro de advertencia, etc.

::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

::: details
This is a details block.
:::

Esto se traduce como:

tipbox.png

Resaltado de sintaxis en bloques de código

El resaltado de sintaxis en bloques de código se soporta de varias formas. Vea este ejemplo de cómo puede resaltar una línea en un bloque de código:

export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}

syntaxhighlighting.png

Despliegue de la aplicación

Ahora que hemos desarrollado nuestro sitio estático, y le hemos añadido páginas junto con una barra de navegación enriquecida, vamos a desplegar nuestra aplicación. Puedes hacerlo ejecutando el siguiente comando yarn docs:build.

Si todo funciona correctamente, verás lo siguiente:

yarn docs:build
yarn run v1.22.19
$ vitepress build docs
vitepress v1.0.0-alpha.21
✓ building client + server bundles...
⠋ rendering pages...(node:3164) ExperimentalWarning: The Fetch API is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
✓ rendering pages...
build complete in 8.29s.
Done in 8.97s.

Los archivos renderizados irán por defecto a la página de tu proyecto en dist. Por ejemplo, mis archivos se renderizaron aquí: C:\Users\mbcru\source\static-starter\docs\.vitepress\dist

fileexplorer.png

Resumen

Ahora que su sitio estático está en funcionamiento, podría añadir funciones de comunicación específicas que Vonage ofrece, como Videoo Mensajeríaetc.

Si tienes preguntas o comentarios, únete a nosotros en el Slack para desarrolladores de Vonage o envíame un Tweet a Twittery te responderé. Gracias de nuevo por leer, ¡y te espero en el próximo!