VuePress es un generador de sitios estáticos desarrollado por Evan You, el creador de Vue.js, originalmente pensado para escribir la documentación de los propios proyectos de Vue. Un sitio en VuePress es en realidad una SPA (Single-Page Application) que utiliza Vue, Vue Router y webpack como base.
¿Cómo funciona VuePress?
VuePress está compuesto de dos partes: un generador minimalista de sitios estáticos con un sistema de temas personalizable con Vue y un tema por defecto optimizado para escribir documentación técnica. Cada página generada por VuePress tiene su propio HTML estático preprocesado, proporcionando un muy buen rendimiento al momento de cargar y compatibilidad con SEO. Una vez que la página es cargada, Vue toma el control del contenido estático y lo convierte en una completa SPA.
Durante el desarrollo, Vue crea un servidor local con una versión renderizada de la aplicación y renderiza el HTML correspondiente al visitar cada página. Cada archivo markdown es compilado a HTML con markdown-it y luego procesado como la plantilla de un componente de Vue. Esto te permite usar Vue directamente en tus archivos markdown, lo cual es excelente cuando necesitas añadir contenido dinámico.
Características de VuePress
Algunas de las caracteristicas de VuePress son:
- Markdown optimizado para escribir documentación técnica.
- Posibilidad de utilizar Vue dentro de archivos markdown.
- Un sistema de temas basado en Vue.
- Soporte para PWA (Progressive Web App).
- Integración con Google Analytics.
VuePress también incluye un tema por defecto con:
- Diseño adaptable.
- Página de inicio opcional.
- Sistema de búsqueda.
- Barra de navegación y sidebar personalizable.
- Enlace de GitHub y enlaces de edición generados automáticamente.
Generar un sitio con VuePress
Generar un sitio con VuePress es bastante sencillo y veremos cómo hacerlo a continuación. Lo primero que debemos hacer es instalar VuePress con npm, lo cual podemos lograr de forma global con el siguiente comando:
npm install -g vuepress
Una vez hecho esto, dentro del directorio donde queremos generar nuestro sitio creamos un archivo README:
echo "# Tutorial sobre VuePress de Styde.net" > README.md
Ya tenemos lo básico para nuestro sitio, ahora podemos ejecutar el servidor local con el siguiente comando:
vuepress dev .
Asegúrate de estar dentro del directorio de tu sitio al ejecutar este comando.
Ahora, si te diriges en el navegador a http://localhost:8080/ podrás ver tu sitio generado con VuePress.
Nuestro sitio se ve bien pero podemos agregar un encabezado y una descripción, así como también un sistema de búsqueda en la parte superior. Para hacer esto crea un directorio .vuepress dentro del directorio de tu sitio.
El nombre del directorio debe tener un punto al comienzo, de lo contrario el archivo de configuración no será cargado.
Dentro del directorio .vuepress crea un archivo config.js. En en este archivo debes poner lo siguiente:
module.exports = {
title: 'Mi sitio con VuePress',
description: 'Tutorial de VuePress de Styde.net'
}
Luego de hacer esto veremos el encabezado y el formulario de búsqueda en la parte superior. Básicamente en el archivo config.js estamos asignando un título para el encabezado con title y con description una descripción que se incluye en el código HTML como una etiqueta meta.
Si no puedes ver los cambios en el navegador asegúrate de ejecutar de nuevo vuepress dev . en la terminal.
En la referencia de configuración tienes una lista con todas las opciones de configuración y personalización disponibles.
Para agregar más páginas a tu sitio simplemente agrega un archivo markdown. Si, por ejemplo, quieres una página llamada contacto agrega un archivo contacto.md.
Generar los archivos estáticos de nuestro sitio
Hasta el momento hemos ejecutado nuestro sitio en un servidor local, sin embargo fuera de este no podemos hacer mucho con nuestros archivos markdown. Para generar nuestros archivos estáticos y poder utilizarlos fuera del entorno local necesitamos ejecutar el comando build dentro del directorio de nuestro sitio:
vuepress build .
Al hacer esto VuePress creará un directorio dist dentro de .vuepress con los archivos de nuestro sitio generados y listos para ser usados en un servidor, que bien podría ser un servicio de alojamiento web, un VPS o GitHub Pages. Yo he subido el ejemplo creado a Github Pages y puedes ver el resultado aquí.
Si estás utilizando GitHub Pages, por ejemplo, es necesario que establezcas la propiedad base en el archivo config.js a la URL que planeas utilizar. Por ejemplo, si tu sitio se va a encontrar en misitio.com/blog establece base a '/blog/' (debes comenzar y finalizar la cadena con un slash).
Material relacionado
- Sitio oficial de VuePress
- Referencia de Markdown
- Ejemplo creado con VuePress y alojado en Github Pages
Recuerda que puedes seguirnos en Twitter y suscribirte a nuestro boletín:
Regístrate hoy en Styde y obtén acceso a todo nuestro contenido.
