Jekyll es una herramienta para crear contenido estático, esto significa que no necesitamos interactuar con ninguna base de datos y que nuestros datos no cambian muy a menudo, algunos ejemplos de contenido son: un currículo, una landing page, un portafolio o nuestro propio blog.

Crear blog en github con jekyll

Repositorio

Para mas información ver jekyll y github-pages

Usando jekyll

Lo primero que tenemos que hacer es instalar algunos paquetes necesarios en nuestro sistema operativo, para este ejemplo usaremos Ubuntu sin embargo para otras configuraciones podemos ver aquí.

Si no queremos instalar ruby y jekyll y solo queremos correr el proyecto, podemos usar docker, para ello podemos leer el README del repositorio

sudo apt-get install ruby-full build-essential zlib1g-dev
sudo gem install jekyll bundler # No debería usar sudo, pero es para simplificar la explicación

Ahora que nuestro sistema operativo tiene todo lo necesario para funcionar, vamos a crear un proyecto con jekyll que va a generar la minima estructura necesaria.

# --force sobre-escribe la raíz ya que usamos .
# jekyll new myBlog  #  el comportamiento normal es un nombre de proyecto
> jekyll new myBlog
> cd myBlog/

.
├── README.md
├── 404.html
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _posts
│   └── 2020-05-01-welcome-to-jekyll.markdown
├── about.markdown
└── index.markdown

Para correr localmente nuestro proyecto debemos ejecutar los siguientes comandos bundle update, bundle exec jekyll serve

En este punto podemos ver nuestra pagina y una lista de publicaciones, por defecto jekyll provee un diseño y una estructura. Vamos a crear nuestra propia estructura y vamos a tratar los conceptos más importantes en jekyll.

Front Matter

Front Matter es la manera en que jekyll nos permite agregar variables y meta tags a nuestros archivos markdown, por ejemplo si vemos nuestro index.markdown, contiene el siguiente fragmento, el cual nos dice que todo el contenido va cargar a partir de una plantilla html llamada home, esta plantilla viene por defecto con nuestra instalación.

---
layout: home
---

Podemos agregar cualquier variable que deseemos, sin embargo existen unas predefinidas

Layouts

Un layout es una plantilla html, como lo mencionamos anteriormente jekyll genera una por defecto llamada home, ahora vamos a crear una propia llamada default, para eso debemos crear un directorio en la raíz llamado _layouts.

<!-- _layouts/default.html -->

<!doctype html>
<html>

<head>
    <meta charset="utf-8">
    <title>{{ page.title }}</title>
</head>

<body>
    <!-- include es explicado más abajo -->
    {% include navigation.html %}
    <section>
        <div>
            {{ content }}
        </div>
    </section>
</body>

</html>

En este momento tenemos una plantilla en donde usamos el motor de template liquid en donde encontramos los liquid objects { { ... } } y las variables content, muchas variables las podemos definir desde un archivo o podemos acceder a alguna global como page.title, la cual se encuentra en _config.yml. Para visualizar nuestro nuevo templete solo debemos usarlo y para eso modificamos el fragmento en el archivo index y en about: layout: default.

includes y data files

Los includes son archivos html que nos sirven para separar nuestro código de una manera más ordenada y donde cada archivo tiene una sola responsabilidad, algunos ejemplos que podemos agregar son el header, el footer o la navegación. Vamos a crear una carpeta en la raíz llamada _includes y vamos a crear el archivo navigation.

<!-- _includes/navigation.html -->

<nav>

    {% for item in site.data.navigation %}
    <div class="navbar-item">
        <a href="{{site.baseurl}}{{ item.link }}">
            {{ item.name }}
        </a>
    </div>
    {% endfor %}

</nav>

En este archivo vamos a construir una navegación con las entradas que tenemos por el momento que son home (index.markdown) y about (about.markdown). Estamos construyendo a partir de liquid tag { % ... % } dentro podemos usar condicionales o iteraciones en este caso vamos a recorrer todas las entradas de nuestro data ( site.data.<file> ), el cual es la lista de todas nuestras rutas, debemos crear entonces la carpeta _data y dentro el archivo navigation.yml.

# _data/navigation.html

- name: Home
  link: /                # index.markdown
- name: About
  link: /about.markdown
- name: Blog
  link: /blog.html       # Podemos usar md o html

Posts

Para complementar nuestro código vamos a crear un archivo html (hasta el momento hemos usado markdown) para listar todos nuestros post, que se encuentran en la carpeta _posts.

Nuestros archivos pueden ser .html, .markdown o .md, sin embargo dentro de un archivo markdown podemos usar html

<!-- blog.html -->
---
layout: default
title: Blog
---
<h1>Latest Posts</h1>

<ul>
  {% for post in site.posts %}
    <li>
      <h2><a href="{{site.baseurl}}{{ post.url }}">{{ post.title }}</a></h2>
      {{ post.excerpt }}
    </li>
  {% endfor %}
</ul>

Como nos podemos dar cuenta cuando generamos nuestro proyecto en jekyll se genero automáticamente un archivo dentro de la carpeta _posts que sigue la siguiente convención y es obligatorio que se nombren de esta manera YYYY-MM-DD-title.markdown, además en el archivo podemos ver que es importante usar el Front Matter, ya que vamos a tener unas meta tag que permiten buscar, filtrar o manipular nuestros post.

---
layout: post
title:  "Welcome to Jekyll!"
date:   2020-05-01 16:19:34 -0500
categories: jekyll update
---

Assets

Los assets son todos los recursos como css, javascript o imágenes que podemos usar, hasta el momento nuestra pagina no ha usado ningún estilo o imagen, y para esto debemos crear la carpeta assets y dentro de ella tres carpetas más css, js e images.

Para agregar estilos también debemos tener una carpeta llamada _sass, en donde vamos a agregar lo que deseemos, como mínimo debe existir un archivo que usualmente es nombrado main.scss pero puede tener cualquier nombre y se debe importar en css/styles.scss

// assets/css/styles.scss

@charset "utf-8"
@import "main"

// _sass/main.scss
// podemos agregar cualquier estilo o importar otros archivos
.current {
  color: green;
}

y finalmente para usarlo debemos agregalo en nuestro head, en este caso en _layouts/default.html

<head>
  <link rel="stylesheet"
          href="/code-of-toth/assets/css/styles.css">
</head>

De esta manera ya sabemos como agregar por nosotros mismos estilos a nuestro blog, sin embargo no todos tienen el conocimiento para empezar a agregar css y generar un diseño agradable, es por esto que podemos utilizar gemas que se encarguen de generar todos estos estilos como el que venia por defecto con el proyecto minima, para cambiar un tema debemos hacelo desde _config.yml y agregarla en el Gemfile.

La manera mas fácil es comenzar nuestro proyecto a partir de un tema, clonamos el repositorio que más nos llame la atención

Themes

Para entender un poco mejor como funcionan los temas vamos a usar el framework de css bulma (parecido a bootstrap pero más liviano), para darle estilo a nuestro proyecto nosotros mismos.

primero debemos descargar bulma y guardar todo el contenido sass en nuestra carpeta _sass.

 .
  ├── base
  ├── components
  ├── elements
  ├── form
  ├── grid
  ├── layout
  └── utilities

Debemos importar estas carpetas y para eso creamos en el mismo directorio un archivo llamado bulma.sass.

// _sass/bulma.scss

@charset "utf-8"

@import "utilities/_all"
@import "base/_all"
@import "elements/_all"
@import "form/_all"
@import "components/_all"
@import "grid/_all"
@import "layout/_all"

Ahora debemos importar este archivo en css/main.scss y usarlo en nuestro head.

// assets/css/main.scss

@charset "utf-8"
@import "bulma"

<head>
  <link rel="stylesheet"
          href="/code-of-toth/assets/css/main.css">
</head>

Para finalizar debemos comenzar a explorar las clases y componentes de bulma para familiarizarnos, podemos ver el ejemplo terminado en el repositorio, en la rama gh-pages.

Si queremos alojar nuestro sitio en github podemos ver: Github pages