Ведём блог (делаем сайт) с HUGO и AsciidocFX

HUGO - это софт из плеяды "static site generators". Буквально в трёх словах - на входе у него документы в маркап-форматах (markdown, asciidoc, reST, pandoc) и метаданные, какую тему использовать, какую структуру делать и прочее. На выходе - готовый статический html сайт с заданными темами. Соответственно его можно тем или иным способом залить на хостинг, некоторые способы вшиты с сам hugo.

При выборе SSG рассматривал не только HUGO, но и бегло посмотрел некоторых прочих. Их конечно более чем один.

• Jekill - С Jekill ( https://jekyllrb.com/ ) наверное знаком любой пользователь git-hub, он там почти стандарт де-факто. Но к сожалению автономно в Windows нормально завести его не вышло. Для Windows нужны танцы с бубном. Зато если вы работаете в Linux и неплохо знакомы с Ruby, то это хороший выбор.

• Antora - ( https://antora.org/ ) SSG рекомендованный авторами AsciidocFX. Очень много возможностей, но требует node.js; Родной язык разметки - asciidoc. Как там с маркдаун, не знаю. И на мой взгляд минус - слишком тесная интеграция с git. Часть функционала git встроена в Antora и объявлена фичей. Я всё-таки предпочитаю чтобы git отдельно, сайто-софт отдельно. Наверное на нём хорошо делать документация для больших проектов. Когда и так установлена нода, и проекты большие - тогда наверное Antora.

• и наконец HUGO. ( https://gohugo.io/ ) Я когда увидел его размер, почти сразу влюбился :-) Он маленький, без зависимостей и всего один файл. По возможностям примерно равен вышеуказанным, из коробки поддерживает сразу несколько входных форматов и графических к нему тем дофига.

Мне самый раз HUGO : не надо качать и поддерживать инфраструктуру, плюс вопросы дизайна можно отложить на потом.

Выбор языка разметки глубоко личное дело каждого. Мне более симпатичен Asciidoc, на мой взгляд он больше подходит для технических публикаций чем markdown. В любом случае основной принцип - фокусировка на смысле а не на оформлении. Работа с контентом как с кодом. Для программиста это привычно.

Громадным плюсом Asciidoc является редактор AsciidocFX ( https://www.asciidocfx.com/). Можно конечно навесить плагинов в студию или другие редакторы и писать нетленку прямо не выходя из IDE. Но отдельно всё-таки лучше ;-) Он мультиплатформенный и есть для Windows, Linux,MacOS.

правила разметки не сильно отличаются от wiki, markdown и можно подсмотреть в:

• на сайте asciidoctor https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/

• или вот ещё удобно https://powerman.name/doc/asciidoc-compact

• потренироваться/ознакомиться можно тут https://w3speedup.com/tools/asciidoctor-live-preview/

AsciidocFX совсем элементарно - качается дистрибутив, тыкается exe-шник и далее-далее-далее.

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

Понадобиться ещё asciidoctor, рендер asciidoc в прочие форматы. Можно следовать инструкции оф.сайта https://asciidoctor.org/#windows , но лучший способ см.далее

Для Hugo есть хороший альтернативный путь - если у вас как у меня установлен msys2 то лучше воспользоваться его пакетным менеджером :

• запускам консоль msys2

• смотрим имя пакета pacman -Ss hugo выбираем подходящий, у меня всё с ucrt, значит его и беру pacman -S mingw-w64-ucrt-x86_64-hugo

• аналогично для asciidoctor; если вы будете использовать только markdown то шаг пропустить.

• всё, софт поставлен и готов к работе

Авторы Hugo рекомендуют в качестве консоли использовать Power Shell, но если поставлен msys2 то лучше сразу родной bash - консоль msys

Открываем консоль, делаем где-нибудь себе каталог, например sites; В нём будут все наши сайты. Переходим в него и дальше следуем QuickStart (https://gohugo.io/getting-started/quick-start/). Там всего несколько команд, детальнейше разобранны и официальное руководство не буду цитировать.

Пара нюансов если используете Asciidoc: надо в настройках нового сайта разрешить запуск asciidoctor. То есть отредактировать файл hugo.toml и добавить разрешения:

и в начало страницы добавить мелкий макрос указывающий правильный пути к картинкам (подсмотрено тут: https://stackoverflow.com/questions/78406461/path-predicament-navigating-image-rendering-discrepancies-between-asciidoctor-p )

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

далее как по QuickStart - запускаем тестовый сервер: hugo server --buildDrafts

и открываем в браузере localhost://1313

В консоле просто вводим команду hugo и сайт полностью генериться в каталог public. Результат можно перенести любыми способами на хостинг. Скопировать файлы или использовать rsync или git. Как угодно. Любой хостинг естественно поддерживает статические сайты и всё там будет работать.

То есть захотим отдельный сайт - получим его одной командой

Немного сложнее публиковать на mql5. Продвинутые трейдерские технологии не поддерживают импорт из html или стандартный docbook, поэтому почти врукопашную:

1) На сайте mql5 создаём новую запись блога

2) в preview AsciidocFX мышкой выделяем всю страницу сверху донизу, жмём Copy

3) в редакторе блога жмём Paste - получаем всю страницу, но со стилями принятыми на сайте MQL5

4) внимательно просматриваем и по мере необходимости заливаем картинки. В данном случае две - внешний вид AsciidocFX и начальный вид блога

5) вносим мелкие правки, в частности inline код корёжится - придётся форматировать или отдельно copy-paste. (стиль "код" это непосильная задача для местных веб-дизайнеров)