Синтаксис Markdown для генератора сайтов Hugo
В данном случае описывается вариант 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]: Текст сноски.
Кроме того 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 --> [*]
```
преобразуется в
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 генерирует идентификаторы элементов для каждого заголовка на странице.
- Например, для кодасоздаётся следующий HTML:
## Reference
<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-->
Текст сноски. ↩︎