Синтаксис Markdown для генератора сайтов Hugo

Обновлено 2024-09-13 6 мин. для прочтения Computer-Science

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

Содержание

1 Основные элементы текста

1.1 Заголовки

## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Максимальным уровнем заголовка поста является заголовок второго уровня (это не более, чем конвенция).

1.2 Шрифтовые выделения

_Курсив_ - подчёркивания.
**Полужирный** - двойная звёздочка.
Можно объединить: **звёздочки и  _подчёркивания_**.
Для зачёркивания используем ~~двойную тильду~~.

1.3 Списки

1.3.1 Нумерованные

1. First item
2. Another item

1.3.2 Ненумерованные

* First item
* Another item

1.3.3 Списки с отметками

- [x] Write math example
- [x] Write diagram example
- [ ] Do something else

Для интерактивности списка с отметками необходима поддержки со стороны хостера.

1.4 Встраивание документов

В страницу могут быть встроены документы Google. Чтобы встроить документы Google (например, презентацию):

нажмите Файл -> Опубликовать в Интернете -> Встраивать в Документы Google;
скопируйте URL-адрес в отображаемом атрибуте src="...";

вставьте URL-адрес в форму:

{{< gdocs src="https://docs.google.com/..." >}}

1.5 Сноски

Используются сноски Markdown:

Кроме того [^1], …

[^1]: Текст сноски.

Кроме того ¹, …

2 Изображения

2.1 Одиночные изображения

Статические изображения по-умолчанию подгружаются из каталога assets/media/.

Можно подключать изображение с помощью стандартного оператора markdown:
```
![alternative text for search engines](image.jpg)
```
Наряду со стандартной загрузкой изображений можно использовать и следующую конструкцию:
```
{{< figure library="true" src="image.jpg" title="A caption" >}}
```
Изображение можно помещать в папку страницы:
```
{{< figure src="image.jpg" title="A caption" >}}
```
Можно вставлять нумерованные рисунки:
```
{{< figure src="image.jpg" title="A caption" numbered="true" >}}
```
С оператором figure используется библиотека fancybox для отображения картинок.

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

2.2.1 В папке `assets/media/`

Добавить изображения в подпапку папки assets/media/.
Описать все изображения в заголовке поста:

gallery_item:
  - album: gallery
    image: boards.jpg
    caption: A caption
  - album: gallery
    image: https://<url to image>
    caption: Another caption

Для отображения галереи на странице вставить оператор

{{< gallery >}}

2.2.2 В папке страницы

Создать папку с изображениями внутри папки страницы.
Для отображения галереи на странице вставить оператор

{{< gallery album="<album_folder>" >}}

Дополнительно можно описать изображения в заголовке поста:

gallery_item:
  - album: <album_folder>
    image: <image_name>.jpg
    caption: Image caption

Следует заметить, что для страниц типа doc возможно размещение галереи только в папке assets/media/.

2.3 Диаграммы

Для Markdown поддерживается расширение для рисования диаграмм mermaid (см. Диаграммы. Mermaid).
Для использования нужно включить эту функцию в файле params.toml или добавив diagram: true в преамбуле страницы.

Например, следующий код

```mermaid
stateDiagram
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]
```

преобразуется в

stateDiagram [*] --> Still Still --> [*] Still --> Moving Moving --> Still Moving --> Crash Crash --> [*]

2.4 Графики

Поддерживает библиотека Plotly. Для отрисовки графика следует сохранить файл Plotly в формате json в папке страницы. Например, если файл называется chart.json, то он отрисовывается следующим оператором:

{{< chart data="chart" >}}

Для создания файла json можно использовать онлайн редактор Plotly JSON Editor.

3 Мультимедийные данные

3.1 Аудио

Подключение аудио поддерживается для локальных MP3-файлов:

{{< audio src="audio.mp3" >}}

Путь к файлу задаётся от static/media/.

3.2 Видео

3.2.1 Локальные файлы

Подключение видео из static/media/:

{{< video library="true" src="my_video.mp4" controls="yes" >}}

Подключение видео из папки страницы:

{{< video src="my_video.mp4" controls="yes" >}}

3.2.2 Youtube

Видео, размещённое на Youtube:
```
{{< youtube w7Ft2ymGmfc >}}
```

3.2.3 Vimeo

Видео, размещённое на Vimeo:
```
{{< vimeo 146022717 >}}
```

3.2.4 Rutube

Видео, размещённое на Rutube (см. Сокращение для видео Rutube для Hugo):
```
{{< rutube e6033653f134bd93e79aa2fe81848f09 >}}
```

3.2.5 VK Video

Видео, размещённое на VK Video (см. Hugo shortcode. Видео на VK Video).
Для вставки видео VK Video используется следующая конструкция (с именованными параметрами):
```
{{< vkvideo oid="606414976" id="456239563" hd="2" >}}
```
Для вставки видео VK Video используется следующая конструкция (с позиционными параметрами):
```
{{< vkvideo 606414976 456239563 2 >}}
```

3.2.6 Размещение видео во вкладках

Одно и то же видео, размещённое на разных хостингах, удобно размещать во вкладках.
Hugo. Видео во вкладках

4 Разное

4.1 Таблицы

Таблицы в формате csv можно отображать с помощью оператора:
```
{{< table path="results.csv" header="true" caption="Table 1: My results" >}}
```
Таблица в виде файла csv должна находиться в папке страницы.

4.2 Вкладки

Тема Wowchemy не поддерживает вкладки.
Можно добавить поддержку вкладок: Hugo. Вкладки.

5 Ссылки

5.1 Стандартные ссылки

Можно использовать стандартный формат ссылок Markdown:
```
[I'm a link](https://www.google.com)
```

5.2 Генерация ссылок

Ссылки модно генерить с помощью операторов ref и relref:

{{< ref "document" >}}
{{< ref "document#anchor" >}}
{{< ref "document.md" >}}
{{< ref "document.md#anchor" >}}
{{< ref "#anchor" >}}
{{< ref "/blog/my-post" >}}
{{< ref "/blog/my-post.md" >}}
{{< relref "document" >}}
{{< relref "document.md" >}}
{{< relref "#anchor" >}}
{{< relref "/blog/my-post.md" >}}

ref задаёт абсолютную ссылку, relref — относительную.

Эти ссылки можно использовать внутри стандартных ссылок Markdown:

[A post]({{< ref "/post/my-page-name/index.md" >}})
[A publication]({{< ref "/publication/my-page-name/index.md" >}})
[A project]({{< ref "/project/my-page-name/index.md" >}})
[A relative link from one post to another post]({{< relref "../my-page-name/index.md" >}})
[Scroll down to a page section with heading *Hi*](#hi)

5.2.1 Ссылка на версию на другом языке

Чтобы создать ссылку на версию документа на другом языке, используйте следующий синтаксис:
```
{{< relref path = "document.md" lang = "en"' >}}
```

5.2.2 Ссылка на пакет страниц

При ссылке на пакет страниц необходимо задать путь к пакету.
Возможно придётся задавать полный путь, поскольку краткий (только часть пути) может не сработать.

5.2.3 Другой формат вывода

Чтобы сослаться на другой формат вывода:
```
{{< relref path = "document.md" outputFormat = "rss" >}}
```

5.2.4 Идентификаторы заголовков

Для документов markdown Hugo генерирует идентификаторы элементов для каждого заголовка на странице.
Например, для кода
```
## Reference
```
создаётся следующий HTML:
```
<h2 id="reference">Reference</h2>
```

Ссылку можно задать следующим образом:

{{< ref "document.md#reference" >}}
{{< relref "document.md#reference" >}}

Идентификатор можно задать и явно:
```
## Reference A {#foo}
## Reference B {id="bar"}
```

5.3 Ссылка на статический файл

Ссылка на файл из иерархии static/, обычно размещаемый в подкаталоге static/files/:
```
{{< staticref "files/cv.pdf" "newtab" >}}Download my CV{{< /staticref >}}
```
- Опция newtab используется для открытия файла в новой вкладке.

5.4 Цитирование

Цитирование страницы (ссылка на папку страницы):
```
{{< cite page="/publication/preprint" view="4" >}}
```
Опция view задаёт один из стандартных форматов:
- Stream,
- Compact (установлен по умолчанию),
- Card,
- Параметр устанавливается согласно citation_style из params.toml.

6 Специальные элементы

6.1 Содержание страницы (Table of Contents)

Содержание страницы задаётся с помощью следующего оператора:

{{< toc >}}

Уровни заголовков, попадающие в содержание, задаются в config.toml

[markup.tableOfContents]
   endLevel = 3
   ordered = false
   startLevel = 2

Здесь содержание начинается со второго уровня (это соответствует соглашению об уровнях заголовков), а завершается третьим. При необходимости следует внести изменения.

6.2 Отбивка резюме (Summary Splitter)

Отбивка резюме задаётся конструкцией

<!--more-->

Текст сноски. ↩︎

Links to this note

Hugo