Cómo crear un tema VuePress personalizado con Vuetify

Si ya ha oído hablar de VuePress, es posible que sepa que se trata de un generador de sitio estático potente y mínimo del creador de Vue.js, Evan You. VuePress hace que la creación de sitios web de documentación con mucho texto sea fácil, mucho más fácil que Nuxt.js.

Pero, ¿sabía que VuePress tiene un sistema de temas personalizado construido sobre Vue que le permite crear sus propios temas con todas las funciones con funcionalidad personalizada?

En este artículo, veremos cómo puede comenzar a crear su propio tema personalizado, algunas prácticas recomendadas a seguir y cómo integrar una biblioteca de patrones de interfaz de usuario como Vuetify para la creación rápida de diseños.

Por ejemplo, tomemos el propio sitio web de documentación de VuePress. Está usando el tema predeterminado. El tema predeterminado viene de fábrica con una gran cantidad de funciones personalizadas, como una búsqueda incorporada, navegación y barras laterales personalizables, e incluso un enlace GitHub generado automáticamente y enlaces de edición de página que son excelentes si aloja su sitio web utilizando Páginas de GitHub.

El sitio web de VuePress

Podrá crear temas tan destacados como el tema predeterminado. Si ha utilizado Vue.js para el desarrollo anteriormente, verá que la experiencia de desarrollo es similar cuando crea un tema personalizado. Incluso puede usar Vue DevTools para depurar su tema personalizado.

Entonces empecemos.

Configurar un proyecto VuePress

Primero, asegúrese de tener VuePress instalado en su sistema.

npm install -g vuepress

Cree una carpeta para su sitio web VuePress con el siguiente comando: mkdir my-vuepress-project.

Haga clic aquí para obtener más información sobre la integración de VuePress con un proyecto existente.

Estructurando tu contenido

La belleza de VuePress es que te permite estructurar tu contenido como quieras. Cada archivo de descuento en su proyecto se compilará en un archivo HTML estático.

Por ejemplo, su proyecto podría estar estructurado de la siguiente manera:

Entonces, una vez que su proyecto tiene contenido, ¿cómo comienza a crear un tema personalizado para mostrar ese contenido?

Creando tu tema VuePress personalizado

En el ejemplo de estructura de carpetas anterior, es posible que haya notado una carpeta llamada .vuepress. Esta carpeta es donde van su configuración y todos los archivos específicos de VuePress. También es donde irán tus archivos de temas personalizados.

Para crear un tema personalizado, cree un directorio de temas dentro del directorio .vuepress en su proyecto VuePress y luego cree un archivo Layout.vue.

El componente Layout.vue

El componente Layout.vue es el archivo que busca VuePress al invocar su tema. Se invocará una vez por cada archivo de descuento en su proyecto VuePress.

Por ejemplo, se invocará 4 veces con nuestra estructura de ejemplo, que tiene cuatro archivos de descuento (.md).

Representar el contenido de su sitio web dentro de su tema.

El tema más simple puede ser un solo componente Layout.vue con el siguiente marcado:

El contenido compilado del archivo .md actual que se procesa estará disponible como un componente global especial .

Otra forma de pensar sobre el archivo Layout.vue es como el punto de partida para su tema porque, en realidad, un tema completamente desarrollado requerirá más que un solo archivo.

Estructurando su tema VuePress

Entonces, ¿cuál es la estructura recomendada para un tema VuePress personalizado? No hay reglas obligatorias, pero muchos temas en la naturaleza están estructurados de la siguiente manera:

Esta estructura le permite organizar sus diseños de página individuales (como sus publicaciones y páginas de inicio) en la carpeta de diseños, y luego tener sus componentes individuales (que usan esos diseños) en la carpeta de componentes.

Integre una biblioteca de patrones de UI como Vuetify en su tema personalizado

En última instancia, los temas personalizados de VuePress son solo aplicaciones de Vue, por lo que puede hacer cualquier cosa que normalmente haría dentro de sus aplicaciones. Por ejemplo, puede incluir una biblioteca de patrones de IU en su tema personalizado desde npm.

Desde el terminal, cd en su carpeta .vuepress y luego haga una instalación npm vuetify - guarde para que Vuetify se convierta en su tema personalizado.

Ahora puede aprovechar al máximo cualquier biblioteca dentro de su tema y puede personalizar completamente sus archivos de tema.

Home.vue

Post.vue

Personalizando su tema con los datos de su página

Una vez que tenga una estructura de carpetas en su lugar y haya presentado sus componentes de diseño individuales, ¿cómo puede hacer que esos componentes individuales se procesen desde Layout.vue?

Cuando se trata de sus archivos de rebajas individuales, VuePress le ofrece muchas opciones de personalización. Puede agregar YAML front-matter, un lenguaje de serialización de datos comúnmente utilizado para la configuración, en la parte superior de sus archivos de descuento y VuePress lo interpretará automáticamente por usted.

Cada vez que se llama a Layout.vue, el YAML que ha definido en su archivo, junto con otros metadatos generados por VuePress, estará disponible dentro de su componente Layout.vue como esta. $ Page.

Por ejemplo, cuando procese su archivo /guides/getting-started.md, su variable this. $ Page podría tener un aspecto similar al siguiente:

{
  "lastUpdated": 1524847549000,
  "ruta": "/guides/getting-started.html",
  "title": "Guías - Primeros pasos",
  "frontmatter": {}
}

Luego puede usar esos datos para personalizar el tema a su gusto. Por ejemplo, una cosa que puede hacer es renderizar un diseño HTML / CSS diferente para una apariencia diferente dependiendo de la ruta del archivo.

Otra variable que se inyecta es este sitio. $ Que le brinda información sobre todo su sitio web.

{
  "title": "VuePress",
  "description": "Generador de sitio estático alimentado por Vue",
  "base": "/",
  "páginas": [
    {
      "lastUpdated": 1524027677000,
      "camino": "/",
      "title": "VuePress",
      "frontmatter": {}
    },
    ...
  ]
}

Un ejemplo de lo que puede hacer con la matriz this. $ Site.pages es recorrerlo y crear enlaces siguientes y anteriores.

Las propiedades this. $ Site y this. $ Page se inyectan en cada componente dentro de la carpeta .vuepress.

Haga clic aquí para obtener más información sobre todos los datos que se inyectan en sus componentes.

Recursos extra

Aquí hay tres temas personalizados de VuePress en GitHub que puede usar como referencia para crear los suyos.

  • Índigo
  • Yubisaki
  • Valle

O simplemente puede instalarlos directamente.

Haga clic aquí para aprender cómo instalar estos temas directamente en su proyecto.

Conclusión

En última instancia, crear un tema de VuePress le brinda tanta flexibilidad como crear una aplicación Vue.js. Eres libre de diseñar tu tema de la manera que mejor funcione para ti.

En esta publicación, repasamos algunas prácticas recomendadas, los datos que puede usar dentro de los componentes de su tema y también cómo integrarse con una biblioteca de interfaz de usuario como Vuetify para crear diseños.

Sigue leyendo

  • VuePress vs Nuxt.js
  • Acelere el desarrollo con VueTools
  • Cómo crear transiciones Vue.js