Acerca de GitHub Pages y Jekyll

Nota:

Aunque la gema github-pages sigue siendo compatible con algunos flujos de trabajo, GitHub Actions es ahora el enfoque recomendado para implementar y automatizar sitios de GitHub Pages.

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.

Windows no tiene soporte oficial para Jekyll. Para obtener más información, consulte 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 AUTOTITLE.

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 . 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 o
Comienzan por , o
Terminan con
Se excluyen por el ajuste en tu archivo de configuración

Si quiere que Jekyll procese cualquiera de estos archivos, puede usar la configuración en su 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 a una publicación o página para agregar los metadatos de referencias del repositorio al sitio. Para más información, consulta la sección "Uso" 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 manualmente un tema al sitio. Para obtener más información, consulte Temas compatibles en el sitio de GitHub Pages y Agregar un tema al sitio de GitHub Pages mediante 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.

Plugins

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 obtener más información, consulte los plugins en la documentación de Jekyll.

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

Puedes habilitar plugins adicionales agregando la gema del plugin a la configuración correspondiente en tu archivo. 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.

Sugerencia

Puedes asegurarte de que usas la versión más reciente de todos los complementos si mantienes actualizada la gema de GitHub Pages. Para obtener más información, consulte AUTOTITLE y Versiones de dependencia en el sitio de GitHub Pages.

GitHub Pages no puede compilar sitios mediante plugins no compatibles. Si quieres 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 obtener más información sobre el resaltado de sintaxis, consulta AUTOTITLE.

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, en lugar de ello se usará Rouge como reemplazo. 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 . Para más información, consulta AUTOTITLE.

Nota:

Rouge solo reconoce identificadores de lenguaje en minúsculas para bloques de código delimitados. Para obtener una lista de los lenguajes compatibles, consulta Lenguajes.

Si quieres usar otro resaltador, como highlight.js, debes deshabilitar el resaltado de sintaxis de Jekyll mediante la actualización del archivo 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 del proyecto.

rougify style github > style.css

Construyendo tu sitio localmente

Si estás publicando 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 más información, consulta Probar el sitio de GitHub Pages localmente con Jekyll.