Создаём свой блог на Hugo

Расскажу как я создал этот сайт, используя Hugo с темой Stack

Программы

Что такое Hugo?

Если загуглить “Что такое Hugo”, то в ответ получим - это генератор статических сайтов.

Для человека, который не хочет разбираться в терминологии и который хочет просто вести свой блог с удобством, эта информация вообще ни о чём не говорит. Поэтому скажу проще - Hugo позволяет писать посты, будто это обычная заметка в программе Obsidian, используя markdown, о котором написано тут.

Это позволяет относительно легко начать вести свой блог. Написал текст в .md файл, написал в терминале hugo, потом загрузил это на сервер и готово, пост добавлен на сайт. И вот о том, как именно это сделать, сейчас пойдёт речь.

Установка Hugo

Все действия показаны для пользователей Linux. Как это делается на других ОС я не знаю. Я буду показывать сразу тот вариант, который использую сам, а не установку голой темы Stack.

Устанавливаем hugo, git и golang. Для Arch Linux команда будет такой:

1

sudo pacman -Sy hugo git go

Проверяем установилось ли:

1

hugo version

Если после номера версии написано extended, то установлено что надо. Для этой темы нужна именно такая версия.

Открываем терминал в том месте, где хотим хранить файлы блога.

Создаём новый проект Hugo и заходим в него:

1

hugo new site hugo-blog && cd hugo-blog

Установка темы Stack

У меня с этим по началу были проблемы, но этот гайд меня выручил.

Клонируем репозиторий в каталог темы:

1

git clone https://github.com/Buliway/hugo-theme-stack/ themes/hugo-theme-stack

Копируем файлы тестового сайта в каталог проекта и удаляем старый дефолт конфиг:

1

cp -r themes/hugo-theme-stack/exampleSite/* ./ && rm hugo.toml

Всё, готово. Если хотим потыкать у себя на ПК локально, то пишем в терминал hugo server и открыть в браузере эту ссылку http://localhost:1313/

Работа с Hugo

Когда всё готово и работает локально, то надо разобраться с тем, как писать посты и как их подготовить к загрузке на сервер.

Подготовка к загрузке на сервер

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

В прошлый раз мы писали команду hugo server. Эта команда создала все нужные для сервера файлы, поместила их в каталог public и запустила сервер локально.

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

Но и тут есть нюансы. Если вы создавали статью-черновик, тоесть с draft: true, что скрывает эту страницу из поисковой выдачи, или если вы удалили какие-то файлы, которые не должны быть в публичном доступе, то описанные выше команды создадут для них файлы в public, а вы потом загрузите их на сервер, даже не подозревая, что к ним можно получить доступ. Да - в поиске и на главной странице их, скорее всего, не будет. Но если ввести конкретный путь, который ведёт на “удалённую” страницу, то она откроется.

Дело в том, что hugo не удаляет старые файлы, а hugo server создаёт файлы даже для draft: true, чтоб можно было их посмотреть локально.

Чтоб это исправить я использую команду, которая не создаёт страницы для черновиков:

1

hugo server --buildDrafts=false

И команду, которая удаляет весь прошлый проект из public перед созданием нового:

1

hugo --cleanDestinationDir

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

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

Отправляем блог на сервер

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

Тут ничего сложного. Билдим, потом через rsync отправляем на сервер:

1
2

hugo --cleanDestinationDir
rsync -av --delete "путь/до/каталога/public" "user@ip:/путь/до/каталога/на/сервере"

ОСТОРОЖНО: флаг --delete удаляет файлы на сервере. Если указать неверный путь, можно потерять файлы. Изначально команда rsync синхронизирует файлы из первого места во второе. Она отправляет только изменения файлов, а не весь проект целиком. Но если какие-то файлы у меня на пк были удалены, то без флага --delete эта команда не удалит эти же файлы на сервере. Поэтому я отправляю файлы с удалением.

Пишем посты

В данный момент я использую VSCode для написания статей.

Чтоб они нормально отображались, я установил плагин Hugo Language and Syntax Support.

Ещё есть плагин Front Matter CMS, который позволяет удобно управлять постами для разных генераторов статических сайтов, включая Hugo. Но второй плагин мне не зашёл, проще руками всё делать.

В самом VSCode я создал шаблоны, которые удобно вставлять в пустой файл при создании статьи. Для этого нажимаем Ctrl + Shift + P. Внутри пишем Configure User Snippets и выбираем New Snippets file for hugo-blog. Это создаст файл с синтаксисом json. Удаляем всё, что там находится внутри и вставляем это:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

{
	"Add current date and time": {
	  "body": [
		"${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}T${CURRENT_HOUR}:${CURRENT_MINUTE}:${CURRENT_SECOND}Z"
	  ],
	  "description": "Add current date and time"
	},
	"Add start post info RU": {
		"body": [
		  "---\ntitle:\ndescription:\ndate: ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}\ncategories: [\n\n]\ntags: [\n\n]\nlinks:\n  - title: Помочь проекту\n    description: Если вам нравится то, что я делаю, то можете поддержать автора по этой ссылке.\n    website: /ru/поддержка\n# lastmod:  # Дата редактирования поста\n# image: string # Изображение поста\n# comments: false # Вкл/Выкл комментариев под данным постом\n# math: true # Вкл/Выкл KaTeX рендеринг\n# toc: false # Вкл/Выкл навигацию по заголовкам справа от поста\n# keywords: []string # Keywords of the page. Useful for SEO.\ndraft: true # Если вкл, то не рендерит эту страницу. Для недописанных постов\n---"
		],
		"description": "Add title and description with current date and time"
	},
	"Add start post info EN": {
		"body": [
		  "---\ntitle:\ndescription:\ndate: ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}\ncategories: [\n\n]\ntags: [\n\n]\nlinks:\n  - title: Support the Project\n    description: If you enjoy what I create, you can support the author through this link.\n    website: /en/support\n# lastmod:  # Дата редактирования поста\n# image: string # Изображение поста\n# comments: false # Вкл/Выкл комментариев под данным постом\n# math: true # Вкл/Выкл KaTeX рендеринг\n# toc: false # Вкл/Выкл навигацию по заголовкам справа от поста\n# keywords: []string # Keywords of the page. Useful for SEO.\ndraft: true # Если вкл, то не рендерит эту страницу. Для недописанных постов\n---"
		],
		"description": "Add title and description with current date and time"
	}
}

Теперь, когда я создаю новый пост, то просто нажимаю Ctrl + Shift + P, выбираю Insert Snippets и там выбираю нужный мне шаблон. Обычно это только второй шаблон, который всталяет стартовые данные для страницы, куда надо писать название, описание и прочие настройки поста.

Структура файлов у меня стандартная для этой темы. Я создаю каталог с названием поста в content/post. Туда я вставляю index.ru.md, где находится содержание статьи на русском языке, и файлы, например картинки, которые надо показать на этой странице.

Нюансы при написании постов

Как было сказано в посте про мои изменения темы Stack, у меня есть “проблемы” с тегами. Если просто задать теги в .md файле, то они не будут отображаться. Как это исправить написано на той же странице. Если не нравится - можно отменить мои изменения работы тегов, содержание той статьи позволяет легко в этом разобраться.

Итоги

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

Для удобства напишу спидран установки блога на Hugo:

1
2
3
4
5

sudo pacman -Sy hugo git go
hugo new site hugo-blog && cd hugo-blog
git clone https://github.com/Buliway/hugo-theme-stack/ themes/hugo-theme-stack
cp -r themes/hugo-theme-stack/exampleSite/* ./ && rm hugo.toml
hugo server

Если работает, останавливаем, билдим, отправляем на сервер:

1
2

hugo --cleanDestinationDir
rsync -av --delete "путь/до/каталога/public" "user@ip:/путь/до/каталога/на/сервере"
© 2024 Buliway
Создано при помощи Hugo
Тема Stack, дизайн Jimmy