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.
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-sitioLuego inicia Jekyll con los comandos que ves a continuación:
cd new mi-sitio
bundle exec jekyll serve --livereloadFinalmente, 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 serveConfiguració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..4Esta es la lista completa de opciones de Kramdown que podrás configurar:
| Elemento | Soporte |
|---|---|
| auto_id_prefix | Prefijo usado para generar automáticamente los IDs de los encabezados. |
| auto_id_stripping | Eliminar el formato de los encabezados al generar los IDs automáticos. |
| auto_ids | Generación automática de IDs para las cabeceras. |
| coderay_bold_every | Definir la frencuencia con la que un número de línea se mostrará en negrita en los bloques de código. |
| coderay_css | Definir cómo se mostrarán los estilos de los bloques de código. |
| coderay_default_lang | Lenguaje por defecto de los bloques de código. |
| coderay_line_number_start | Valor inicial para los número de línea de los bloques de código. |
| coderay_line_numbers | Define si se mostrarán los números de línea y cómo se mostrarán en los bloques de código. |
| coderay_tab_width | Tamaño de la tabulación en los bloques de código. |
| coderay_wrap | Define cómo se envolverán los bloques de código. |
| enable_coderay | Usar CodeRay para el resaltado de sintaxis. |
| entity_output | Define cómo se muestran las entidades. |
| footnote_backlink | Define el texto que se usará para los enlaces de las anotaciones al pie de página. |
| footnote_backlink_inline | Define si los enlaces de las anotaciones del pie de página deben aparecer el línea. |
| footnote_nr | Número de la primera anotación al pie de página. |
| gfm_quirks | Agregar peculiaridades de GitHub GFM. |
| hard_wrap | Interpretar los saltos de línea literalmente. |
| header_offset | Offset de los encabezados. |
| html_to_native | Convertir HTML a elementos nativos. |
| line_width | Ancho de línea máximo que se usará al mostrar los documentos. |
| link_defs | Enlaces de definiciones predefinidos. |
| math_engine_opts | Establecer el motor usado para la sitnaxis de las operaciones matemáticas. |
| parse_block_html | Procesar la sintaxis Kramdown definida en el interior de los bloques y etiquetas HTML. |
| parse_span_html | Procesar la sintaxis Kramdown en el interior de las etiquetas span. |
| smart_quotes | Definir automáticamente los nombres de las entidades HTML en las citas. |
| syntax_highlighter | Establecer el resaltador de sintaxis que se utilizará. |
| syntax_highlighter_opts | Establecer las opciones del resaltador de sintaxis. |
| toc_levels | Definir el nivel máximo de profundidad que se usará en las tablas de contenido. |
| transliterated_header_ids | Transcribir el texto de las cabeceras antes de generar los IDs. |
| transliterated_header_ids | Transcribir el texto de las cabeceras antes de generar los IDs. |
| typographic_symbols | Definir 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:
| Elemento | Soporte | Notas |
|---|---|---|
| Encabezados | Sí | |
| Párrafos | Sí | |
| Saltos de línea | Sí | Puedes usar una barra invertida \ para saltar de línea en luegar de los dos espacios en blanco. |
| Negrita | Sí | |
| Cursiva | Sí | |
| Citas | Sí | |
| Listas ordenadas | Sí | |
| Listas no ordenadas | Sí | |
| Código | Sí | |
| Línea horizontal | Sí | |
| Enlaces | Sí | |
| Imágenes | Sí | |
| HTML | Sí | Desactivado por defecto. |
| Tablas | Sí | |
| Bloques de código avanzados | Sí | |
| Resaltado de sintaxis | Sí | Debes 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é | Sí | |
| IDs de cabecera | Sí | |
| Listas de definiciones | Sí | |
| Texto tachado | Sí | Podrás usar tanto ~~dos guiones ondulados~~ como ~uno solo~. |
| Listas de tareas | Sí | |
| Emojis (copiar y pegar) | Sí | |
| Emojis (shortcodes) | No | No están soportados por defecto, pero puedes usar Jemoji en su lugar. |
| Enlaces automáticos | Sí | |
| Deshabilitar enlaces automáticos | Sí |
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:
| Elemento | Markdown | HTML | Resultado |
|---|---|---|---|
| Abreviaturas | | | 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:
- Web: Accede a la web de Jekyll
- Repositorio: Accede al repositorio de Jekyll
- Documentación: Consulta la documentación de Jekyll
👋 Hola! Soy Edu, me encanta crear cosas y he redactado este tutorial. Si te ha resultado útil, el mayor favor que me podrías hacer es el de compatirlo en Twitter.
Sígueme en Twitter para estar al día con mi contenido. 😊
