Acerca de las Páginas de GitHub y Jekyll

Jekyll es un generador de sitios estáticos con soporte integrado para GitHub Pages.

¿Quién puede utilizar esta característica?

GitHub Pages is available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub’s plans.

GitHub Pages now uses GitHub Actions to execute the Jekyll build. When using a branch as the source of your build, GitHub Actions must be enabled in your repository if you want to use the built-in Jekyll workflow. Alternatively, if GitHub Actions is unavailable or disabled, adding a .nojekyll file to the root of your source branch will bypass the Jekyll build process and deploy the content directly. For more information on enabling GitHub Actions, see Managing GitHub Actions settings for a repository.

En este artículo

Acerca de Jekyll

Jekill es un generador de sitio estático con soporte incorporado para GitHub Pages y un proceso de construcción simplificado. Jekyll toma los archivos Markdown y HTML y crea un sitio web estático completo en función de la opción de diseño. Jekyll soporta Markdown y Liquid, un lenguaje de plantillas que carga contenido dinámico en tu sitio. Para más información, vea Jekyll.

Jekyll no está oficialmente admitido por Windows. Para más información, consulta Jekyll en Windows en la documentación de Jekyll.

Recomandamos usar Jekyll con GitHub Pages. Si lo prefieres, puedes usar otros generadores de sitio estático o personalizar tu propio proceso de compilación localmente o en otro servidor. Para más información, consulta Acerca de GitHub Pages.

Configurando Jekyll en tu sitio GitHub Pages

Puedes configurar la mayoría de los valores de Jekyll, como los temas y los complementos del sitio, mediante la edición del archivo _config.yml. Para más información, consulta Configuración en la documentación de Jekyll.

Algunos parámetros de configuración no pueden cambiarse para los sitios GitHub Pages sites.

lsi: false
safe: true
source: [your repo's top level directory]
incremental: false
highlighter: rouge
gist:
  noscript: false
kramdown:
  math_engine: mathjax
  syntax_highlighter: rouge

De manera predeterminada, Jekyll no compila archivos o carpetas que:

  • Se encuentran en una carpeta denominada /node_modules o /vendor
  • Comienzan por _, . o #
  • Terminan con ~
  • Se excluyen mediante el valor exclude del archivo de configuración

Si quiere que Jekyll procese cualquiera de estos archivos, puede usar el valor include del archivo de configuración.

Texto preliminar

Para configurar variables y metadatos, tales como el título y diseño, de una página o publicación en tu sitio, puedes agregar YAML front matter a la parte superior de cualquier archivo Markdown o HTML. Para obtener más información, consulta "Texto preliminar" en la documentación de Jekyll.

Puede agregar site.github a una publicación o página para agregar los metadatos de referencias del repositorio al sitio. Para más información, consulta Uso de site.github en la documentación de metadatos de Jekyll.

Temas

Puedes agregar un tema de Jekyll a tu sitio de GitHub Pages para personalizar la apariencia de tu sitio. Para más información, consulta Temas en la documentación de Jekyll.

Puede agregar un tema compatible al sitio en GitHub. Para obtener más información, consulta Temas admitidos en el sitio de GitHub Pages e Incorporación de un tema al sitio de GitHub Pages mediante Jekyll.

Para usar cualquier otro tema de Jekyll de código abierto hospedado en GitHub, puedes agregar el tema manualmente. Para más información, consulta los temas hospedados en GitHub y Agregar un tema a tu sitio de Páginas de GitHub con Jekyll.

Puedes sobrescribir cualquiera de los valores por defecto de tu tema editando los archivos del tema. Para más información, consulta la documentación del tema e Invalidación de los valores predeterminados del tema en la documentación de Jekyll.

Complementos

Puedes descargar o crear plugins Jekyll para ampliar la funcionalidad de Jekyll para tu sitio. Por ejemplo, el complemento jemoji le permite usar emoji de estilo GitHub en cualquier página del sitio de la misma manera que lo haría en GitHub. Para más información, consulta Complementos en la documentación de Jekyll.

GitHub Pages usa plugins que están habilitados por defecto y no pueden estar inhabilitados:

Puedes habilitar complementos adicionales agregando la gema del complemento al valor plugins del archivo _config.yml. Para más información, consulta Configuración en la documentación de Jekyll.

Para obtener una lista de los complementos admitidos, consulta Versiones de dependencia en el sitio de GitHub Pages. Para obtener información de uso de un plugin específico, consulta la documentación del plugin.

Tip

Puedes asegurarte de que usas la versión más reciente de todos los complementos si mantienes actualizada la gema de GitHub Pages. Para más información, consulta Probar tu sitio de Páginas de GitHub localmente con Jekyll y Versiones de dependencia en el sitio de GitHub Pages.

GitHub Pages no puede compilar sitios mediante plugins no compatibles. Si deseas usar plugins no compatibles, genera tu sitio localmente y luego sube los archivos estáticos del sitio a GitHub.

Resaltado de sintaxis

Para facilitar la lectura de tu sitio, los fragmentos de código se resaltan en los sitios de GitHub Pages de la misma manera que se resaltan en GitHub. Para más información sobre el resaltado de sintaxis en GitHub, consulta Crear y resaltar bloques de código.

Por defecto, los bloques de código en su sitio serán resaltados por Jekyll. Jekyll usa el resaltado Rouge, que es compatible con Pygments. Si especificas Pygments en el archivo _config.yml, se usará Rouge como alternativa en su lugar. Jekyll no puede usar ningún otro resaltador de sintaxis, por lo que recibirás una advertencia de compilación de página si especificas otro en el archivo _config.yml. Para más información, consulta Acerca de los errores de compilación para sitios de Páginas de GitHub.

Si quieres usar otro resaltador, como highlight.js, debes deshabilitar el resaltado de sintaxis de Jekyll mediante la actualización del archivo _config.yml del proyecto.

kramdown:
  syntax_highlighter_opts:
    disable : true

Si en el tema no se incluye CSS para el resaltado de sintaxis, puede generar CSS de resaltado de sintaxis de GitHub y agregarlo al archivo style.css del proyecto.

rougify style github > style.css

Construyendo tu sitio localmente

Si publicas desde una rama, los cambios en tu sitio se publican automáticamente cuando se fusionan con la fuente de publicación de tu sitio. Si publicas desde un flujo de trabajo de GitHub Actions personalizado, los cambios se publican cuando se desencadene el flujo de trabajo (normalmente mediante una inserción en la rama predeterminada). Si quieres previsualizar tus cambios primero, puedes hacer los cambios localmente en vez de en GitHub. Después, prueba tu sitio localmente. Para obtener más información, vea «Probar tu sitio de Páginas de GitHub localmente con Jekyll».