11 tips sobre Jekyll

por Natalia Ventre el 21/04/2013 ・ podés leerlo en 5 minutos ・

Jekyll es un generador de sitios estáticos. A partir de una plantilla y de contenido (en formato Markdown) genera archivos HTML. Es también el motor detrás de las páginas de GitHub.

Uso Jekyll desde marzo del 2012, aprendí cómo funciona leyendo la documentación y viendo el código fuente de otros usuarios y buscando con Google soluciones a problemas que fui encontrando.

Personalizar el prompt

Para generar el sitio en Jekyll, hay que usar la terminal y por lo tanto, la quise hacer más divertida.

Como me gustan los gatos, en mi .bash_profile agregué un emoji 1:

export PS1="😺 > \W$ "
export PATH="/usr/local/bin:/usr/local/sbin:~/bin:$PATH"
Jekyll Terminal
Captura de pantalla de una ventana de Terminal corriendo Jekyll.

Incluir un archivo .htaccess

En config.yml teóricamente debería funcionar include: .htaccess, pero no funciona :( En GitHub, encontré la solución de Juev. Crear un archivo llamado htaccess (sin punto al comienzo) con el siguiente contenido:

---
layout: none
permalink: .htaccess
---

Generar un sitemap

Para generar un sitemap para Google usé el plugin Sitemap.xml Generator de Michael Levin. La documentación es muy clara y funciona perfectamente.

Usar : en los títulos

Para usar dos puntos, basta con ponerlo entre comillas. Ej:

title: "Mi título: es tal cosa"

Escapar caracteres en Markdown

Para mostrar un * o _ usar \ para escapar caracteres.

Resaltar sintaxis con Prism

Jekyll resalta la sintaxis con Pygments, no está mal, pero preferí usar el Jekyll Prism Plugin, ya que Prism de Lea Verou funciona muy bien con HTML/CSS/JS (se pueden definir más lenguajes) y me gustaron los estilos por defecto.

Mostrar un extracto

Para mostrar un fragmento del post (por ej. en la home page), se agrega la siguiente línea:

<!--break-->

Snippets de TextExpander

Para la metadata del post y las notas al pie (porque nunca me pude memorizar la sintaxis), uso snippets en TextExpander, ya que los puedo usar en Byword y Sublime Text.

.meta

---
layout: post
title: %fill:name%
description:
---

.fn

[^fn-%fill:name%]

Usar Grunt

Hasta poco estaba generando el sitio con jekyll –server y usando LiveReload para compilar Sass y recargar la ventana del navegador para previsualizar los cambios de contenido y diseño antes de publicar, pero ahora estoy haciendo todo en único paso con Grunt2.

_config.yml

auto: false

Gruntfile.js

'use strict';
var lrSnippet = require('grunt-contrib-livereload/lib/utils').livereloadSnippet;
var mountFolder = function (connect, dir) {
    return connect.static(require('path').resolve(dir));
};

module.exports = function (grunt) {
	grunt.initConfig({
		connect: {
			options:{
				port: 9000
			},
			livereload: {
				options: {
					middleware: function(connect) {
						return [lrSnippet, mountFolder(connect, '_site')]
					}
				}
			}
		},
		sass: {
			dist: {
				files: {
					'css/style.css':'_sass/style.scss'
				},
				options:{
					style: 'compressed'
				}
			}
		},
		watch: {
			sass: {
				files: ['**/*.scss'],
				tasks: ['sass']
			},
			jekyllsources:{
				files: ['_includes/**', '_layouts/**.html', '_posts/**.md', 'css/**.css', '*.html'],
				tasks: 'shell:jekyll'
			},
			livereload: {
				files: ['_site/index.html'],
				tasks: ['livereload']
			}
		},
		shell:{
			jekyll:{
				command: 'jekyll',
				stdout: true
			}
		}
	});

	grunt.loadNpmTasks('grunt-contrib-sass');
	grunt.loadNpmTasks('grunt-regarde');
	grunt.loadNpmTasks('grunt-contrib-connect');
	grunt.loadNpmTasks('grunt-contrib-livereload');
	grunt.loadNpmTasks('grunt-shell');

	grunt.renameTask('regarde', 'watch');

	grunt.registerTask('default', ['livereload-start', 'connect', 'watch']);
};

Sincronizar con Trasmit

El sitio generado por Jekyll está en la carpeta “_site”. Uso Trasmit 3 como cliente de FTP e hice un par de ajustes para facilitarme la publicación:

  • Rules: Para publicar posts rápidamente, en las preferencias agregué una regla para que saltee las carpetas (CSS, JS, font) ya que sólo es necesario volver a subirlas al hacer un cambio en el diseño.
  • Linking: enlacé la carpeta local con la carpeta en el servidor. De esta manera, una vez que navego a la carpeta del servidor, en el panel izquierdo, me muestra la carpeta local.

Con esta configuración, para publicar un nuevo artículo sólo tengo que navegar hasta la carpeta del servidor y presionar el botón Sync.

Incluir un archivo Markdown

Para incluir un archivo en formato Markdown, desde un archivo HTML (por ej. incluir acerda.md en /acerca/index.html):

{% capture foo %}{% include foo.md %}{% endcapture %}
{{ foo | markdownify }}

Conclusión

En el 2009, usando Tumblr llegué a publicar 100 posts, pero sinceramente varios eran basura, desde que estoy usando Jekyll, me estoy enfocando más en escribir y me siento más orgullosa del contenido publicado. Además me resultó sencillo migrar artículos que había escrito anteriormente en otras plataformas.


  1. Zach Holman escribió un artículo divertidísimo Abusing emoji in iOS and your Mac Los emoji sólo se ven en Safari.

  2. ¿Por qué Grunt y no Rake? Como Jekyll está desarrollado en Ruby, tiene más sentido usar Rake que Grunt, pero como soy diseñadora web, me siento más cómoda con una solución basada en JavaScript.

  3. El artículo 15 Secrets of Transmit 4 me resultó muy útil.