Предыстория
Три года назад, когда я вообще не понимал, что такое программирование, не видел грань между фронт-эндом и бэк-эндом - я не подозревал, что на каждой стадии разработки сайта могут начаться проблемы. Я не понимал самой сущности как сайт. Я не понимал как работает http протокол, какая разница между GET и POST методом. Как работает URI, из каких частей он состоит. Я знал что есть php, есть CMS, которые делают всё за тебя. Я знал что существует тот же ucoz. И имея минимальный опыт во фронт-энде можно делать красивые, но однотипные сайты.
Спустя всё это время я прокачал свои скиллы в написании всего. Я писал свои парсеры, сервисы, всякие скрипты для расчёта всего, чего было лень считать в тетрадке. На сегодняшний день я стал самодостаточным, для того что бы делать крупные проекты, используя тонны инструментов, но столкнулся с одной и достаточно очевидной проблемой - время.
Все проекты которые я писал больше недели - не имели никакого смысла. И как бы есть на что мне грешить. Мб это недостаток опыта в программировании, слишком большие цели для одного человека, неправильный подбор инструментов для проекта или может быть дело в плохой планировки задач.
Очевидно проблема глобальная и всем очевидно, что чем быстрее проект выйдет в продакшен, тем лучше для всех. И главная проблема время. Время - это важный ресурс, который никак не восполнить. И в очередной раз я столкнулся с этой проблемой.
У меня появилась задача. Написать документацию для одного проекта. Стартовый капитал 0 рублей.
С начала выбирался хостинг. Из всех возможных бесплатных вариантов был только Github Pages. Мне не нужен был бэк-энд в моём проекте и поэтому он подходил идеально.
Потом появилась проблема написании самой документации.
Проект на C# и поэтому один из решений - это прописать комментарии к коду (так как в этом языке это можно сделать красиво и просто) и как вариант воспользоваться автогенерацией документации на основе кода.
К сожалению кода в открытом доступе не существует и поэтому этот вариант отпадает.
Второй вариант. Сделать проект на NodeJS и собирать все при помощи WebPack'а. Вариант не из простых, так как на вёрстку я потрачу много времени, а ещё я не сильно понимаю в этом. Хорошие шаблоны найти очень сложно, а если и есть например красивые, то они построены на технологиях древних, по типу jQuery, а такие вещи в современной javascript адаптировать очень сложно. Я потратил 2 дня на попытку сделать всё хорошо, но получилось никак. Так как процесс написания контента в виде HTML-кода - занимала уйма времени.
Следующие 2 дня я думал как бороться с этой проблемой. Я думал, как можно упростить задачу. Написать свой markdown, с таким синтаксисом, в котом можно было бы задавать в заголовках текста свой id, для создание простых меню, что бы пользователю было просто. В конце концов я понял, что это уже переусложнение ради ничего.
Сама идея использовать Markdown как контент не нова сама по себе. Например сейчас с помощи md делаются Readme файлы в Github'е, оформляются сообщение в Telegram и Discord'е и я уверен есть куча инструментов для этого. Но мы поговорим об одном из них. Это Hugo.
Hugo
На сайте самого Hugo написано следующее:
The world’s fastest framework for building websites
Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.
Тут говорится что Hugo это во первых фрэймворк (это означает что своевольничать тут мало где получится (но на самом деле это не так)). Это генератор статических сайтов. И очень много слов по типу "быстрый, популярный, гибкий".
Это всё правда, и даже про получении удовольствия в построении сайта.
Во первых начнём с самого главного.
Как мы хотим использовать Hugo. Для каждого может быть 2 пути. Использовать готовое или писать самому.
Сразу скажу что, для того, что бы писать самому, красивый сайт для Hugo, нужно знать:
- Вёрстку (HTML+CSS)
- JavaScript
- Иметь некоторые знание в NodeJS и npm
Проект сделан на Golang'е поэтому шаблоны там стандартные из go.
И это уже говорит о том, что для этого нужно иметь много знаний и опыта в написании сайтов.
( Если вы всё же выбрали первый путь, то у Hugo есть отличная документация, только на английском языке. )
Так что этот путь не для нас, мы же хотим сделать всё как можно быстрее.
Второй путь, как говорил выше. Использовать готовое. Готовых шаблонов/тем для hugo сейчас полно. Они достаточно красивые и позволяют сильно сократить время производства сайта.
На сайте Hugo есть раздел Hugo Themes, в котором очень много разных шаблонов для всего. Для блогов, сайтов визиток, галерей, презентаций проектов и что для меня было важно, для документации. Для себя я выбрал тему Geekdoc, так как у него уже была тёмная тема, хорошая адаптивная вёрстка и куча shortcod'ов, о которых мы поговорим потом.
Для начала нужно поставить сам Hugo. Для этого нужно зайти на их github и зайти в их релизы. В документации для Geekdoc шаблона говорится что необходим extended версия Hugo. В моём случае это hugo_extended_0.88.1_Windows-64bit.zip.
Внутри архива у нас есть hugo.exe, который нужно положить куда нибудь.
Из вариантов это System32, в папку с проектом, в любую папку к которому нужно прописать путь в %PATH%. Либо если у вас есть go, положить в папку bin с вашим go.exe. Я выбрал последний вариант, так как мне это было удобнее всего.
Нужно создать проект.
В терминале нужно написать
hugo new site quickstart
"quickstart" это будет название нашего сайта.
Далее создаём файл конфигурации, на выбор 3 формата. json, toml, yaml. Из всех, мне лично понравился yaml, хотя с json я работал больше всего.
Создаём файл с названием config.toml
Я понимаю что я сказал что мне yaml больше понравилось, но в моём случае это был toml. Не бейте)
Прописываем 3 строки
baseURL = 'https://compico.github.io/rutonychat-docs/'
title = 'RutonyChat - Docs'
theme = "hugo-geekdoc"
baseURL - это url. Вы можете выбрать любое, но нужно больше для уже собранного сайта.
title - это название сайта, будет прописан сам везде где только возможно.
theme - это название темы, у вас будет своё, если не у вас тема не Geekdoc.
Так же важно прописать путь уже сгенерированного статического сайта.
Это важно потому что в Github Pages за бесплатно можно выбрать корневую папку или папку docs. Поэтому нужно прописать так же в конфиге, что бы готовый сайт сохранялся в папку docs.
Для этого я прописываю всё туда же в config.toml
publishDir = 'docs'
Дальше уже у меня идут настройки темы именно под себя.
Для примера у меня на гитхабе уже лежит готовый проект и вы можете сами прочитать файл конфигурации.
Дальше в папку themes нужно положить нашу тему. Я скачал и положил папку hugo-geekdoc прямо в themes и больше ничего не нужно.
Запускаем. Для этого пишем в терминал
hugo server -D --disableFastRender
Я отключаю FastRender, так как я изредко всё же менял тему под себя а в FastRender имеется кэш, который всё портит. Но разница сборки сайта было в 10ms, так что это для глаза не заметно.
И по ссылке в терминале захожу на сайт и вижу как всё работает.
Дальше в папке content я создаю файл _index.md
Это контент нашей главной страницы.
В верху файла прописываются кофигурации данной страницы.
---
title: "RutonyChat - Docs"
weight: 1
---
Название и `вес?` страницы. Вес не особо понятно для чего, но я добавлял +1 к каждой подкатегории.
Ниже я пишу сам контент.
К примеру
# Документация RutonyChat
Здесь очень много полезного и так далее.
Дальше допустим мне нужно вставить кусок кода.
```go
func main() {
print("Привет мир!")
}
```
Этот код уже автоматически форматируется как мне нужно. Смотрим на результат.
Как мы видим, в результате мы получили то, чего мы хотели.
Есть ещё shortcodes. Допустим мы не хотим что бы код был виден изначально, а хотим что бы он был скрыт.
Для этого пишем
{{< expand "Пример" >}}
```go
func main()
{
print("Привет мир!")
}
```
{{< /expand >}}
И теперь код скрыт, и для того что бы его увидеть, его нужно развернуть.
Shortcodes разные для своих тем. А в теме Geekdoc есть например кнопки, построение диаграмм, сложных формул в формате KaTeX, колонны и ещё например тот же expand.
Резюме или tl;dr.
Hugo это очень полезный инструмент для создания статических сайтов, где контент это Markdown файл. Он очень удобный и очень полезный. Я не рассказал ещё очень многого, но если я продолжу, но вы ещё сильнее удивитесь, насколько удобен и гибок Hugo. Так же в некоторых случая он может сократить время разработки многих вещей. Попробуйте его для себя, как будет время, не пожалеете.