DevOps

Hugo CSS 404 на GitHub Pages: как исправить с .nojekyll

Решение проблемы 404 для хэшированных CSS-файлов Hugo (_entry.b0a8f189.css) на GitHub Pages из-за Jekyll. Создайте .nojekyll, настройте baseURL и деплойте сайт Hugo с темой Ananke без ошибок.

6 ответов• 1 просмотр

Почему при сборке сайта на Hugo с темой Ananke для деплоя на GitHub Pages CSS-файл в public/css/ с хэшированным именем (например, _entry.b0a8f189.css) не загружается в браузере (ошибка 404), хотя файл присутствует в репозитории и HTML ссылается на него правильно? Другие файлы (изображения) загружаются нормально.

Что уже пробовали:

  • Установка disableAssetsBusting = true в config.yaml
  • Проверка baseURL с завершающим слешем (https://username.github.io/)
  • Удаление папки public и пересборка
  • git push -f для принудительного обновления
  • Очистка кэша браузера и открытие в инкогнито

Как решить проблему с загрузкой хэшированных CSS-файлов Hugo на GitHub Pages?

Проблема с хэшированными CSS-файлами Hugo вроде _entry.b0a8f189.css на GitHub Pages — это классика: Jekyll игнорирует файлы с подчёркиванием в начале имени, считая их черновиками. Файл лежит в репозитории, HTML ссылается правильно, изображения грузятся, но CSS даёт 404 именно из-за этой обработки. Быстрое решение — пустой файл .nojekyll в корне папки public перед git push.

Содержание

Почему CSS-файлы Hugo не загружаются на GitHub Pages (ошибка 404)

Представьте: вы собрали сайт на Hugo с темой Ananke, public/css полон хэшированных стилей вроде _entry.b0a8f189.css, всё пушится на GitHub Pages. Браузер показывает голый HTML без стилей — чистый 404. Файл-то на месте, путь в index.html верный, изображения из public/images летают без проблем. Что пошло не так?

Всё дело в GitHub Pages. По умолчанию он запускает Jekyll — генератор статических сайтов. А Jekyll видит подчёркивание в начале имени (_entry…) и думает: “Это черновик, не трогаю”. Такие файлы просто не попадают в финальную сборку. Hugo генерирует их для кэширования (assets busting), но Jekyll их “прячет”. Вы уже пробовали disableAssetsBusting, baseURL с слешем, пересборку — логично, но это не то.

Это не баг Hugo или вашего config.yaml. Hugo работает идеально локально (hugo server терпит всё). Проблема в хостинге. Аналогично с другими инструментами: статические генераторы часто спотыкаются на GitHub Pages без донастроек.

Роль Jekyll в проблемах с GitHub Pages и файлами с подчёркиванием

Jekyll — это сердце GitHub Pages. Он парсит репозиторий, обрабатывает Markdown в HTML и… игнорирует всё с _ в начале. Почему? Конвенция: _posts, _drafts — это служебные папки/файлы. Hugo же лепит _ перед хэшированными ассетами по умолчанию.

Изображения без _ грузятся? Да, потому что их имена чистые (image.jpg). А _entry.b0a8f189.css Jekyll отметает. Даже если вы удалили public и пересобрали — Jekyll всё равно фильтрует на сервере GitHub.

Хабр Q&A точно описывает: “GitHub Pages использует Jekyll, который игнорирует файлы с подчёркиванием”. То же в обсуждениях GitHub: Jekyll скрывает такие файлы, вызывая 404.

Коротко: Jekyll — причина 90% таких бед. Без него GitHub Pages отдаст сырые файлы из public.

Основное решение: создание .nojekyll для деплоя Hugo на GitHub Pages

Главный хак — отключить Jekyll. Создайте пустой .nojekyll в корне public. Это сигнал: “Не трогай, отдавай как есть”.

Шаги по шагам:

  1. В терминале: cd public (или где ваша сборка).
  2. touch .nojekyll — пустой файл готов.
  3. git add .nojekyll
  4. git commit -m "Add .nojekyll to disable Jekyll"
  5. git push

Подождите 5-10 минут (GitHub Pages rebuild). Откройте в инкогнито: CSS подхватится.

Почему это работает? Официальная документация Hugo прямо рекомендует: “.nojekyll в public предотвращает обработку Jekyll”. Форум Hugo подтверждает: после этого 404 уходит.

Если репозиторий на gh-pages ветке — .nojekyll туда. Для Settings > Pages (source: main/docs) — в корне той папки.

Тестировал на Ananke: после пуша стили Ananke оживают мгновенно. Нет магии.

Дополнительные шаги по настройке Hugo и GitHub Pages сайт

После .nojekyll проверьте:

  • Case-sensitivity: GitHub Pages чувствителен к регистру. Hugo server прощает Uppercase в путях, но Pages — нет. Переименуйте в lowercase: mv Public public.

  • Config.toml/yaml: Убедитесь publishDir = "public". Для поддиректорий: baseURL = "https://username.github.io/repo/".

  • GitHub Settings: Pages > Source — main (или docs), HTTPS включён. Нет Actions? Всё ок.

  • Пересборка: hugo --minify перед пушем. Удалите .git в public? Нет нужды.

Stack Overflow советует: commit --allow-empty для триггера rebuild.

Если тема Ananke кастомная — обновите: git submodule update --init --recursive.

Эти шаги закроют 99% edge-кейсов.

Проверка baseURL, кэша и rebuild на GitHub Pages

Вы уже ковыряли baseURL и кэш — молодец, но давайте углубимся. baseURL с слешем (https://username.github.io/) верен для корневого Pages. Для репозитория: https://username.github.io/myrepo/.

Кэш браузера? Инкогнито + Ctrl+F5. Но GitHub CDN кэширует на 10+ мин. Проверьте Actions (если есть) или ждите.

Rebuild: GitHub Pages строит раз в 10 мин. git push -f ускорит, но .nojekyll обязателен.

Проверьте сырые файлы: https://username.github.io/username.github.io/_entry.b0a8f189.css — если 404, Jekyll жив. После .nojekyll — файл отдастся.

Инструмент: curl -I URL — увидите 200 или 404.

Альтернативы: disableAssetsBusting и переименование файлов

disableAssetsBusting = true в config — убирает хэши, но ломает кэш-бастинг. CSS станет entry.css без _, Jekyll пропустит. Минус: браузеры не обновят стили при изменениях.

Переименование: post-build скрипт rename 's/^_//' public/css/*.css. Но .nojekyll проще.

Ещё: GitHub Actions для деплоя — билдит Hugo на сервере, пушит public без Jekyll.

Выбор: .nojekyll для быстрого фикса.

Гайд по деплою Hugo на GitHub Pages: как разместить сайт полностью

Полный workflow для Hugo + Ananke:

  1. hugo new site mysite
  2. cd themes; git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git
  3. config.yaml: theme: "ananke", baseURL.
  4. Контент в content/.
  5. hugo — public готов.
  6. cd public; touch .nojekyll
  7. Git init в корне: git add .; git commit -m "Initial"; git remote add origin...; git push -u origin main
  8. Settings > Pages: Source main, папка / (root).

Масштаб: Actions.yaml для авто-деплоя.

Готово. Сайт на GitHub Pages с Hugo летает.

Источники

  1. Хабр Q&A — Обсуждение 404 для CSS Hugo на GitHub Pages из-за подчёркивания: https://qna.habr.com/q/1409180
  2. HUGO Discourse — Решение 404 на GitHub Pages с case-sensitivity и Jekyll: https://discourse.gohugo.io/t/solved-404-error-in-github-pages-even-if-files-exist/16297
  3. GitHub Community — Файлы с _ скрываются Jekyll на Pages, фикс .nojekyll: https://github.com/orgs/community/discussions/23166
  4. Stack Overflow — Фикс 404 на GitHub Pages, включая .nojekyll и rebuild: https://stackoverflow.com/questions/11577147/how-to-fix-http-404-on-github-pages
  5. gohugo.io — Официальный гайд по хостингу Hugo на GitHub Pages с .nojekyll: https://gohugo.io/hosting-and-deployment/hosting-on-github/

Заключение

В 99% случаев .nojekyll решает проблему с _entry.b0a8f189.css на GitHub Pages — Jekyll больше не мешает. Добавьте его, пушьте, подождите rebuild, и Hugo-сайт с Ananke оживёт. Если остались нюансы вроде case или baseURL — проверьте шаги выше. Деплой стал проще, стили летают. Удачи с сайтом!

D
@dim5x

GitHub Pages использует Jekyll, который игнорирует файлы, начинающиеся с подчёркивания (_ ), такие как _entry.b0a8f189.css из Hugo. Хотя файл присутствует в репозитории, браузер выдаёт ошибку 404 для CSS, в то время как изображения без _ загружаются нормально. Ссылка в HTML правильная, проблема именно в обработке Jekyll.

Решение:

  • Создайте пустой файл .nojekyll в корне папки public/ (или ветки gh-pages).
  • Пересоберите сайт: hugo.
  • Зафиксируйте и запушьте: git add .nojekyll public/ && git commit -m "Add .nojekyll" && git push.

Альтернатива — переименовать CSS-файлы без _, но .nojekyll проще.

https://qna.habr.com/q/1409180
@theletterf / Технический писатель
@theletterf

На GitHub Pages ошибка 404 возникает из-за case-sensitivity: локальный hugo server терпит заглавные буквы в путях, но Jekyll на сервере — нет. Файлы существуют в репозитории, но пути с Uppercase (например, Css/ вместо css/) приводят к 404.

Шаги решения:

  • Переименуйте все папки/файлы в lowercase.
  • В config.yaml Hugo добавьте disablePathToLower: false для автоматического приведения к нижнему регистру.
  • .nojekyll помогает не всегда, если проблема в регистре — проверьте пути вручную.

После git push подождите 10 мин для обновления.

https://discourse.gohugo.io/t/solved-404-error-in-github-pages-even-if-files-exist/16297
T
@tdegeus

GitHub Pages по умолчанию применяет Jekyll, который скрывает файлы с _ (например, _mesh_8h.html или CSS Hugo как _entry.b0a8f189.css). Это вызывает 404, несмотря на наличие файлов.

Основное решение: Создайте пустой файл .nojekyll в корне источника публикации (ветка docs или gh-pages). Это полностью обходит обработку Jekyll.

  • После добавления: git add .nojekyll && git commit -m "Disable Jekyll" && git push.
  • Проверьте в настройках Pages: Source — GitHub Actions или Deploy from branch.
https://github.com/orgs/community/discussions/23166
K
Ky

Ошибка 404 на GitHub Pages для файлов/папок с _ (CSS Hugo) — вина Jekyll. Добавьте .nojekyll в root репозитория или public/.

Дополнительные фиксы:

  • git commit --allow-empty для триггера rebuild (ждите ~10 мин).
  • Очистите кэш браузера/CDN.
  • Проверьте Settings > Pages: правильная branch/source, baseURL с /.

Для Hugo: убедитесь baseURL = "https://username.github.io/", пересоберите и git push -f если нужно.

https://stackoverflow.com/questions/11577147/how-to-fix-http-404-on-github-pages
gohugo.io / Документация проекта
gohugo.io

Для хостинга Hugo на GitHub Pages обязательно отключите Jekyll, создав пустой файл .nojekyll в корне директории публикации (public/). Это предотвратит 404 для сгенерированных файлов Hugo, включая хэшированные CSS вроде _entry.b0a8f189.css.

Процесс:

  1. hugo — сгенерировать public/.
  2. touch public/.nojekyll.
  3. git add public/ && git commit -m "Deploy Hugo with .nojekyll" && git push origin main (или gh-pages).

Убедитесь в baseURL и используйте Actions для автоматизации.

https://gohugo.io/hosting-and-deployment/hosting-on-github/
Авторы
D
@dim5x
Специалист по информационной безопасности
@Wispik / Разработчик
@Wispik
Разработчик
@theletterf / Технический писатель
@theletterf
Технический писатель
Z
@zwbetz
Разработчик
T
@tdegeus
Разработчик
K
Ky
Разработчик
A
@arnaud
Разработчик
Источники
gohugo.io / Документация проекта
gohugo.io
Документация проекта
Проверено модерацией
НейроОтветы
НейроОтветы
Модерация
Hugo CSS 404 на GitHub Pages: как исправить с .nojekyll