Solucionar problemas de errores de compilación de Jekyll para sitios de Páginas de GitHub

Puedes usar los mensajes de error de compilación de Jekyll para solucionar los problemas de tu sitio de 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

Solucionar problemas de errores de compilación

Si Jekyll encuentra un error al compilar tu sitio de GitHub Pages localmente o en GitHub Enterprise Cloud, puede usar los mensajes de error para solucionar los problemas. Para más información sobre los mensajes de error y cómo verlos, consulta Acerca de los errores de compilación para sitios de Páginas de GitHub.

Si recibiste un mensaje de error genérico, revisa los problemas comunes.

  • Estás usando plugins no compatibles. Para más información, consulta Acerca de las Páginas de GitHub y Jekyll
  • Tu repositorio ha excedido nuestros límites de tamaño del repositorio. Para más información, consulta Acerca de los archivos grandes en GitHub
  • Has cambiado el valor de configuración source en el archivo _config.yml. Si publica el sitio desde una rama, GitHub Pages reemplaza este parámetro durante el proceso de compilación.
  • Un nombre de archivo en tus archivos publicados contiene dos puntos (:), los cuales no se admiten.

Si recibiste un mensaje de error específico, revisa la información de solución de problemas para el mensaje de error que aparece a continuación.

Después de corregir los errores, desencadene otra compilación insertando los cambios en la rama de origen del sitio (si está publicando desde una rama) o desencadenando el flujo de trabajo personalizado GitHub Actions (si está publicando con GitHub Actions).

Error de archivo de configuración

Este error significa que el sitio no se pudo compilar porque el archivo _config.yml contiene errores de sintaxis.

Para solucionar el problema, asegúrate de que el archivo _config.yml sigue estas reglas:

  • Utiliza espacios en vez de tabulaciones.
  • Incluya un espacio después de : para cada par clave-valor, como timezone: Africa/Nairobi.
  • Utiliza únicamente caracteres con codificación UTF-8.
  • No puede contener caracteres especiales, como : o title: "my awesome site: an adventure in parse errors".
  • En el caso de los valores de varias líneas, use | para crear líneas y > para omitir las líneas nuevas.

Para identificar los errores, puedes copiar y pegar el contenido del archivo YAML en un linter YAML, como el validador YAML.

Note

If your repository contains symbolic links, you will need to publish your site using a GitHub Actions workflow. For more information about GitHub Actions, see "Documentación de GitHub Actions."

La fecha no es una fecha válida

Este error significa que una de las páginas de tu sitio incluye una fecha inválida.

Para solucionar el problema, busca el archivo en el mensaje de error y los diseños del archivo para encontrar llamadas a cualquier filtro Liquid relacionado con la fecha. Asegúrate de que todas las variables pasadas en los filtros de Liquid relacionados con la fecha contengan valores en todos los casos y nunca pases nil ni "". Para obtener más información, consulta Filtros en la documentación de Liquid.

El archivo no existe en el directorio includes

Este error significa que tu código hace referencia a un archivo que no existe en el directorio _includes.

Para solucionar problemas, busque el archivo en el mensaje de error de include para ver dónde ha hecho referencia a otros archivos, como {% include example_header.html %}. Si cualquiera de los archivos a los que has hecho referencia no está en el directorio _includes, copia o mueve los archivos al directorio _includes.

El archivo no está correctamente codificado en UTF-8

Este error significa que usaste caracteres no latinos, como 日本語, sin decirle al equipo que esperara estos símbolos.

Para solucionar el problema, aplica la codificación UTF-8 agregando la siguiente línea al archivo _config.yml:

encoding: UTF-8

Lenguaje de resaltado inválido

Este error significa que especificaste cualquier resaltador de sintaxis diferente de Rouge o Pygments en el archivo de configuración.

Para solucionar el problema, actualiza el archivo _config.yml para especificar Rouge o Pygments. Para más información, consulta Acerca de las Páginas de GitHub y Jekyll.

Fecha de publicación inválida

Este error significa que una publicación en tu sitio contiene una fecha inválida en el nombre de archivo o en el asunto de la parte delantera de YAML.

Para solucionar el problema, asegúrate de que todas las fechas tengan el formato de AAAA-MM-DD HH:MM:SS para UTC y que sean fechas del calendario reales. Para especificar una zona horaria con un desplazamiento UTC, utiliza el formato AAAA-MM-DD HH:MM:SS +/-TTTT, como 2014-04-18 11:30:00 +0800.

Si especificas un formato de fecha en el archivo _config.yml, asegúrate de que el formato sea correcto.

Sass o SCSS inválido

Este error significa que tu repositorio contiene un archivo Sass o SCSS con contenido inválido.

Para solucionar el problema, revisa el número de línea incluido en el mensaje de error para el Sass o SCSS inválido. Para ayudar a prevenir errores futuros, instala un limpiador de Sass o SCSS para tu editor de texto favorito.

Submódulo inválido

Este error significa que tu repositorio incluye un submódulo que no se ha iniciado correctamente.

Para resolver problemas, primero decide si quieres utilizar un submódulo, lo cual es un proyecto de Git dentro de otro proyecto de Git; ya que estos a veces se crean por accidente.

Si no quiere usar un submódulo, elimínelo y reemplace RUTA-DEL-SUBMÓDULO con la ruta del submódulo:

git submodule deinit PATH-TO-SUBMODULE
git rm PATH-TO-SUBMODULE
git commit -m "Remove submodule"
rm -rf .git/modules/PATH-TO-SUBMODULE

Si quieres usar el submódulo, asegúrate de usar https:// al hacer referencia al submódulo (no http://) y de que el submódulo se encuentre en un repositorio público.

YAML inválido en el archivo de datos

Este error significa que uno de los archivos de la carpeta data contiene YAML no válido.

Para solucionar el problema, asegúrate de que los archivos YAML de la carpeta data sigan estas reglas:

  • Utiliza espacios en vez de tabulaciones.
  • Incluya un espacio después de : para cada par clave-valor, como timezone: Africa/Nairobi.
  • Utiliza únicamente caracteres con codificación UTF-8.
  • No puede contener caracteres especiales, como : o title: "my awesome site: an adventure in parse errors".
  • En el caso de los valores de varias líneas, use | para crear líneas y > para omitir las líneas nuevas.

Para identificar los errores, puedes copiar y pegar el contenido del archivo YAML en un linter YAML, como el validador YAML.

Para obtener más información sobre los archivos de datos de Jekyll, consulta Archivos de datos en la documentación de Jekyll.

Errores de Markdown

Este error significa que tu repositorio contiene errores de Markdown.

Para solucionar el problema, asegúrate de estar usando un procesador Markdown compatible. Para más información, consulta Configurar un procesador Markdown para tu sitio de páginas de GitHub usando Jekyll.

Luego asegúrate de que el archivo del mensaje de error utilice una sintaxis Markdown válida. Para obtener más información, consulta Markdown: Sintaxis de Daring Fireball.

Falta carpeta de docs

Este error significa que has elegido la carpeta docs en una rama como origen de publicación, pero no hay ninguna carpeta docs en la raíz del repositorio de esa rama.

Para solucionar el problema, si tu carpeta docs se movió accidentalmente, trata de volver a mover la carpeta docs a la raíz de tu repositorio en la rama que elegiste como tu origen de publicación. Si la carpeta docs se eliminó accidentalmente, puedes hacer lo siguiente:

Falta submódulo

Este error significa que tu repositorio incluye un submódulo que no existe o no se ha iniciado correctamente.

Para resolver problemas, primero decide si quieres utilizar un submódulo, lo cual es un proyecto de Git dentro de otro proyecto de Git; ya que estos a veces se crean por accidente.

Si no quiere usar un submódulo, elimínelo y reemplace RUTA-DEL-SUBMÓDULO con la ruta del submódulo:

git submodule deinit PATH-TO-SUBMODULE
git rm PATH-TO-SUBMODULE
git commit -m "Remove submodule"
rm -rf .git/modules/PATH-TO-SUBMODULE

Si quieres utilizar un submódulo, inicia el submódulo. Para obtener más información, consulta Submódulos de herramientas de Git en el libro Pro Git.

Este error significa que tienes enlaces permanentes relativos que no son compatibles con GitHub Pages en tu archivo _config.yml.

Los enlaces permanentes son URL permanentes que hacen referencia a una página particular en tu sitio. Los enlaces permanentes absolutos comienzan con la raíz del sitio, mientras que los enlaces permanentes relativos comienzan con la carpeta que contiene la página referenciada. GitHub Pages y Jekyll ya no admiten enlaces permanentes relativos. Para obtener más información sobre los vínculos permanentes, consulta Vínculos permanentes en la documentación de Jekyll.

Para solucionar el problema, quita la línea relative_permalinks del archivo _config.yml y vuelve a formatear los vínculos permanentes relativos del sitio con vínculos permanentes absolutos. Para más información, consulta Editar archivos.

Error de sintaxis en el bucle 'for'

Este error significa que tu código incluye una sintaxis no válida en una declaración de bucle for de Liquid.

Para solucionar el problema, asegúrate de que todos los bucles for en el archivo del mensaje de error tengan una sintaxis adecuada. Para obtener más información sobre la sintaxis adecuada de los bucles for, consulta Etiquetas en la documentación de Liquid.

Etiqueta no cerrada correctamente

Este mensaje de error significa que tu código incluye una etiqueta lógica que no está correctamente cerrada. Por ejemplo, {% capture example_variable %} debe cerrarse mediante {% endcapture %}.

Para solucionar el problema, asegúrate de que todas las etiquetas lógicas en el archivo del mensaje de error estén correctamente cerradas. Para obtener más información, consulta Etiquetas en la documentación de Liquid.

Etiqueta no finalizada correctamente

Este error significa que tu código incluye una etiqueta de salida que no está correctamente finalizada. Por ejemplo, {{ page.title } en lugar de {{ page.title }}.

Para solucionar el problema, asegúrate de que todas las etiquetas de salida en el archivo del mensaje de error finalicen con }}. Para obtener más información, consulta Objetos en la documentación de Liquid.

Error de etiqueta desconocido

Este error significa que tu código contiene una etiqueta de Liquid no reconocida.

Para solucionar el problema, asegúrate de que todas las etiquetas de Liquid en el archivo del mensaje de error coincidan con las variables predeterminadas de Jekyll y que no haya ningún error de escritura en los nombres de las etiquetas. Para obtener una lista de variables predeterminadas, consulta Variables en la documentación de Jekyll.

Los plugins no compatibles son una fuente común de etiquetas no reconocidas. Si usas un plugin no compatible en tu sitio cuando lo generas localmente y subes tus archivos estáticos a GitHub Enterprise Cloud, asegúrate de que el plugin no esté introduciendo etiquetas que no están en las variables predeterminadas de Jekyll. Para obtener una lista de los complementos admitidos, consulta Acerca de las Páginas de GitHub y Jekyll.