Guía Markdown de Jekyll

Jekyll es un generador de sitios web que convierte archivos Makdown en sitios web estáticos.

Jekyll es un generador de sitios web gratuito y open source con el que podrás crear webs estáticas a partir de archivos Markdown.

Acerca de Jekyll

Jekyll está desarrollado con el lenguaje de programación Ruby. Por defecto usa archivos en formato Markdown que se compilarán en archivos HTML, creando un sitio web estático que por su naturaleza tendrá un gran rendimiento. Jekyll es usado por servicios online muy populares como por ejemplo GitHub Pages.

Imagen de Jekyll

Jekyll usa el procesador Markdown Kramdown, que podrás personalizar según tus necesidades. Sin embargo, también podrás configurar Jekyll para usar otro procesador de diferente.

Jekyll usa el sistema de plantillas Liquid para procesar las plantillas. En las plantillas podrás agregar código HTML, código CSS y también variables mediante la sitnaxis {{ variable }}.

Jekyll usa CodeRay para el resaltado de sintaxis de los bloques de código. Jekyll también te permite usar usa serie de filtros y etiquetas.

Jelyll es un generador de sitios ideal para blogs, incluyendo la posibilidad de agregar categorías, posts, permalinks y páginas por defecto. Además, existen herramientas que te permitirán importar contenidos de casi cualquier CMS a Jekyll.

Instalación de Jekyll

Para instalar Jekyll, primero necesitarás instalar Ruby en tu sistema. Luego basta con que inicies la terminal de comandos y ejecutes estos comandos, reemplazando mi-sitio por el nombre de tu proyecto.

gem install bundler jekyll
jekyll new mi-sitio

Luego inicia Jekyll con los comandos que ves a continuación:

cd new mi-sitio
bundle exec jekyll serve --livereload

Finalmente, accede a la URL http://localhost:4000 desde tu navegador para ver el proyecto.

En caso de que quieras que el contenido de tu navegador se refresque automáticamente cuando modifiques una plantilla, usa este comando para iniciar Jekyll:

bundle exec jekyll serve

Configuración de Jekyll

Para cambiar la configuración Markdown de Jekyll debes editar archivo _config.yml, en el que encontrarás diferentes opciones con las que podrás configurar el Kramdown:

kramdown:
  input: GFM
  syntax_highlighter: rouge
  auto_ids: true
  toc_levels: 1..4

Esta es la lista completa de opciones de Kramdown que podrás configurar:

ElementoSoporte
auto_id_prefixPrefijo usado para generar automáticamente los IDs de los encabezados.
auto_id_strippingEliminar el formato de los encabezados al generar los IDs automáticos.
auto_idsGeneración automática de IDs para las cabeceras.
coderay_bold_everyDefinir la frencuencia con la que un número de línea se mostrará en negrita en los bloques de código.
coderay_cssDefinir cómo se mostrarán los estilos de los bloques de código.
coderay_default_langLenguaje por defecto de los bloques de código.
coderay_line_number_startValor inicial para los número de línea de los bloques de código.
coderay_line_numbersDefine si se mostrarán los números de línea y cómo se mostrarán en los bloques de código.
coderay_tab_widthTamaño de la tabulación en los bloques de código.
coderay_wrapDefine cómo se envolverán los bloques de código.
enable_coderayUsar CodeRay para el resaltado de sintaxis.
entity_outputDefine cómo se muestran las entidades.
footnote_backlinkDefine el texto que se usará para los enlaces de las anotaciones al pie de página.
footnote_backlink_inlineDefine si los enlaces de las anotaciones del pie de página deben aparecer el línea.
footnote_nrNúmero de la primera anotación al pie de página.
gfm_quirksAgregar peculiaridades de GitHub GFM.
hard_wrapInterpretar los saltos de línea literalmente.
header_offsetOffset de los encabezados.
html_to_nativeConvertir HTML a elementos nativos.
line_widthAncho de línea máximo que se usará al mostrar los documentos.
link_defsEnlaces de definiciones predefinidos.
math_engine_optsEstablecer el motor usado para la sitnaxis de las operaciones matemáticas.
parse_block_htmlProcesar la sintaxis Kramdown definida en el interior de los bloques y etiquetas HTML.
parse_span_htmlProcesar la sintaxis Kramdown en el interior de las etiquetas span.
smart_quotesDefinir automáticamente los nombres de las entidades HTML en las citas.
syntax_highlighterEstablecer el resaltador de sintaxis que se utilizará.
syntax_highlighter_optsEstablecer las opciones del resaltador de sintaxis.
toc_levelsDefinir el nivel máximo de profundidad que se usará en las tablas de contenido.
transliterated_header_idsTranscribir el texto de las cabeceras antes de generar los IDs.
transliterated_header_idsTranscribir el texto de las cabeceras antes de generar los IDs.
typographic_symbolsDefinir un mapa entre los símbolos tipograficos y los caracteres de salida.

Soporte Markdown

La compatibilidad de Jekyll con Markdown es excelente, soportando todos los elementos de la sintaxis básica de markdown, así como los elementos de la sintaxis extendida, salvo alguna particularidad. A continuación pudes ver la tabla de compatibilidad de Jekyll con Markdown:

ElementoSoporteNotas
Encabezados
Párrafos
Saltos de líneaPuedes usar una barra invertida \ para saltar de línea en luegar de los dos espacios en blanco.
Negrita
Cursiva
Citas
Listas ordenadas
Listas no ordenadas
Código
Línea horizontal
Enlaces
Imágenes
HTMLDesactivado por defecto.
Tablas
Bloques de código avanzados
Resaltado de sintaxisDebes asegurarte de que el resaltador de sintaxis seleccionado es rouge. Puedes comprobarlo en la opción syntax_highlighter del archivo _config.ym.
Notas al pié
IDs de cabecera
Listas de definiciones
Texto tachadoPodrás usar tanto ~~dos guiones ondulados~~ como ~uno solo~.
Listas de tareas
Emojis (copiar y pegar)
Emojis (shortcodes)NoNo están soportados por defecto, pero puedes usar Jemoji en su lugar.
Enlaces automáticos
Deshabilitar enlaces automáticos

Soporte adicional

Jekyll soporta más elementos extra mediante la sintaxis Markdown, aunque no forman parte del estándar habitual. Un ejemplo de ello son las abreviaturas:

ElementoMarkdownHTMLResultado
Abreviaturas
*[HTML]: Hyper Text Markup Language
La especificación HTML es mantenida
por la asociación W3C.
La especificación
<abbr title="Hyper Text Markup Language">HTML</abbr>
es mantenida por la asociación W3C.
La especificación HTML es mantenida por la asociación W3C.

Alternativas a Jekyll

La mejor alternatia a Jekyll que podrás encontrar es Hugo, otro generador de sitios web estáticos que destaca por su velocidad. Además, su compatibilidad con Markdown también es muy buena.

Si lo que quieres es crear la documentación de algún proyecto, tu mejor opción es Docusaurus, que también creará un sitio web a partir de documentos Markdown. Otra opción para este último caso sería MkDocs.

Más información

Si quieres saber más cosas acerca de Jekyll, consulta los siguientes enlaces: