Форматы контента

Вы можете поместить файлы любого типа в каталоги /content, но Hugo использует начальное значение markup, если установлено, или расширение файла (смотрите Markup identifiers в таблице ниже), чтобы определить, нужно ли обрабатывать разметку, например:

Markdown преобразован в HTML
Обработка Шорткодов
Примененный макет

Список форматов контента

Текущий список форматов контента в хьюго:

Название	Идентификаторы разметки	Комментарий
Goldmark	md, markdown, goldmark	Обратите внимание, что Вы можете установить обработчик по умолчанию для `md` и `markdown` на что-нибудь другое, смотрите настройку разметки.
Blackfriday	blackfriday	Поддержка Blackfriday в со временем будет прекращена.
MMark	mmark	Mmark устарел и будет удален в следующем выпуске.
Emacs Org-Mode	org	Смотрите go-org.
AsciiDoc	asciidocext, adoc, ad	Необходим установленный Asciidoctor.
RST	rst	Необходим установленный RST.
Pandoc	pandoc, pdc	Необходим установленный Pandoc.
HTML	html, htm	Чтобы его можно было рассматривать как файл содержимого с макетом, шорткодами и т.д., он должен иметь предварительную информацию. В противном случае он будет скопирован как есть.

markup identifier извлекается либо из переменной markup в начале, либо из расширения файла. Для конфигурации, связанной с разметкой, смотрите Настройка разметки.

Внешние помощники

Для некоторых форматов, указанных в таблице выше, на Вашем компьютере должны быть установлены внешние помощники. Например, для файлов AsciiDoc Хьюго попытается вызвать команду asciidoctor. Это означает, что Вам необходимо установить соответствующий инструмент на свой компьютер, чтобы использовать эти форматы.

По умолчанию Хьюго передает этим внешним помощникам разумные аргументы по умолчанию:

asciidoctor: --no-header-footer -
rst2html: --leave-comments --initial-header-level=2
pandoc: --mathjax

Внешний помощник AsciiDoc

AsciiDoc реализация EOLs в январе 2020 г. и больше не поддерживается. Разработка AsciiDoc продолжается в Asciidoctor. Формат AsciiDoc остается конечно. Продолжайте реализацию Asciidoctor.

Внешний помощник Asciidoctor

Сообщество Asciidoctor предлагает широкий набор инструментов для формата AsciiDoc, которые можно установить дополнительно к Hugo. Смотрите инструкции по установке в документации Asciidoctor. Убедитесь, что при необходимости установлены все дополнительные расширения, такие как asciidoctor-diagram или asciidoctor-html5s.

Некоторые параметры Asciidoctor можно настроить в Hugo:

Параметр	Комментарий
backend	Не меняйте это, если Вы не знаете, что делаете.
doctype	В настоящее время в Hugo поддерживается только тип документа `article`.
extensions	Возможные расширения: `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, `asciidoctor-question`, `asciidoctor-rouge`.
attributes	Переменные, на которые следует ссылаться в Вашем файле AsciiDoc. Это список отображений имен и значений переменных. Смотрите атрибуты Asciidoctor.
noHeaderOrFooter	Выведите встраиваемый документ, исключая заголовок, нижний колонтитул и все, что находится за пределами тела документа. Не меняйте это, если Вы не знаете, что делаете.
safeMode	Уровень безопасного режима `unsafe`, `safe`, `server` или `secure`. Не меняйте это, если вы не знаете, что делаете.
sectionNumbers	Авто-нумерация заголовков разделов.
verbose	Подробно распечатайте информацию об обработке и проверках файла конфигурации в stderr.
trace	Включите информацию об ошибках.
failureLevel	Минимальный уровень ведения журнала, при котором запускается ненулевой код выхода (сбой).

Hugo предоставляет дополнительные настройки, которые не сопоставляются напрямую с параметрами интерфейса командной строки Asciidoctor:

workingFolderCurrent: Устанавливает рабочий каталог таким же, как и у обрабатываемого файла AsciiDoc, так что включение будет работать с относительными путями. Этот параметр использует asciidoctor cli параметр --base-dir и атрибут outdir=. Для отображения диаграмм с asciidoctor-diagram, workingFolderCurrent должно быть установлено значение true.
preserveTOC: По умолчанию Hugo удаляет оглавление, созданное Asciidoctor, и предоставляет его с помощью встроенной переменной .TableOfContents, чтобы обеспечить дальнейшую настройку и лучшую интеграцию с различными темами Hugo. Для этой опции можно установить значение true, чтобы сохранить содержание Asciidoctor на сгенерированной странице.

Ниже приведены все настройки, связанные с AsciiDoc в Hugo, со значениями по умолчанию:

config.

markup:
  asciidocExt:
    attributes: {}
    backend: html5
    extensions: []
    failureLevel: fatal
    noHeaderOrFooter: true
    preserveTOC: false
    safeMode: unsafe
    sectionNumbers: false
    trace: false
    verbose: false
    workingFolderCurrent: false

[markup]
  [markup.asciidocExt]
    backend = "html5"
    extensions = []
    failureLevel = "fatal"
    noHeaderOrFooter = true
    preserveTOC = false
    safeMode = "unsafe"
    sectionNumbers = false
    trace = false
    verbose = false
    workingFolderCurrent = false
    [markup.asciidocExt.attributes]

{
   "markup": {
      "asciidocExt": {
         "attributes": {},
         "backend": "html5",
         "extensions": [],
         "failureLevel": "fatal",
         "noHeaderOrFooter": true,
         "preserveTOC": false,
         "safeMode": "unsafe",
         "sectionNumbers": false,
         "trace": false,
         "verbose": false,
         "workingFolderCurrent": false
      }
   }
}

Пример того, как установить расширения и атрибуты:

[markup.asciidocExt]
    extensions = ["asciidoctor-html5s", "asciidoctor-diagram"]
    workingFolderCurrent = true
    [markup.asciidocExt.attributes]
        my-base-url = "https://example.com/"
        my-attribute-name = "my value"

В сложной среде Asciidoctor иногда бывает полезно отладить точный вызов Вашего внешнего помощника со всеми параметрами. Запустите Hugo с -v. Вы получите результат вроде

INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ...

Изучение разметки

Синтаксис Markdown достаточно прост, чтобы изучить его за один присест. Ниже приведены отличные ресурсы, которые помогут Вам начать работу: