Синтаксис 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 --> [*]
```

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

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

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 Размещение видео во вкладках

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-->

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


Дмитрий Сергеевич Кулябов
Дмитрий Сергеевич Кулябов
Профессор кафедры теории вероятностей и кибербезопасности

Мои научные интересы включают физику, администрирование Unix и сетей.

Похожие