Acerca de las Páginas de GitHub y Jekyll

Acerca de Jekyll

Jekill es un generador de sitio estático con soporte incorporado para Páginas de GitHub 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 obtener más información, consulta Jekyll.

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

Recomandamos usar Jekyll con Páginas de GitHub. 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 obtener más información, consulta la sección "Acerca dePáginas de GitHub".

Configurando Jekyll en tu sitio Páginas de GitHub

Puedes configurar la mayoría de los parámetros de Jekyll, como los temas y los plugins del sitio, al editar tu archivo _config.yml. Para obtener más información, consulte "Configuración" en la documentación de Jekyll.

Algunos parámetros de configuración no pueden cambiarse para los sitios Páginas de GitHub 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:

están situados en una carpeta denominada /node_modules o /vendor
comienza con _, ., o #
termina con ~
están excluidos por el parámetro exclude en tu archivo de configuración

Si quieres que Jekyll procese cualquiera de estos archivos, puedes utilizar el ajuste include en tu 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 la sección "Front Matter" en la documentación de Jekyll.

Puedes añadir site.github a una publicación o página para añadir cualquier metadato de referencias de repositorio a tu sitio. Para obtener más información, consulta "Usar site.github" en la documentación de metadatos de Jekyll.

Temas

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

Puedes agregar un tema a tu sitio manualmente. Para obtener más información, consulta los "temas compatibles" en el sitio de Páginas de GitHub y la sección "Agregar un tema a tu sitio de Páginas de GitHub utilizando Jekyll".

Puedes sobrescribir cualquiera de los valores por defecto de tu tema editando los archivos del tema. Para obtener más información, consulta la documentación de tu tema y "Sobrescribir 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 plugin jemoji te permite usar el emoji con formato GitHub en cualquier página de tu sitio del mismo modo que lo harías en GitHub. Para obtener más información, consulta "Plugins" en la documentación de Jekyll.

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

Puedes habilitar plugins adicionales al agregar la gema del plugin en los ajustes de plugins en tu archivo _config.yml. Para obtener más información, consulte "Configuración" en la documentación de Jekyll.

Para conocer la lista de los plugins soportados, consulta "Versiones de dependencia" en el sitio Páginas de GitHub. Para obtener información de uso de un plugin específico, consulta la documentación del plugin.

Sugerencia: Puedes asegurarte de que estás usando la versión más reciente de todos los plugins al mantener actualizada la gema de Páginas de GitHub. Para obtener más información, consulta "Comprobar tus páginas de GitHub localmente con Jekyll" y "Versiones de dependencia" en el sitio de Páginas de GitHub.

Páginas de GitHub 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 Enterprise Server.

Resaltado de la sintaxis

Para facilitar la lectura de tu sitio, los fragmentos de código se resaltan en los sitios de Páginas de GitHub de la misma manera que se resaltan en GitHub Enterprise Server. Para más información sobre como enfatizar sintaxis en GitHub Enterprise Server, vea "Creando y resaltando bloques de código."

Por defecto, los bloques de código en su sitio serán resaltados por Jekyll. Jekyll utiliza el resaltador de Rouge, compatible con Pygments. Pygments se obsoletizó y no es compatible con Jekyll 4. Si especificas a Pygments en tu archivo _config.yml, se utilizará a Rouge como sustitución. Jekyll no puede usar ningún otro resaltador de sintaxis, y obtendrás una advertencia de compilación de página si especificas otro en tu archivo _config.yml. Para más información, vea "Acerca de los errores de construcción de sitios Jekyll Páginas de GitHub ."

Si quieres usar otro resaltador, como highlight.js, debes desactivar el resaltador de sintaxis de Jekyll actualizando el archivo de tu proyecto _config.yml.

kramdown:
  syntax_highlighter_opts:
    disable : true

Si tu tema no incluye CSS para resaltar la sintaxis, puedes generar la sintaxis de GitHub resaltando CSS y añadirlo a tu archivo style.css de proyecto.

$ rougify style github > style.css

Construyendo tu sitio localmente

Los cambios en tu sitio se publican automáticamente cuando se fusionan con la fuente de publicación de tu sitio. Si quieres pre-visualizar tus cambios primero, puedes hacer los cambios localmente en vez de en GitHub Enterprise Server. Después, prueba tu sitio localmente. Para obtener más información, consulta "Verificar tu sitio de Páginas de GitHub localmente con Jekyll".