Aprovechando el lanzamiento de la documentación de Laravel en español he decidido crear una serie de tutoriales donde explico el proceso de deploy automatizado que utilizamos para la creación y publicación del sitio de la documentación.
Anteriormente en Styde ya hablamos sobre VuePress, una librería de Vue.js con la que podemos crear sitios estáticos. VuePress nos permite utilizar Markdown para escribir nuestras páginas y luego nos genera los archivos HTML de nuestro sitio que más adelante podemos subir a cualquier servidor que soporte archivos estáticos.
El sitio de la documentación de Laravel en Español está creado utilizando VuePress y alojado usando GitHub Pages. Github Pages es una herramienta de GitHub que nos permite alojar páginas estáticas de forma gratuita y que está disponible para todos los usuarios de la plataforma.
¿Qué necesitamos?
En este primer tutorial configuraremos dos repositorios de Git en GitHub que necesitaremos:
- Uno para el código fuente de nuestro sitio.
- Uno para el despliegue en GitHub Pages.
El repositorio con el código fuente será el lugar donde el código base de la aplicación se encontrará, es decir, el lugar donde residirá la configuración de VuePress y los archivos Markdown. Por su parte, el repositorio para el despliegue será el sitio donde Travis CI se encargará de desplegar los archivos estáticos de VuePress.
También necesitamos una cuenta de Travis CI y dependiendo del tipo de repositorio con el que estamos trabajando tenemos dos opciones:
- Si estamos usando repositorios públicos nos registramos en travis-ci.org
- Si estamos usando repositorios privados o que pertenecen a una organización nos registramos en travis-ci.com
Primeros pasos
Una vez nos hemos registrado en Travis CI podemos proceder a crear nuestros repositorios.
El repositorio para el código fuente puede tener cualquier nombre, pero el nombre del repositorio para GitHub Pages debe tener el siguiente formato:
tunombredeusuario.github.io
tunombredeusuario debes reemplazarlo con tu nombre de usuario de GitHub.
GitHub Pages te permite agregar tu propio dominio (.com, .net etc.) a tu sitio publicado. Sólo debes configurar los DNS en el panel de control del sitio donde compraste el dominio.
Generando un sitio con VuePress
Como mencioné anteriormente, en Styde contamos con un tutorial sobre VuePress, sin embargo, vamos a dar un breve repaso sobre cómo generar un sitio. 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 "# Despliegue automatizado con VuePress y GitHub Pages" > README.md
¡Excelente! con esto ya tenemos todo lo que necesitamos.
Recuerda que puedes agregar más secciones a tu sitio creando más archivos Markdown (uno por sección).
A continuación, necesitas crear un directorio .vuepress dentro del directorio de tu sitio. Dentro de .vuepress crea un archivo config.js y coloca el siguiente código en su interior:
#
module.exports = {
title: 'Mi sitio en GitHub Pages con VuePress',
description: 'Despliegue automatizado con VuePress y GitHub Pages'
}
Para probar que todo esté funcionando ejecuta el siguiente comando dentro del directorio raíz del sitio:
vuepress dev .
Ahora, si te diriges a http://localhost:8080/ deberías ver una página con un título H1 y el texto Despliegue automatizado con VuePress y GitHub Pages.
En el tutorial sobre VuePress tienes información más detallada sobre las opciones de configuración de VuePress.
Organizando el repositorio
Por defecto, nuestro sitio tiene la siguiente estructura:
#
directorio-raiz-del-sitio/
.vuepress/
config.js
README.md
Vamos a organizar esto. Lo primero que haremos será crear un directorio llamado docs dentro del directorio raíz. Una vez hecho esto, moveremos tanto el directorio .vuepress como README.md y el resto de los archivos de nuestro sitio a este directorio:
#
directorio-raiz-del-sitio/
docs/
.vuepress/
config.js
README.md
Luego, dentro del directorio raíz crearemos tres archivos:
- Un archivo
package.jsondonde pondremos los comandos de Node. - Un archivo
.travis.ymlpara el deploy automatizado con Travis CI. - Un archivo
.gitignore
El resultado debería ser el siguiente:
#
directorio-raiz-del-sitio/
docs/
.vuepress/
config.js
README.md
package.json
.travis.yml
.gitignore
Por el momento vamos a ignorar el archivo .travis.yml y enfocarnos en el archivo package.json.
En el archivo package.json agregaremos lo siguiente:
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
Estos comandos que agregamos en scripts serán ejecutados por Travis CI al momento del deploy. El comando más importante es docs:build o vuepress build docs, que se encargará de generar los archivos estáticos de nuestro sitio.
Como último paso de esta primera parte configuramos nuestro repositorio del código fuente con Git para enlazarlo con el repositorio remoto creado al principio de este tutorial:
git init git add . git commit -m "config vue-press" git remote add origin https://github.com/tu-usuario/repositorio-del-codigo-fuente.git
Con esto terminamos la primera parte de este tutorial donde configuramos todo lo que necesitamos generar un sitio web usando VuePress. En la parte dos veremos cómo realizar todo el proceso de despliegue o deploy con la configuración de Travis CI y GitHub Pages.
Regístrate hoy en Styde y obtén acceso a todo nuestro contenido.
