Hugo cms: Hugo Documentation | Hugo

Содержание

Опыт использования генератора статических сайтов Hugo / Хабр

Делюсь 2-х летним опытом использования генератора статических сайтов Hugo. Заметка ориентирована на начинающих, но в этой заметке не будет инструкций «как установить Hugo» или «как создать первый пост». Эта заметка будет полезна тем, кто выбирает и сравнивает альтернативы для ведения блога.

Генератор статических сайтов — программа, которая обрабатывает структурированные исходные файлы (тексты, картинки, шаблоны) и генерирует статический HTML-сайт, который можно загрузить на сервер.

Исходники сайта — это набор папок на компьютере:

В отдельных подпапках лежат шаблоны тем, исходники постов, общие картинки. В нескольких bat-файлах записаны команды на типовые операции: запись обновлений блога, запуск сервера для локального просмотра, создание нового поста из шаблона.

Несмотря на кажущуюся недружественность, такой подход, в отличие от CMS, удобен для тех, кто имеет какие-то знания в HTML, CSS и других веб технологиях, но хочет, чтобы блог оставался технически примитивным.

Субъективно, править базовые скрипты на 5-10 строк легче, чем копаться в исходниках страниц какой-нибудь CMS. Также не нужно настраивать окружение на сервере, заниматься базой данных и вопросами безопасности установки.

Ограничения статических сайтов заключаются в том, что нет возможности использовать функции, привязанные к пользователям. Как пример, приходится использовать стороннюю систему комментариев. Для блога подобные ограничения не являются критичными.

Для статических сайтов легко найти и настроить хостинг

Хостинг статики, пока у сайта нет объёмов траффика, как у Гугла, настраивается проще, чем для динамических сайтов, и во многих случаях бесплатен.

Держу исходники и сам блог на GitLab. Вот как все работает:

  1. В приватном git-репозитории GitLab содержатся исходники блога.

  2. GitLab CI при обновлении репозитория самостоятельно запускает генерацию новой версии сайта и выкладывает её на GitLab Pages.

Схема, как это работает:

На конце стека используется Cloudflare для организации SSL сертификата для https версии блога.

Обновление сайта от внесения изменений до доступности онлайн новой версии блога в конфигурации Hugo-GitLab занимает 0,5-1 минуту. Основное время тратится Gitlab CI на подготовку к сборке сайта. Непосредственно генерация сайта занимает 1-2 секунды. У других генераторов сайтов скорость обновления будет другой. Например, у другого популярного генератора сайтов Jekyll построение страниц новой версии сайта может быть в разы медленнее.

Исходники и хостинг можно разделить — генерировать страницы сайта на локальном компьютере, а загружать на хостинг только получившиеся HTML-файлы. Для статики есть удобные хостинги, например, Netlify. По такому принципу ранее работал GitHub Pages. Некоторое время назад GitHub ввели инструменты автоматизации CI, как у GitLab.

Не нужно думать о поддержке работоспособности блога

Если один раз без ошибок загрузил готовый сайт на сервер и ничего не меняешь, то усилия по поддержке сайта сводятся к минимуму. Нужно только раз в год оплачивать домен. Нет необходимости думать о безопасности (например, обновлять CMS и плагины), ежемесячно оплачивать хостинг, можно не бояться автоматических обновлений.

Сохраняется полный контроль над исходниками

Каждый пост — это отдельная папка с Markdown текстом и тут же лежащими файлами изображений.

Подготовленные таким образом посты, в теории, легко переносятся на другие платформы. На практике сложно об этом судить, так как в интернете сложно найти кейсы.

Вот так выглядит папка с данными для 1 поста в блоге:

А это уже редактирование самого поста в Sublime Text и страница на выходе:

Если внести исходники в систему контроля версий, то можно смотреть историю изменений в блоге. На скриншоте ниже показан просмотр истории изменений от мая 2018 года в Sublime Merge:

Среди разных генераторов выбрал Hugo из-за его популярности, скорости и простоты установки

Hugo входит в топ-3 популярным генератором сайтов в интернете по количеству звезд на GitHub.

Сама программа представляет из себя 1 exe-файл. Запуск генератора не требует установки, но чтобы вызывать его командой «hugo» надо прописать путь к нему его в системную переменную PATH.

Про скорость работы уже писал выше — Hugo существенно быстрее многих других генераторов, что становится важно по мере роста объема сайта.

Нужно хотя бы немного разбираться в программировании или скриптах

HUGO и другие генераторы не имеют привычного пользовательского интерфейса. Запуск обновления сайта делается через набор команд или один bat-файл.

«Интерфейс»:

Если загружать сайт через GitLab CI, то нужно уметь слегка править конфигурационный файл CI.

GitLab предлагает ряд готовый файлов под разные генераторы, которые можно взять за базу:

Но все равно приходится погружаться в конфиг, чтобы что-поправить. Например, в стандартном конфиге (на скриншоте ниже) рекомендую, как минимум, сменить выбор версии Hugo (причины разберу позже):

Приходится вручную править выбранную тему оформления под себя, нужны знания HTML

Русскоязычное сообщество Hugo не слишком велико, поэтому очень мало готовых решений, учитывающих специфику аудитории России. Нет русскоязычных тем, социальные кнопки адаптированы под зарубежные сети, темы ориентированы на использование только комментариев Disqus и так далее. Пришлось самостоятельно переписать системные надписи на русский и поставить комплекты социальных кнопок с сетями, популярными у русскоязычной аудитории.

Даже если вы не front-end разработчик, добро пожаловать в мир HTML шаблонов с вставками на Go:

В Hugo не было до недавнего времени не было такого понятия, как плагины. Все правки надо делать в исходниках темы. Например, если нужно поправить текст в подвале страницы — придётся править HTML-шаблон темы.

Если тему надо обновить, то надо вручную переносить свои правки между версиями темы. На случай необходимости полного переноса приходится вести текстовый лог с описанием всех изменений в исходной теме.

На скриншоте ниже ~1/3 перечня изменений:

Сложно разобраться, как работает движок генератора

Не старался, но за все время использования так и не смог полностью разобраться в том, как именно работает генератор. Самостоятельно сделать тему или сложную структуру блога с нуля не смогу.

Не всегда можно найти решение проблемы

Если проблема общая для многих пользователей, то она быстро чинится. Но можно нарваться на проблему, которая встретится только у вас.

Например, после обновления GitLab стал конвертировать неанглийские символы в пути к файлам в web-encode. Это в разы увеличивало пути к файлам, если в них были неанглийские буквы. Из-за слишком длинных путей процесс построения сайта падал с ошибкой. Упоминания конкретно этой проблемы я не смог найти. Завёл тикет на issue-трекере GitLab, но по нему не было движения. Предполагаю, что проблема была связанна с более крупным багом в GitLab CI, который был исправлен где-то через месяц. В этот месяц временно решил свою проблему через перенос хостинга.

Опасность обновлений и причины фиксировать версию Hugo

Нет гарантии, что ваши настройки, документы и допиленная тема будут без изменений корректно работать в новой версии Hugo.

Например, в Hugo версии 0.57.0 перестала правильно собираться главная страница. Так и не смог понять, в чем проблема: в багах новой версии генератора, в необновлённой теме или в моей структуре исходников. Решил остановиться на версии 0.56. Потом оказалось, что разработчики внесли ломающие совместимость изменения в конфигурацию алгоритма генерации страниц.

Актуальным становится вопрос, а стоит ли в принципе обновляться, если не для использования новой функциональности. Ведь на безопасность отсутствие обновлений не влияет, а совместимость может поломаться. Пример с официального форума Hugo:

На GitLab CI в настройках скриптов рекомендую жёстко фиксировать, какую версию Hugo использовать.

По умолчанию пользовался «последней актуальной», но несколько раз столкнулся с тем, что новая версия меняла важные параметры рендера сайта. Вплоть до того, что ломался процесс построения блога, или в RSS появлялись ненужные записи. Узнавал об этом, только после обновления сайта на хостинге или после попадания в RSS. На скриншоте ниже история RSS из Feedly с навсегда сохранёнными ошибочными записями:

Подводим итоги

Генератор статических сайтов — подходит тем, кто уже немного разбирается во front-end, хочет при ограниченном погружении в технические аспекты получить технически несложный сайт/блог.

Hugo — хороший выбор, если в приоритете скорость работы и простота установки.

Совсем без технических знаний не обойтись. То тут, то там приходится погружаться в HTML, CSS и прочие технические вопросы. С другой стороны, один раз настроенный сайт требует существенно меньше усилий для сопровождения.

Статический генератор сайтов Hugo. Фронтенд реалии / Хабр

В 2020 практически весь мир фронтенда заполонили Javascript фреймворки. Только и слышно о React, Angular, Vue и иногда в далеких просторах можно услышать тихий шепот «Svelte». Разработчики умело используют эти инструменты для создания крутых продуктов, но есть и «динозавры» которые все еще предпочитают статику или jquery, а может их жизнь, вынуждает к этому или специфические задачи. Каждый день мир веб-разработки пополняется новыми технологиями, и сегодня речь пойдет о статических генераторах сайтов.
Статический генератор сайта — программа, которая из различных исходных файлов (картинок, шаблонов в разных форматах, текстовых файлов и т.п) генерирует статический HTML-сайт. Один из ярких представителей — Hugo. Разработчики позиционируют Hugo, как «самая быстрая в мире платформа для создания сайтов».

«Самая быстрая в мире платформа для создания сайтов»


Ознакомиться с документацией можно на официальном сайте фреймворка. Далее речь пойдет об основных преимуществах, особенностях (здесь немного введения в фреймворк) и недостатках данного продукта. Эта статья не являться полноценным туториалом по Hugo. Я лишь пытаюсь сделать краткое введение в технологию и изложения некоторых мыслей из личного опыта, чтоб читатель смог решить стоит ли ему тратить время для более детального ознакомления с фреймворком и добавления его в свой арсенал фронтенд-разработки.

Несколько слов о HUGO


Hugo — один из самых популярных генераторов статических сайтов с открытым исходным кодом, написан на языке Go. Благодаря своей удивительной скорости и гибкости, Hugo делает создание веб-сайтов увлекательным.

Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.


На момент написания статьи доступная версия фреймворка — v0.79.0. Hugo еще не имеет стабильной версии, но это не мешает создавать с помощью него гибкие и масштабируемые сайты.

Он подойдет как для создания лендингов, «многостраничников» — так и для создания более сложных продуктов: блог, новостной портал и даже интернет-магазин.

Установить фреймворк можно практически на любую современную платформу в несколько команд. Инструкция по установке для Windows, macOs, Linux очень хорошо описана в документации и не вызывает у разработчиков дополнительной головной боли.

Основные преимущества Hugo

  • Очень быстрый и гибкий

  • Для него легко настроить хостинг

  • Безопасный

  • Хорошая структура исходников

  • Возможность хранить содержимое в удобном формате (YAML, JSON или TOML)

  • Поддержка тем. Есть готовый набор тем, более 200

  • Легко SEO-оптимизировать

  • i18n с коробки

  • Хорошая поддержка таксономии

  • Быстрый в освоении. Исчерпывающая документация

Документация


Фреймворк имеет очень хорошую документацию. Она доступна только на английском языке. Информация очень хорошо структурирована, что позволяет освоить данную технологию, за несколько дней. Для лучшего восприятия, практически в каждой главе есть обучающее видео от разработчиков. Все это позволяет очень быстро приступить к созданию собственных сайтов.

Структура


После установки фреймворка, сайт можно легко создать с помощью команды:

hugo new site website-name

Далее hugo сгенерирует следующую структуру проекта:

Content & data. Основной контент или содержимое сайта храниться в формате .md в папке content. В роле контента могут выступать ваши статьи, новости, продукты интернет магазина и прочее. Каталог «data» используется для хранения файлов конфигурации, которые Hugo может использовать при создании вашего веб-сайта. Вы можете записать эти файлы в формате YAML, JSON или TOML.

Archetypes. Архетипы используют для создания содержимого сайта на основе заготовок. Это экономит время и обеспечивает единообразие для сайтов, использующих несколько типов контента. Вы также можете создавать свои собственные архетипы с предварительно настроенными полями основного материала.

I18n. Этот каталог предназначен для хранения конфигурации сайта на различных языках.

Resources. Hugo использует этот каталог для хранения кеша. Это ускоряет сборку сайта.

Static. Здесь храниться весь статический контент (CSS, JavaScript, и т.п).

Layouts. Хранит шаблоны в виде файлов . html, которые определяют, как просмотры вашего контента будут отображаться на статическом веб-сайте.

Themes. Для хранения различных тем.

Public. Сгенерированные исходники веб-сайта. Именно эту директорию следует заливать на хостинг.

Разработка


Как было указано выше, Hugo имеет около 200 готовых тем, которые можно легко установить и использовать. Это значительно ускоряет процесс разработки. Темы включают в себя не только отличные дизайнерские, но и хорошие программные решения. Можно найти много интересного для разработки если покопаться в исходниках (код каждой темы в открытом доступе на github).

Отдельным преимуществом фреймворка являться использование Go html/template. Вы можете легко создавать компоненты страницы в формате html затем импортировать их в нужное вам место. Многим может быть не по душе создавать компоненты в формате html, надеюсь в будущем этот вопрос будет решен разработчиками в пользу шаблонизаторов.

Одно из приятных нововведений последних релизов — поддержка scss с коробки. Теперь не нужно дополнительно настраивать сборку с помощью различных сборщиков, Hugo умеет распознавать scss и минимизировать его. Так же можно легко минимизировать и js с коробки.

По поводу различных сборок — разработчики предоставляет несколько интересных готовых решений на github.

В целом хранения содержимого в текстовом формате оставляет приятный след на душе, особенно удобно хранить различные конфигурации в формате YAML (с коробки так, можно настроить другой удобный формат). Преимущество такого способа хранения контента сможет ощутить не только разработчик, но и заказчик, которому можно смело отдать папку с контентом для редактирования. Ему не нужно будет копаться в полотне html кода, а всего лишь редактировать текстовый файл. Алгоритм добавления нового плагина, пункта меню, или гугл аналитики привлекает.

Если речь идет о новом плагине ваши действия сводятся к тому что вам нужно:

  1. Физически переместить исходники плагина в директорию проекта (к примеру в папку static)

  2. Указать название нового плагина в файле конфигурации проекта


Если речь зашла о гугл аналитике, или пункте меню — все это легко можно добавить в конфигурационный файл проекта.

Деплой


Все просто, вам нужен обычный хостинг. Загружаете туда папку public и наслаждаетесь сайтом.

Но что же делать если мы хотим backend? Для этого существует ряд сторонних сервисов которые предоставляют услуги по размещению веб-сайтов созданных с помощью статических генераторов. Так же есть CMS системы для статических генераторов. Загружая туда свой продукт у вас и заказчика есть возможность «с комфортом» редактировать содержимое сайта, создавать новые посты / продукты, загружать медиафайлы и прочее. Один из ярких примеров — forestry.

Минусы

  • Нет стабильной версии. Порой неожиданно при сборке проекта могут возникнуть некоторые баги, однако Hugo — активно развивается и вы можете оставить фидбек разработчикам, которые часто выпускают новые релизы и «фиксят» баги.

  • Использование html. Возможно кого-то это смутит. Многие разработчики привыкли использовать шаблонизаторы.

  • Привлекательные конкуренты. Статический генератор Gatsby вдохновлен идеями React может показаться куда привлекательнее Hugo, учитывая популярность js-фреймворка.

Заключение


Учитывая вызовы современности (когда более привлекательным стала разработка SPA) Hugo может заинтересовать не многих. Но все еще существуют множество заказов на создание блога, новостного сайта или лендинга с использованием CMS систем. Здесь Hugo может стать отличной альтернативой. Его скорость, простота в развертывании, возможность сохранить «чистоту кода» (а значит и хорошая поддержка продукта в будущем) смогут удовлетворить требования не только разработчика, но и заказчика.

Быстрый старт | Hugo

В этом уроке вы будете:

  1. Создать сайт
  2. Добавить содержимое
  3. Настройка сайта
  4. Опубликовать сайт

Предварительные условия

Перед тем, как начать этот урок:

  1. . расширенная версия)
  2. Установить Git

Вы также должны уметь работать из командной строки.

Создать сайт

Команды

Если вы являетесь пользователем Windows, вы должны выполнять эти команды с помощью PowerShell. Вы не можете использовать Windows Powershell, которая является другим приложением, или командную строку. Вы также можете использовать оболочку Linux, если она доступна.

Запустите эти команды, чтобы создать сайт Hugo с темой Ananke. В следующем разделе дается объяснение каждой команды.

 Хьюго быстрый запуск нового сайта
компакт-диск быстрый старт
git инициировать
добавить подмодуль git https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke
echo "theme = 'ananke'" >> config.toml
Хьюго сервер

Просмотрите свой сайт по URL-адресу, отображаемому в вашем терминале. Нажмите Ctrl + C , чтобы остановить сервер разработки Hugo.

Объяснение команд

Создайте структуру каталогов для своего проекта в каталоге быстрого запуска .

 Хьюго быстрый запуск нового сайта

Измените текущий каталог на корень вашего проекта.

 компакт-диск быстрого запуска

Инициализировать пустой репозиторий Git в текущем каталоге.

 инициализация git

Клонируйте тему Ananke в каталог themes , добавив ее в свой проект как подмодуль Git.

 подмодуль git добавить https://github.com/theNewDynamic/gohugo-theme-ananke темы/ananke

Добавить строку в файл конфигурации сайта, указывающую текущую тему.

 эхо "тема = 'ananke'" >> config.toml

Запустите сервер разработки Hugo, чтобы просмотреть сайт.

 Хьюго сервер

Нажмите Ctrl + C , чтобы остановить сервер разработки Hugo.

Добавить контент

Добавить новую страницу на свой сайт.

 Хьюго новые сообщения/my-first-post.md

Hugo создал файл в каталоге content/posts . Откройте файл в вашем редакторе.

 ---
title: "Мой первый пост"
дата: 2022-11-20T09:03:20-08:00
черновик: правда
---

Обратите внимание, что значение draft во вступительной части равно true . По умолчанию Hugo не публикует черновой контент при создании сайта. Узнайте больше о черновиках, будущем и просроченном содержимом.

Добавьте некоторую уценку в тело сообщения, но не изменяйте значение draft .

 ---
title: "Мой первый пост"
дата: 2022-11-20T09:03:20-08:00
черновик: правда
---
## Вступление
Это **жирный** текст, а это *выделенный* текст.
Посетите сайт [Hugo](https://gohugo.io)!

Сохраните файл, затем запустите сервер разработки Hugo, чтобы просмотреть сайт. Вы можете запустить любую из следующих команд, чтобы включить черновик содержимого.

 сервер Hugo --buildDrafts
Хьюго сервер -D

Просмотрите свой сайт по URL-адресу, отображаемому в вашем терминале. Поддерживайте работу сервера разработки, пока вы продолжаете добавлять и изменять содержимое.

Механизм рендеринга Hugo соответствует спецификации CommonMark для уценки. Организация CommonMark предоставляет полезный инструмент для тестирования в реальном времени на основе эталонной реализации.

Настройте сайт

В редакторе откройте файл конфигурации сайта ( config.toml ) в корне вашего проекта.

 baseURL = 'http://example.org/'
languageCode = 'en-us'
title = 'Мой новый сайт Hugo'
тема = 'ананке'

Внесите следующие изменения:

  1. Установите baseURL для вашего производственного сайта. Это значение должно начинаться с протокола и заканчиваться косой чертой, как показано выше.

  2. Установите languageCode на ваш язык и регион.

  3. Установите заголовок для вашего производственного участка.

Запустите сервер разработки Hugo, чтобы увидеть ваши изменения, не забывая включить черновой контент.

 Хьюго сервер -D

Большинство авторов тем предоставляют рекомендации по настройке и параметры. Обязательно посетите репозиторий вашей темы или сайт документации для получения подробной информации.

The New Dynamic, авторы темы Ananke, предоставляют документацию по настройке и использованию. Они также предоставляют демонстрационный сайт.

Опубликовать сайт

На этом шаге вы опубликуете свой сайт, но не будете развертывать его.

Когда вы публикуете свой сайт, Hugo создает весь статический сайт в общедоступном каталоге в корне вашего проекта. Сюда входят файлы HTML и активы, такие как изображения, файлы CSS и файлы JavaScript.

Когда вы публикуете свой сайт, вы обычно , а не хотите включить черновик, будущий контент или контент с истекшим сроком действия. Команда проста.

Чтобы узнать, как развернуть ваш сайт, см. раздел «Размещение и развертывание».

Запросить помощь

Форум Hugo — это активное сообщество пользователей и разработчиков, которые отвечают на вопросы, делятся знаниями и приводят примеры. Быстрый поиск по более чем 20 000 тем часто дает ответ на ваш вопрос. Перед тем, как задать свой первый вопрос, обязательно прочтите о запросе помощи.

Другие ресурсы

Другие ресурсы, которые помогут вам изучить Hugo, включая книги и видеоуроки, см. на странице внешних учебных ресурсов.

Редакторы Hugo CMS любят

Разрабатывайте быстрее, редактируйте проще и публикуйте уверенно с CloudCannon в качестве вашей CMS Hugo.

Отредактируйте свой сайт Hugo

Заказать демо

Доверено более 40 000 сайтов

Все что тебе нужно

Все, что вам нужно для управления контентом, на одной платформе. Позвольте вашей команде создавать новые страницы, редактировать их визуально и размещать самые эффективные сайты в Интернете с помощью CloudCannon CMS для Hugo.

Редактируйте все, что видите

Редактируйте весь контент прямо на странице, без всяких догадок.​

Предоставьте своим редакторам возможность создавать целые страницы с помощью пользовательских компонентов.

Git, без головной боли

CloudCannon синхронизирует изменения из вашего репозитория Git и отправляет изменения контента обратно, чтобы ваша команда разработчиков и команда контента всегда были синхронизированы. А поскольку CloudCannon справится со всем этим, вам не придется обучать Git.

Целая экосистема позади вас

Повысьте уровень своего проекта Hugo с помощью наших инструментов для создания статических сайтов с открытым исходным кодом:

  • Книжный магазин — создавайте рабочие процессы разработки на основе компонентов;
  • Reseed — объединение нескольких сайтов в один домен;
  • Rosey — управлять переводами для локализации и i18n;
  • Pagebreak — детальная настройка пагинации сайта.

CloudCannon дает нашим разработчикам полный контроль над нашими микросайтами, а группе по контенту предоставляет простой в использовании интерфейс.

Ищете ресурсы Hugo?

Мы вас прикроем. Ознакомьтесь с нашими советами, рекомендациями и учебными пособиями Hugo:

  • Учебные пособия и видеоролики Hugo — узнайте, как строить с помощью Hugo, как настраивать сайты Hugo для редактирования CloudCannon и многое другое.
  • Найдите темы Hugo — изучите нашу библиотеку бесплатных тем Hugo, готовых к использованию CloudCannon, и разверните их одним щелчком мыши.
  • Отпразднуйте Hugo вместе с сообществом — запишитесь на два дня бесплатных лекций и мастер-классов на HugoConf 2022!

Живые и редактируемые веб-сайты Hugo за четыре простых шага

Начните с учебника Hugo и CloudCannon

1. Синхронизируйте свой сайт Hugo

Войдите в свою учетную запись GitHub, GitLab или Bitbucket и подключите свой репозиторий Hugo.