En el acelerado panorama digital actual, tener un sitio de documentación o blog bien organizado y visualmente atractivo es esencial para captar la atención de tu audiencia y mantenerla interesada. Pero, ¿cómo puedes conseguirlo sin dedicar interminables horas al desarrollo web?
Este artículo explica cómo crear y personalizar un sitio de documentación y blog rápido utilizando VuePress, un generador de sitios estáticos (SSG – Static Site Generators) minimalista pero potente.
¿Qué es VuePress?
VuePress es un framework de código abierto especializado en generar sitios web estáticos, orientado principalmente a la documentación y los blogs. Fue creado por Evan You, el genio detrás de Vue.js, y encarna la filosofía de simplicidad y facilidad de uso por la que Vue.js es conocido.
¿Por qué utilizar VuePress?
Aquí tienes algunas razones de peso por las que VuePress puede ser la elección perfecta para ti.
- Simplicidad Markdown: VuePress simplifica la creación de contenidos con Markdown, facilitando la escritura y estructuración de contenidos sin formatos complejos.
- Integración con Vue.js: VuePress integra a la perfección Vue.js, permitiendo elementos web interactivos y dinámicos para una experiencia de usuario atractiva.
- Rendimiento y personalización: VuePress ofrece un rendimiento excelente con sitios web estáticos de carga rápida y amplias opciones de personalización para adaptarse a tu estilo y necesidades.
Primeros Pasos con VuePress
Antes de sumergirte en VuePress, asegúrate de que tienes instalado Node.js o Yarn Classic en tu ordenador. Hay dos formas de empezar con VuePress: o bien utilizas el generador create-vuepress-site, que te ayudará a crear la estructura básica del sitio VuePress, o bien utilizas la instalación manual.
Para este artículo, vamos a utilizar el método de instalación manual.
- Crea un nuevo directorio y cámbialo:
mkdir vuepress-starter && cd vuepress-starter- Inicialízalo con tu gestor de paquetes preferido. Para este artículo, vamos a utilizar Yarn:
yarn init- Instala VuePress en tu proyecto como dependencia del desarrollador:
yarn add -D vuepress- Crea una carpeta docs para guardar todo tu código y luego crea un archivo README.md, que sirve como archivo índice de tu proyecto, similar a index.html:
mkdir docs && echo '# Hello VuePress' > docs/README.md- Abre tu proyecto en un editor de código y añade los siguientes scripts a tu archivo package.json para que puedas servir y construir tu sitio:
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs"
},Ahora puedes servir tu sitio ejecutando el comando yarn dev. VuePress iniciará tu servidor de desarrollo en http://localhost:8080.
Ya has creado un sitio de documentación. Verás que VuePress ofrece un tema predeterminado limpio y minimalista. Sin embargo, es altamente personalizable, ofreciéndote libertad creativa para crear un aspecto único para tu sitio web.
Crear Páginas de Documentación
VuePress sigue una estructura de directorios sencilla para organizar la documentación. Dentro de la carpeta de tu proyecto, encontrarás el directorio docs que hemos creado, donde puedes crear archivos Markdown (.md) para tus páginas de documentación.
Por ejemplo, puedes crear archivos como getting-started.md, usage.md y troubleshooting.md. Estos archivos se convierten automáticamente en rutas a las que puedes acceder cuando navegas a http://localhost:8080/getting-started, http://localhost:8080/usage y http://localhost:8080/troubleshooting.
Para mejorar la organización de tu documentación, puedes crear carpetas dedicadas a páginas de documentación relacionadas. Por ejemplo, puedes crear una carpeta llamada guide y organizarla con guías específicas como using-kinsta-stsh.md. Cuando emplees esta estructura, el contenido de using-kinsta-stsh.md será accesible a través de una URL como http://localhost:8080/guide/using-kinsta-stsh.
También puedes crear un archivo README.md o index.md en el nivel raíz de la carpeta del guide. Este archivo servirá como página índice, permitiendo a los usuarios navegar a http://localhost:8080/guide/ y acceder cómodamente al contenido con una barra lateral que aprenderás a configurar en la siguiente sección.
En este repositorio de muestra de VuePress, observarás que se han creado todos estos archivos, y se ha añadido algo de contenido markdown a cada uno de ellos. Siéntete libre de crear tus archivos según tus preferencias, ya sea desde cero para adaptarlos a tus necesidades específicas o inspirándote en el contenido disponible en el repositorio.
Personalizar la Apariencia de VuePress
Una vez que hayas creado tu sitio de documentación con contenido, puede que te resulte difícil navegar por él, especialmente si tienes muchos archivos que gestionar. Sin embargo, VuePress te permite personalizar la estructura de navegación de tu sitio para hacerlo más fácil de usar y organizado.
Para personalizar el aspecto y la navegación de tu sitio, crea una carpeta .vuepress en el directorio raíz de tu proyecto. Esta carpeta contendrá archivos de configuración y activos relacionados con tu sitio VuePress.
Configuración de la navegación
En la carpeta . vuepress, crea un archivo config.js. También puedes utilizar otros formatos de archivo como YAML (.yml), TOML (.toml) o TypeScript (.ts) para tu configuración.
En tu archivo config.js, puedes definir la estructura de navegación de tu sitio utilizando el objeto themeConfig. Aquí tienes un ejemplo de configuración:
module.exports = {
title: 'Kinsta Vuepress',
description: 'A VuePress QuickStart for Kinsta',
themeConfig: {
nav: [
{
text: 'Guide',
link: '/guide/',
},
{
text: 'Static Site Hosting',
link: 'https://kinsta.com/static-site-hosting/',
},
],
sidebar: {
'/guide/': [
{
title: 'Guide',
collapsable: false,
children: ['', 'using-kinsta-stsh'],
},
],
},
},
};En este ejemplo, estamos configurando los sitios title y description, definiendo los enlaces de navegación y configurando una barra lateral para la sección /guide/.
La matriz nav especifica los enlaces de navegación en la parte superior de tu sitio. El objeto barra lateral define la estructura de la barra lateral para secciones específicas. En este caso, está configurado para la sección /guide/.
Puedes leer más sobre la configuración de la barra de navegación en la documentación de VuePress.
Estilizar
VuePress te permite personalizar la apariencia de tu sitio mediante estilos. Puedes anular los estilos predeterminados utilizando algunas variables definidas o definir tu propio estilo. Para ello, crea una carpeta de estilos en la carpeta .vuepress
Para aplicar anulaciones sencillas al estilo del preajuste predeterminado o definir algunas variables para utilizarlas más adelante, puedes crear un archivo palette.styl en .vuepress/styles. Estas son algunas variables predefinidas que puedes modificar:
// colors
$accentColor = #5333ED
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34
$arrowBgColor = #ccc
$badgeTipColor = #42b983
$badgeWarningColor = darken(#ffe564, 35%)
$badgeErrorColor = #DA5961
// layout
$navbarHeight = 3.6rem
$sidebarWidth = 20rem
$contentWidth = 740px
$homePageWidth = 960px
// responsive breakpoints
$MQNarrow = 959px
$MQMobile = 719px
$MQMobileNarrow = 419pxEstas variables pueden utilizarse para mantener un estilo coherente en todo tu sitio. VuePress también proporciona una forma cómoda de añadir estilos adicionales. Puedes crear un archivo index.styl en la carpeta .vuepress/styles donde puedes utilizar la sintaxis CSS normal:
.content {
font-size 30px
}Lee más sobre el estilo de VuePress en la documentación oficial.
Uso de componentes
VuePress admite el uso de componentes para mejorar la funcionalidad y el aspecto de tus páginas. Puedes crear componentes Vue e incluirlos en tus archivos Markdown. Crea una carpeta components en .vuepres, y entonces cualquier archivo *.vue que se encuentre en .vuepress/components se registrará automáticamente como componente global.
Por ejemplo, considera la posibilidad de crear dos componentes, HomeOptions.vue y HostingBanner.vue:
.
└─ .vuepress
└─ components
├─ HomeOptions.vue
└─ HostingBanner.vueDentro de estos archivos de componentes vue.js, puedes añadir códigos CSS. Vamos a añadir código a los componentes HomeOptions.vue y HostingBanner.vue.
Añade el código siguiente a HomeOptions.vue:
<template>
<div class="options">
<div class="option">
<a
href="https://kinsta.com/docs/static-site-hosting/static-site-quick-start-examples/"
target="_blank"
>
<h3>Quick Start Examples</h3>
</a>
<p>Explore quick start examples for setting up static sites.</p>
</div>
<div class="option">
<a
href="https://kinsta.com/docs/static-site-hosting/getting-started-static-site-hosting/"
target="_blank"
>
<h3>Getting Started</h3>
</a>
<p>Learn how to get started with static site hosting.</p>
</div>
<div class="option">
<a
href="https://kinsta.com/docs/static-site-hosting/manage-static-sites/"
target="_blank"
>
<h3>Manage Static Sites</h3>
</a>
<p>Discover how to efficiently manage your static sites.</p>
</div>
</div>
</template>
<style scoped>
a {
color: #2c3e50;
}
a:hover {
color: #5333ed;
}
.options {
display: flex;
gap: 10px;
margin: 40px 0;
}
.option {
border: 2px solid #eaecef;
border-radius: 5px;
padding: 10px;
}
</style>Añade también el código siguiente a HostingBanner.vue:
<template>
<div class="banner">
<p>Host Your Static Site With Kinsta for Free!</p>
<a
href="https://kinsta.com/docs/static-site-hosting/"
target="_blank"
class="btn"
>Read More</a
>
</div>
</template>
<style> scoped>
.banner {
background: rgb(156, 85, 34);
background: linear-gradient(
90deg,
rgba(156, 85, 34, 1) 0%,
rgba(32, 50, 103, 1) 42%,
rgba(13, 18, 25, 1) 69%,
rgba(22, 47, 60, 1) 100%
);
color: #fff;
padding: 20px;
border-radius: 5px;
display: flex;
justify-content: center;
align-items: center;
flex-direction: column;
}
.banner p {
width: 600px;
font-size: 40px;
font-weight: bold;
text-align: center;
line-height: 50px;
}
.banner .btn {
border-radius: 5px;
padding: 15px;
color: #1f1f1f;
font-weight: bold;
background: #fff;
display: inline-block;
margin-bottom: 10px;
}
.banner .btn:hover {
background: #111319;
color: #fff;
}
</style>Dentro de cualquier archivo Markdown, podrás utilizar directamente los componentes (los nombres se deducen de los nombres de archivo):
<HomeOptions/>
<HostingBanner/>Lee más sobre los componentes en VuePress en la documentación.
Personalizar la página de inicio
En VuePress, el tema predeterminado ofrece un diseño de página de inicio prediseñado que puedes utilizar para crear un punto de partida atractivo e informativo para tu sitio. Para utilizar este diseño de página de inicio, debes especificar home: true e incluir algunos metadatos adicionales en el frontmatter YAML de tu archivo raíz README.md.
Aquí tienes un ejemplo del frontmatter YAML:
---
home: true
heroImage: /hero.png
heroText: Hero Title
tagline: Hero subtitle
actionText: Get Started →
actionLink: /guide/
features:
- title: Simplicity First
details: Minimal setup with markdown-centered project structure helps you focus on writing.
- title: Vue-Powered
details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
- title: Performant
details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
footer: MIT Licensed | Copyright © 2018-present Evan You
---Todas estas configuraciones hacen que tu página de inicio de la documentación tenga este aspecto:
Cabe señalar que puedes desactivar los valores heroText y tagline o cualquier otro estableciendo sus campos correspondientes en null si prefieres un diseño más sencillo o no incluirlo. Cualquier contenido que incluyas después del frontmatter YAML (es decir, la sección de metadatos) se tratará como Markdown normal y se renderizará a continuación de la sección de características.
Si quieres un diseño de página de inicio totalmente personalizado, VuePress también admite diseños personalizados. Además, puedes crear un pie de página de texto enriquecido utilizando la Sintaxis de Ranura Markdown, que ofrece más flexibilidad a la hora de mostrar el contenido del pie de página. Aquí tienes un ejemplo de cómo crear un pie de página de texto enriquecido:
---
home: true
---
::: slot footer
Made with ❤️ by Kinsta. [Static Site Hosting](https://kinsta.com/static-site-hosting/)
:::En este caso, el contenido de la sección ::: slot footer te permite incluir enlaces e información adicional en la zona del pie de página de tu página de inicio.
Ahora que ya sabes cómo realizar las personalizaciones anteriores, añade a la página de inicio los componentes creados anteriormente y elimina algunas opciones para que la página de inicio tenga mejor aspecto:
---
home: true
tagline: A VuePress QuickStart for Kinsta
actionText: Quick Start →
actionLink: /guide/
---
<HomeOptions/>
<HostingBanner/>
::: slot footer
Made with ❤️ by Kinsta. [Static Site Hosting](https://kinsta.com/static-site-hosting/)
:::
Siguiendo estas técnicas de personalización de VuePress, puedes crear un sitio de documentación que no sólo proporcione contenidos valiosos, sino que también ofrezca una excelente experiencia de usuario con una navegación organizada y un estilo atractivo.
Puedes leer más sobre la personalización del tema predeterminado en la documentación.
Crear una Sección de Blog con VuePress
Añadir una sección de blog a tu sitio VuePress es muy sencillo, ya que VuePress te permite escribir componentes Vue personalizados que pueden insertarse en cualquier archivo Markdown. Vamos a crear un componente que mostrará la lista de entradas del blog.
Crea un archivo BlogIndex.vue en la carpeta components y añade el siguiente código:
<template>
<div>
<div v-for="post in posts" v-bind:key="post.path">
<h2>
<router-link> :to="post.path">{{ post.frontmatter.title }}</router-link>
</h2>
<p>{{ post.frontmatter.description }}</p>
<p><router-link> :to="post.path">Read more</router-link></p>
</div>
</div>
</template>
<script>>
export default {
computed: {
posts() {
return this.$site.pages
.filter(
(x) => x.path.startsWith('/blog/') && !x.frontmatter.blog_index
)
.sort(
(a, b) =>
new Date(b.frontmatter.date) - new Date(a.frontmatter.date)
);
},
},
};
</script>En el fragmento de código proporcionado, defines una plantilla Vue que recorre las entradas de tu blog utilizando v-for, mostrando el título de la entrada, la descripción y un enlace «Leer más» para cada entrada.
La sección de script exporta un componente Vue que calcula y recupera las entradas del blog. Estas entradas se filtran en función de su ruta (que comienza por /blog/) y la ausencia de un atributo frontmatter blog_index. A continuación, se ordenan por fecha en orden descendente para presentar primero las últimas entradas.
Cuando crees nuevas entradas de blog, deberás especificar la fecha de la entrada como parte de la información de la portada. Esto ayudará a ordenar las entradas para que aparezcan primero las más recientes.
Para almacenar las entradas del blog, crea una carpeta llamada blog en la raíz del proyecto. En esta carpeta, añade un archivo README.md. Éste será el índice del blog, y aquí es donde incluirás el componente BlogIndex para listar todas las entradas del blog.
---
blog_index: true
---
# Blog
Welcome To Our Blog
<BlogIndex />Asegúrate de añadir el atributo blog_index frontmatter, ya que es fundamental para garantizar que el propio índice del blog no aparezca entre las entradas individuales del blog. Este atributo se utiliza al filtrar las entradas en la propiedad computed posts del componente BlogIndex.vue.
A continuación, crea una carpeta blog en la raíz de tu proyecto que almacenará todas las entradas del blog y creará cada entrada. Por ejemplo, crea un archivo first-post.md y añade el siguiente contenido markdown:
---
title: "My Exciting VuePress Blog Journey"
date: 2023-09-28
description: "Exploring VuePress, a versatile static site generator, and sharing my experiences along the way."
---
# My Exciting VuePress Blog Journey
In this inaugural blog post, I embark on an exciting journey with VuePress, a powerful static site generator that's perfect for creating documentation, blogs, and more. As I delve into the world of VuePress, I'll be sharing my experiences, insights, and tips on making the most out of this fantastic tool.Para cada entrada del blog, asegúrate de definir los parámetros esenciales de la portada, como el título de la entrada, la fecha y otros metadatos relevantes. Esta organización meticulosa garantiza que las entradas de tu blog se presenten de forma cohesionada y proporciona una experiencia de lectura atractiva para tu audiencia.
Por último, puedes añadir la navegación del blog a tu barra de navegación en el archivo .vuepress/config.js:
nav: [
{
text: 'Guide',
link: '/guide/',
},
{ text: 'Blog', link: '/blog/' },
{
text: 'Static Site Hosting',
link: 'https://kinsta.com/static-site-hosting/',
},
],Puedes hacer mucho más con VuePress, como añadir plugins, utilizar un tema independiente o incluso crear tu propio tema.
Desplegar un Sitio Estático VuePress en Kinsta
Kinsta te permite alojar hasta 100 sitios web estáticos de forma gratuita. Para ello, envía tu código a tu proveedor Git preferido (Bitbucket, GitHub o GitLab) y luego despliégalo en Kinsta.
Antes de enviar tus archivos a cualquier proveedor de Git, crea un archivo .gitignore en la raíz de tu proyecto para especificar los archivos y carpetas que Git debe ignorar al enviar tu código:
# dependencies
/node_modules
# build directory
./docs/.vuepress/dist
/publicPara esta guía, utilizamos GitHub. Crea un repositorio en GitHub para insertar tu código fuente. Una vez que tu repositorio esté listo, sigue estos pasos para desplegar tu sitio estático en Kinsta:
- Inicia sesión o crea una cuenta para ver tu panel de control MyKinsta.
- Autoriza a Kinsta con tu proveedor de Git.
- Haz clic en Sitios estáticos en la barra lateral izquierda, y luego 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 compilación en el siguiente formato:
- Comando de compilación:
npm run build - Versión del nodo:
16.20.0 - Directorio de publicación:
./docs/.vuepress/distopublic
- Comando de compilación:
- Por último, haz clic en Crear sitio.
Y ya está En pocos segundos tendrás un sitio desplegado. Se proporciona un enlace para acceder a la versión desplegada de tu sitio. Si lo deseas, puedes añadir más adelante tu dominio personalizado y tu certificado SSL.
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 análisis completos que abarcan datos históricos y en tiempo real.
Resumen
VuePress es una herramienta versátil y potente para crear rápidamente sitios de documentación y blogs. Con su sencilla configuración, temas y plugins personalizables, puedes construir una plataforma informativa y visualmente atractiva para tu audiencia.
Empieza a crear tu sitio VuePress hoy mismo y comparte tus conocimientos con el mundo alojándote en nuestro alojamiento de sitios estáticos ¡gratis!
¿Has utilizado VuePress para construir algo? No dudes en compartir tus proyectos y experiencias con nosotros en la sección de comentarios más abajo.
Deja una respuesta