Skip to main content

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.

GitHub Pages se encuentra disponible en los repositorios públicos con GitHub Free y con GitHub Free para las organizaciones, y en los repositorios públicos y privados con GitHub Pro, GitHub Team, GitHub Enterprise Cloud, y GitHub Enterprise Server. Para más información, vea "Productos de GitHub".

Solucionar problemas de errores de compilación

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

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

  • Estás usando plugins no compatibles. Para obtener más información, consulta "Acerca de GitHub Pages y Jekyll".
  • Tu repositorio ha excedido nuestros límites de tamaño del repositorio. Para obtener más información, consulta "¿Cuál es mi cuota de disco?".
  • Has cambiado la configuración source en el archivo _config.yml. Si publicas 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 haber corregido los errores, desencadena otra compilación insertando los cambios en la rama de origen del sitio (si publicas desde una rama) o desencadenando el flujo de trabajo de GitHub Actions personalizado (si publicas 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 problemas, 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.

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 de Liquid" 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 en el directorio _includes.

Este error significa que tu código hace referencia a un archivo simbólico que no existe en los archivos publicados de tu sitio.

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 es un enlace simbólico, copia o mueve los archivos en el 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 obtener más información, consulta "Acerca 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 obtener más información, consulta "Establecimiento de un procesador Markdown para el sitio de GitHub Pages mediante 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:

  • Usar Git para revertir o deshacer la eliminación. Para obtener más información, consulta "git-revert" en la documentación de Git.
  • Crea una carpeta docs nueva en la raíz de tu repositorio en la rama que elegiste para ser tu origen de publicación y agrega los archivos de origen de tu sitio a la carpeta. Para obtener más información, consulta "Creación de archivos".
  • Cambiar tu fuente de publicación. Para obtener más información, consulta "Configuración de un origen de publicación de GitHub Pages".

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 obtener más información, consulta "Edición de archivos".

Este error significa que tu sitio incluye un enlace simbólico (symlink) que no existe en los archivos publicados de tu sitio. Para obtener más información sobre los vínculos simbólicos, consulta "Vínculo simbólico" en Wikipedia.

Para solucionar el problema, determina si el archivo en el mensaje de error se utiliza para compilar tu sitio. De lo contrario, o si no quieres que el archivo sea un enlace simbólico, elimina el archivo. Si el archivo de enlace simbólico se necesita para compilar tu sitio, asegúrate de que el archivo o el directorio al que hace referencia el enlace simbólico esté en los archivos publicados de tu sitio. Para incluir recursos externos, considera la posibilidad de usar git submodule o un administrador de paquetes de terceros como Bower. Para obtener más información, consulta "Uso de submódulos con GitHub Pages".

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 de iteración" 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 de Liquid" 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 de Liquid" 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, 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 GitHub Pages y Jekyll".