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

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

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

Содержание

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

1.1 Заголовки

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

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

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

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

1.3 Списки

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

11. First item
22. Another item

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

1* First item
2* Another item

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

1- [x] Write math example
2- [x] Write diagram example
3- [ ] Do something else

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

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

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

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

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

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

1.5 Сноски

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

1Кроме того [^1], …
2
3[^1]: Текст сноски.

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

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

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

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

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

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

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

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

1gallery_item:
2  - album: gallery
3    image: boards.jpg
4    caption: A caption
5  - album: gallery
6    image: https://<url to image>
7    caption: Another caption

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

1{{< gallery >}}

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

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

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

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

1gallery_item:
2  - album: <album_folder>
3    image: <image_name>.jpg
4    caption: Image caption

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

2.3 Диаграммы

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

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

1```mermaid
2stateDiagram
3[*] --> Still
4Still --> [*]
5Still --> Moving
6Moving --> Still
7Moving --> Crash
8Crash --> [*]
9```

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

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

2.4 Графики

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

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

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

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

3.1 Аудио

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

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

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

3.2 Видео

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

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

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

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

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

3.2.2 Youtube

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

3.2.3 Vimeo

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

3.2.4 Rutube

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

3.2.5 Платформа

Видео, размещённое на Платформа (см. Сокращение для видео Платформа для Hugo):
```
1{{< plvideo 1SW2MCtcggzo >}}
```

3.2.6 VK Video

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

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

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

4 Разное

4.1 Таблицы

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

4.2 Вкладки

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

5 Ссылки

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

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

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

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

 1{{< ref "document" >}}
 2{{< ref "document#anchor" >}}
 3{{< ref "document.md" >}}
 4{{< ref "document.md#anchor" >}}
 5{{< ref "#anchor" >}}
 6{{< ref "/blog/my-post" >}}
 7{{< ref "/blog/my-post.md" >}}
 8{{< relref "document" >}}
 9{{< relref "document.md" >}}
10{{< relref "#anchor" >}}
11{{< relref "/blog/my-post.md" >}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1{{< toc >}}

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

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

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

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

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

1<!--more-->

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

Links to this note

Hugo