Введение

Эта статья содержит в себе сборник всех изначально встроенных статей в эту тему Hugo. Тут будет всё о markdown для написания статей. Как именно это написать в .md файле я показывать буду лишь частично. Полностью можно посмотреть в файле на github. Эта статья скорее для меня как для админа, чтоб я мог вернуться и глянуть как пишется какой-либо функционал.

В начале статьи надо добавить поле, которое называется frontmatter. В документации написаны все возможные параметры, которые туда можно написать. Выделить настройки можно либо через ---, либо через +++. Разница в том, что --- будет иметь синтаксис yaml формата, а +++ будет иметь синтаксис toml. В настройки, например, можно добавить поле series = ["Themes Guide"]. Это будет означать серию статей о какой-то теме, чтоб читатели могли видеть связанный контент. Как я понимаю, речь про рекомендации в конце поста. Хотя рекомендации, в теории, должны работать и без этого, просто по общим категориям и тегам.

Справа есть навигация по заголовкам. Её можно выключить, если в начало файла добавить toc: false. В этой навигации отображаются только заголовки 2-4 уровней. Глубже не отобразит. Но это всё можно поменять в hugo.yaml.

Изначально описание статьи, которое отображается на главной странице, пишется в начале файла в графе description. Но можно включить режим, когда в описание помещается маленькая часть начала статьи. Для такого сценария есть свой синтаксис, который требует написать <!--more--> в том месте, до которого должно быть описание поста.

Внутри markdown можно писать html код для изменения визуала. Например, я могу покрасить этот текст в чёрный на розовом фоне так:

1

<span style="background: #FF5582A6;color:black">я могу покрасить этот текст в чёрный на розовом фоне</span>

Если символ используется для markdown, но его хочется написать как есть, без использования в форматировании текста, то надо использовать \ перед ним. Я так поступил с примером выше, который изначально выглядит так: \<\!\-\-more\-\-\>.

Чтоб оставить ссылку на другой пост, я предпочитаю пользоваться абсолютными путями относительно каталога content. Например, если я хочу ссылаться на пост, который находится в content/page/Archives, то мне надо написать так, что в markdown будет выглядеть [так]({{< ref “/page/Archives” >}}). Оно будет работать даже в том случае, если в каталоге Архивы будет находиться несколько .md файлов для разных языков. Он отправит на ту страницу, язык которой выбран у пользователя в настройках.

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

Стандартный Markdown

Заголовки

Заголовки разного уровня пишутся через #

1
2
3
4
5
6

# H1
## H2
### H3
#### H4
##### H5
###### H6

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

Параграф

Xerum, quo qui aut unt expliquam qui dolut labo. Aque venitatiusda cum, voluptionse latur sitiae dolessi aut parist aut dollo enim qui voluptate ma dolestendit peritin re plis aut quas inctum laceat est volestemque commosa as cus endigna tectur, offic to cor sequas etum rerum idem sintibus eiur? Quianimin porecus evelectur, cum que nis nust voloribus ratem aut omnimi, sitatur? Quiatem. Nam, omnis sum am facea corem alique molestrunt et eos evelece arcillit ut aut eos eos nus, sin conecerem erum fuga. Ri oditatquam, ad quibus unda veliamenimin cusam et facea ipsamus es exerum sitate dolores editium rerore eost, temped molorro ratiae volorro te reribus dolorer sperchicium faceata tiustia prat.

Itatur? Quiatae cullecum rem ent aut odis in re eossequodi nonsequ idebis ne sapicia is sinveli squiatum, core et que aut hariosam ex eat.

Цитаты

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

Цитаты без автора

Tiam, ad mint andaepu dandae nostion secatur sequo quae. Note that you can use Markdown syntax within a blockquote.

Цитаты с автором

На однёрку можно нажать, она отправит в конец страницы со ссылками на первоисточник.

Don’t communicate by sharing memory, share memory by communicating.
— Rob Pike¹

Таблицы

Таблицы не являются частью основной спецификации Markdown, но Hugo поддерживает их из коробки.

Markdown в таблицах

Блоки кода

Блок кода с указанием языка

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

Блок кода с отступом в четыре пробела

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

    <!doctype html>
    <html lang="en">
    <head>
      <meta charset="utf-8">
      <title>Example HTML5 Document</title>
    </head>
    <body>
      <p>Test</p>
    </body>
    </html>

Блок кода со встроенным шорткодом Hugo

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

Блок кода с различиями (как в гите)

1
2
3
4
5

[dependencies.bevy]
git = "https://github.com/bevyengine/bevy"
rev = "11f52b8c72fc3a568e8bb4a4cd1f3eb025ac2e13"
- features = ["dynamic"]
+ features = ["jpeg", "dynamic"]

Типы списков

Упорядоченный список

1. First item
2. Second item
3. Third item

Неупорядоченный список

• List item
• Another item
• And another item

Вложенный список

• Fruit
  • Apple
  • Orange
  • Banana
• Dairy
  • Milk
  • Cheese

Остальные элементы — abbr, sub, sup, kbd, mark

GIF is a bitmap image format.

H₂O

Xⁿ + Yⁿ = Zⁿ

Press CTRL + ALT + Delete to end the session.

Most salamanders are nocturnal, and hunt for insects, worms, and other small creatures.

Hyperlinked image

Галерея изображений

Можно делать галерею изображений. По ним можно нажать и листать. Для примера приложил 4 изображения, которые сгенерировал ChatGPT по просьбе создать логотип для Discord канала. В данном примере три изображения сверху и одно снизу, но при пролистывании они будут в одном цикле прокрутки.

Поддержка эмодзи

Эмодзи можно включить в Hugo несколькими способами

Функцию emojify можно вызывать напрямую в шаблонах или через Inline Shortcodes.

Чтобы включить emoji глобально, установите enableEmoji: true в конфиге сайта, после чего вы сможете использовать сокращенные коды emoji непосредственно в файлах контента;

🙈 :see_no_evil: 🙉 :hear_no_evil: 🙊 :speak_no_evil:

Emoji cheat sheet - полезный справочник для сокращенных кодов emoji.

Примечание Вышеуказанные шаги позволяют использовать стандартные символы и последовательности emoji Unicode в Hugo, однако отображение этих символов зависит от браузера и платформы. Для стилизации emoji вы можете использовать сторонний шрифт emoji или стек шрифтов, например:

1
2
3

.emoji {
  font-family: Apple Color Emoji, Segoe UI Emoji, NotoColorEmoji, Segoe UI Symbol, Android Emoji, EmojiSymbols;
}

Математические формулы

Математическую запись в Hugo можно добавить при помощи сторонних JavaScript библиотек.

В этом примере мы будем использовать KaTeX

• Создать шаблон /layouts/partials/math.html
• В этом шаблоне используется Auto-render Extension, но можно хостить этот скрипт локально.
• Вставить это в шаблон:

1
2
3

{{ if or .Params.math .Site.Params.math }}
{{ partial "math.html" . }}
{{ end }}

• Для включения KaTeX глобально, надо указать math: true в конфиге проекта.
• Для включения KaTeX отдельно на каждой странице, надо указать math: true в начало файла.

Примечание: Используйте онлайн-справочник поддерживаемых функций TeX

Пример

Математические выражения в строке: $\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…$

Математические выражения в блоке: $$ \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } } $$

Hugo Shortcodes

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

YouTube Privacy Enhanced Shortcode

Twitter Simple Shortcode

“In addition to being more logical, asymmetry has the advantage that its complete appearance is far more optically effective than symmetry.”
— Jan Tschichold pic.twitter.com/gcv7SrhvJb

— Design Reviewed | Graphic Design History (@DesignReviewed) January 17, 2019

Vimeo Simple Shortcode

bilibilibi Shortcode

Gist Shortcode

Gitlab Snippets Shortcode

Quote Shortcode

Stack adds a quote shortcode. For example:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

― A famous person, The book they wrote

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

― Anonymous book

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

― Some book

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

― Somebody

Приложить ссылки в конце статьи

Чтоб использовать эту функцию, надо добавить links в верхнюю часть файла .md, где находятся настройки страницы.

На этой странице оно выглядит так:

1
2
3
4
5
6
7
8

links:
  - title: GitHub
    description: GitHub is the world's largest software development platform.
    website: https://github.com
    image: https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png
  - title: Помочь проекту
    description: Если вам нравится то, что я делаю, то можете поддержать автора по этой ссылке.
    website: /donate

Поле image может содержать как ссылку на онлайн изображение, так и на локальный файл. Если какое-то изображение используется в разных постах и его не хочется дублировать в каталог каждого отдельного поста, то можно поместить картинку в каталог static и вызываеть её, начиная символом /, что я и сделал. Если бы изображение boosty.png было в каталог поста, то я бы написал просто boosty.png, без / в начале пути.