| Comments

Cómo Crear Tu Blog en GitHub Pages

Qué mejor manera de inaugurar este blog que contando cómo lo he hecho. Github ofrece gratuitamente las Github Pages, las cuales permiten crear páginas webs para tus proyectos, usuario y organizaciones. La mayoría de la gente conoce las páginas de los proyectos, pero también se pueden crear páginas de usuario y de organizaciones.

Crear una GitHub Page

Las páginas de proyectos se pueden crear automáticamente desde los ajustes (settings) de tu proyecto presionando el botón “Automatic Page Generator” y siguiendo los pasos. Esto creará una nueva rama en tu proyecto llamada gh-page la cual se desplegará cada vez que hagas un push en dicha rama. por lo que también puedes crearlas manualmente, sincronizar tu rama master con gh-pages o reemplazar la rama master por gh-pages. De una forma similar se pueden crear páginas para los usuarios y para las organizaciones, en este caso, hay que crear un repositorio llamado username.github.io dónde username es tu nombre de usuario o el nombre de la organización en GitHub. Asegurate de escribir correctamente el username, porque si no no funcionará. Lo que describo en este artículo también es aplicable a las páginas de proyecto, pero nos centraremos en las de usuario y organización.

Las GitHub Pages usan Jekyll, un generador de sitios estáticos simple, con conciencia de blog, en Ruby. Para ello se necesita un directorio donde almacenar los ficheros de texto sin procesar y mediante conversores escupe una página estática completa lista para publicar en tu servidor. Los textos sin procesar utilizan sintaxis Markdown y con ello nos olvidamos de las bases de datos pudiéndonos centrar en el contenido.

Crear el entorno de desarrollo local

Antes de ponerse a subir contenido a las GitHub Pages es recomendable tener un entorno en local para previsualizar los cambios y así evitar hacer push innecesarios y esperar a que se actualice la GitHub Page para ver si lo hemos hecho bien. Para instalar Jekyll necesitamos:

  1. Ruby
  2. RubyGems

Una vez lo tenemos, instalamos la gema jekyll con gem install jekyll, la cual utilizará Maruku para Markdown, pero si quieres puedes utilizar LaTeX, RDiscount o Kramdown, pero no obstante, recomiendo dejar Maruku. El siguiente paso sería crear nuestro blog, para lo cual tenemos 2 opciones, utilizar Jekyll directamente o utilizar un framework como Octopress. Veamos cada una de las opciones.

Crear tu blog con Jekyll

Jekyll nos ofrece la posibilidad de crear el esqueleto de nuestro blog mediante el comando jekyll new username.github.io y creará una carpeta llamada username.github.io, recordad que username es vuestro nombre de usuario u organización de GitHub. Esto genera la estructura siguiente:

.
├── _config.yml
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   └── 2013-12-18-welcome-to-jekyll.markdown
├── css
|   ├── main.css
|   └── syntax.css
└── index.html

Luego podemos ir creando más carpetas y ficheros, pero estos son los básicos para empezar:

  • _congi.yml: almacena los datos de configuración. Muchas de estas opciones pueden ser especificadas desde la linea de comandos, pero es más fácil especificarlas aquí así no tienes que recordarlas.
  • layouts: Son las plantillas Liquid que envuelven los artículos. Las layouts se eligen en cada artículo mediantes la información preeliminar en YAML. El tag se usa para inyectar el contenido en la página web.
  • _posts: Aqí se encuentra el contenido dinámico, por así decirlo. El formato de estos archivos es importante, y debe seguir el formato: año-mes-día-título.MARKUP. Los enlaces permanentes se pueden personalizar para cada artículo, pero la fecha y el lenguaje de marcado están determinados únicamente por el nombre del archivo.

Con esto es suficiente para empezar a crear tu blog, pero puedes aprender más sobre plantillas, enlaces permanentes, paginación y plugins leyendo la documentación de Jekyll.

Crear tu blog con Octopress

Si no queremos empezar desde cero creando nuestras propias plantillas HTML, CSS y Javascript, podemos utilizar Octopress, un framework de blogs para hackers. Octopress viene con:

  • Una plantilla HTML5 semántico
  • Un diseño mobile first responsive
  • Construido con soporte a para Twitter, Google Plus One, comentarios Disqus, Pinboard, Delicious y Google Analytics
  • Una fácil estrategia de despliegue usando Github Pages o Rsync
  • Construido en apoyo a los servidores POW y Rack
  • Tematización fácil con Compass y Sass
  • Un resaltado de sintaxis Beautiful Solarized

Además existen plugins creados por Octopress o por la comunidad de Jeklly con algunas mejoras. Puedes consultar el listado de plugins si quieres conocerlos.

Para empezar con Octupus debes comprobar que tienes Ruby 1.9.3 o superior, puedes comprobarlo escribiendo en la consola ruby --version. Una vez comprabdo ejecutamos los siguientes pasos:

  • Clonamos el repositorio: <div> 
    git clone git://github.com/imathis/octopress.git username.github.io

</div>

  • Instalamos las dependencias: <div> 
    gem install bundler
rbenv rehash  # Si usas rbenv, rehash para poder ejecutar el comando bundle
bundle install

</div>

  • Instalar la plantilla por defecto: <div> 
    rake install

</div>

Plantillas Octopress

Si queremos instalar una plantilla diferente a la que viene por defecto puedes echar un ojo a lista de plantillas en Opthemes e instalarla siguiend estos pasos:

git clone GIT_URL .themes/THEME_NAME
rake install['THEME_NAME']
rake generate

Personalmente prefiero incluir las themes como submodulos, pero tened en cuenta que gh-pages no incluye módulos de manera recursiva, únicamente los de primer nivel, así que si la template tiene submódulos no podréis incluirla como submódulo puesto que los submódulos de la template no se instalarán al desplegarla como gh-pages.

git submodule add GIT_URL .themes/THEME_NAME
rake install['THEME_NAME']
rake generate

Desplegar en GitHub

Una vez que tenemos una primera versión de nuestro blog podemos desplegarlo en GitHub. Recuerda que primero has de crear el repositorio con nombre username.github.io. Una vez que lo tienes tendrás que configurar tu clon de Octopress para que puedas hacer los commits a tu repositorio. Para ello exite el comando, el cual te preguntará por la url de tu repositorio y configurará todo lo necesario para usar tu blog como GitHub Page.

rake setup_github_pages

Este comando realiza lo siguiente:

  1. Solicita la url de tu repositorio (HTTP o SSH)
  2. Cambia el nombre del puntero remoto imathis/octopress de origen a octopress
  3. Añade tu repositorio Github Pages como origin
  4. Cambia la rama activa de master a source
  5. Configura la url de tu blog de ​​acuerdo a tu repositorio
  6. Configura de una rama master en el directorio _deploy para el despliegue

Una vez configurado el entorno para trabajar con GitHub Pages podemos previsualizar el resultado ejecutando el comando:

rake preview

Y cuando hemos comprobado que está todo listo para subirlo a GitHub debemos generar el contenido estático y desplegarlo:

rake generate
rake deploy

Y no olvides subir el código fuente de tu blog:

git add .
git commit -m 'My new GitHub Page'
git push origin source

Tu primer post

Ahora que tienes el entorno configurado en local y delplegado en GitHub es hora de escribir tu primer post. Todos los post se encuentan en la carpeta _posts y deben tener el siguiente formato aaaa-mm-dd-title.MARKUP, donde MARKUP es la extensión del formato elegido, en nuestro caso será md. El formato del nombre del fichero es requerimiento de Jekyll, así que a cumplirlo a rajatabla.

Si estás usando Octopres los post se encuentran en source/_posts y puedes automatizar la creación de nuevos artículos usando el sigueinte comando:

rake new_post["title"]

El contenido será renderizado el motor de markup que hayas elegido, pero adicionalmente dispones de todas las características de las templates liquid descritas en la documentación de Jekyll.

Puedes definir el separador del estracto usando la variable de configuración excerpt_separator, en caso de estar usando Octopress el separador por defecto es: <!-- more -->.

Comments