Hugo. HugoBlox. Обновление шаблонов

2026-01-21 · 5 мин. для прочтения

Hugo. HugoBlox. Обновление шаблонов.

Содержание

1 До версии 5.3

Примечания до версии 5.3 находятся в блоге https://wowchemy.com/blog/.
В файле go.mod установите необходимую версию (например, 5.3), исправив строку:
```
require (
        github.com/wowchemy/wowchemy-hugo-modules/v5 v5.3.0
)
```

Обновите пути к модулям в конфигурации в файле config/_default/config.yaml:

module:
  imports:
    - path: github.com/wowchemy/wowchemy-hugo-modules/wowchemy-cms/v5
    - path: github.com/wowchemy/wowchemy-hugo-modules/wowchemy/v5

или config/_default/config.toml:

[module]
  [[module.imports]]
    path = "github.com/wowchemy/wowchemy-hugo-modules/wowchemy-cms/v5"
  [[module.imports]]
    path = "github.com/wowchemy/wowchemy-hugo-modules/wowchemy/v5"

Для использования с netlify:
- Обновите HUGO_VERSION в netlify.toml до необходимой версии 0.84.4.
Обновите модуль:
- текущий релиз:
```
hugo mod get -u
```
- текущая версия разработчика:
```
hugo mod get -u ./...
```

2 Общие рекомендации

Текущую версию можно найти:
- в файле themes/academic/data/academic.toml (если всё делалось очень давно);
- в файле go.mod:
  - точная версия (например, v5.0.0);
  - версия сборки в форме v<dummy-version-number>-<date>-<build-number>.

Отредактируйте файл go.mod:

module my_website

go 1.15

require (
        github.com/HugoBlox/hugo-blox-builder/modules/blox-bootstrap/v5 v5.9.6
        github.com/HugoBlox/hugo-blox-builder/modules/blox-plugin-netlify v1.1.2-0.20231108141515-0478cf6921f9
        github.com/HugoBlox/hugo-blox-builder/modules/blox-plugin-reveal v1.1.2
)

Вы настраиваете версию модуля в операторе require.
~~Вместо версии main можно задать конкретную версию модуля (в формате v5.x.y).~~

Обновите пути модулей в файле config/_default/module.yaml:

imports:
  - path: github.com/HugoBlox/hugo-blox-builder/modules/blox-plugin-netlify
  - path: github.com/HugoBlox/hugo-blox-builder/modules/blox-plugin-reveal
  - path: github.com/HugoBlox/hugo-blox-builder/modules/blox-bootstrap/v5

Определите необходимую версию hugo (HUGO_VERSION) (возьмите из примечания к выпуску https://github.com/HugoBlox/hugo-blox-builder/releases).
Проверьте, что локальная версия Hugo Extended имеет необходимую версию.
Последовательно примените любые критические изменения из соответствующих примечаний к выпуску. Если в релизе нет раздела Breaking Changes, то никаких изменений не требуется.
Обновите модули темы:
- до последней официальной версии:
```
hugo mod get -u
```
- до текущей версии в репозитории:
```
hugo mod get -u ./...
```
После этого main в go.mod будет заменена на конкретную версию.
Если Вы обновляете совсем старую версию, Вам может быть проще создать новый сайт и перенести папку content.

3 Миграция на tailwind

3.1 Общая информация

Последний релиз на bootstrap вышел 2023-11-14.
Далее релиз стал базироваться на tailwind.
Сайт tailwind:
- https://tailwindcss.com/
- https://tailwindcss.ru/

3.2 Основные изменения

3.2.1 Первая страница

Вместо отдельных файлов-блоков в каталоге content/home осуществлён переход к страницам типа landing:
- content/_index.md;
- content/experience.md;
- content/projects.md.

3.2.2 Публикации типа book

Hugo. Wowchemy. Book
Тип публикации book отсутствует.
Вместо него следует использовать тип docs:
```
type: docs
```
Убран шорткод:
```
    
    
    
```

3.2.3 Поиск

Теперь необходимо создать индекс поиска отдельно.
Сначала сгенерим страницы сайта, потом создадим индекс поиска, после можно запустить hugo server для просмотра:
```
hugo && \
npm_config_yes=true npx pagefind --site "public" --output-subdir ../static/pagefind && \
hugo server -D
```

4 Обновление до blox-tailwind/v0.8.0

4.1 Общая информация

Меняются именования каталогов.
Рекомендуется использовать фиксированные названия каталогов.
В Hugo Blox стандартизированы типы контента:

Старый тип контента	Новый тип контента
`post`	`blog`
`publication`	`publications`
`project`	`projects`
`event`	`events`
`teaching`	`courses`

Типы коллекций используют имена во множественном числе (blog является исключением, но это стандартная практика).
Меняются
- page_type:

4.2 Предлагаемые скрипты

Репозиторий: https://github.com/HugoBlox/awesome-hugo
Скрипт: singular2plural.
Документация: https://github.com/HugoBlox/awesome-hugo/blob/main/singular2plural/README.md

4.3 Вариант 1: Миграция с помощью скрипта

Два скрипта миграции (выберите тот, который вам больше подходит):
- Скрипт на Python (рекомендуется): migrate-content-types.py
- Скрипт Zsh : migrate-content-types.sh
Скрипты выполняют операции записи и удаления файлов/папок.
Перед запуском обязательно сделайте полную резервную копию своего компьютера и проверьте/адаптируйте код скрипта под свой сайт.
Всегда запускайте сначала скрипт с помощью --dry-run.

4.3.1 Использование скрипта Python

Требования:
- Python 3.8+ с pyyaml установлены:
```
pip3 install pyyaml
```
Запуск:

# Run the migration script
python migrate-content-types.py /path/to/your/site --dry-run

# Apply changes after reviewing dry-run output
python migrate-content-types.py /path/to/your/site

4.3.2 Использование скрипта Zsh

Требования:
- Оболочка macOS/Linux (или Windows через WSL).
Запуск:

# Make the script executable (first time only)
chmod +x migrate-content-types.sh

# Preview without making changes
./migrate-content-types.sh /path/to/your/site --dry-run

# Apply changes after reviewing dry-run output
./migrate-content-types.sh /path/to/your/site

4.4 Вариант 2: Ручная миграция

Если вы предпочитаете выполнить миграцию вручную, выполните следующие шаги:

4.4.1 Переименовать каталоги с содержимым

Следует заменить:

post → blog
publication → publications
project → projects
event → events

teaching → courses

# For each content type
mkdir -p content/blog
mv content/post/* content/blog/
rmdir content/post

# Repeat for other types
mkdir -p content/publications
mv content/publication/* content/publications/
rmdir content/publication

# And so on...

В случае структуры с языком.

В каталоге content:

cd content
grep -r 'page_type:' *
find . -iname "_index.md" -exec sed -i -e 's/page_type: post/page_type: blog/g' '{}' \;
find -iname '_index.mde' -delete
cd ru
git mv post blog
cd en
git mv post blog

4.4.2 Обновите ссылки на папки в файлах контента

Искать folders: разделы в файлах Markdown
Обновите ссылки, например: - post → - blog
Обновите ссылки, например: - publication → - publications
Обновите ссылки, например: - project → - projects
Обновите ссылки, например: - event → - events
Обновите ссылки, например: - teaching → - courses

4.4.3 Обновите ссылки на `page_type` в файлах контента

Искать page_type: в файлах Markdown
Обновлять page_type: post → page_type: blog
И так далее для других типов контента.

4.4.4 Удалите переопределения постоянных ссылок в конфигурации Hugo:

Отредактируйте свой hugo.yaml, config.yaml, или config.toml.
Удалить или обновить любой permalinks: разделы, заменив название каталогов.

У меня получилось следующее:

permalinks:
  blog: "/blog/:year/:month/:day/:slug"
  authors: "/author/:slug/"
  event: "/events/:slug/"
  tags: "/tag/:slug/"
  categories: "/category/:slug/"
  publication_types: "/publication-type/:slug/"

4.4.5 Добавьте перенаправления в ваш `netlify.toml` для обратной совместимости

Если вы используете netlify.

[[redirects]]
  from = "/post/*"
  to = "/blog/:splat"
  status = 301
  force = true

[[redirects]]
  from = "/publication/*"
  to = "/publications/:splat"
  status = 301
  force = true

# And so on for other content types

4.5 При ведении блога из org-roam

Для post → blog:

cd ~/work/org
find . -iname "*.org" -exec sed -i "s:ru/post/:ru/blog/:g" '{}' \;
find . -iname "*.org" -exec sed -i "s:en/post/:en/blog/:g" '{}' \;

Для teaching → courses:

cd ~/work/org
find . -iname "*.org" -exec sed -i "s:ru/teaching:ru/courses:g" '{}' \;
find . -iname "*.org" -exec sed -i "s:en/teaching:en/courses:g" '{}' \;

4.6 После миграции

Запустите свой сайт локально с помощью hugo server чтобы проверить изменения.
Проверьте все страницы, чтобы убедиться в их корректном отображении.
Попробуйте выполнить поиск в папке вашего сайта по таким запросам, как folders, type, layout или старые типы страниц (например, post ) чтобы подтвердить, что у вас нет фильтров, ищущих контент в старой структуре.
Проверьте корректную работу ссылок и изображений.
Зафиксируйте изменения в вашем репозитории.

Обновлено 2026-01-23