Конфигурация разметки

Смотрите Goldmark для настроек, связанных с обработчиком Markdown по умолчанию в Hugo.

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

config.

markup:
  asciidocExt:
    attributes: {}
    backend: html5
    extensions: []
    failureLevel: fatal
    noHeaderOrFooter: true
    preserveTOC: false
    safeMode: unsafe
    sectionNumbers: false
    trace: false
    verbose: false
    workingFolderCurrent: false
  blackFriday:
    angledQuotes: false
    extensions: null
    extensionsMask: null
    footnoteAnchorPrefix: ""
    footnoteReturnLinkContents: ""
    fractions: true
    hrefTargetBlank: false
    latexDashes: true
    nofollowLinks: false
    noreferrerLinks: false
    plainIDAnchors: true
    skipHTML: false
    smartDashes: true
    smartypants: true
    smartypantsQuotesNBSP: false
    taskLists: true
  defaultMarkdownHandler: goldmark
  goldmark:
    extensions:
      definitionList: true
      footnote: true
      linkify: true
      strikethrough: true
      table: true
      taskList: true
      typographer: true
    parser:
      attribute: true
      autoHeadingID: true
      autoHeadingIDType: github
    renderer:
      hardWraps: false
      unsafe: false
      xhtml: false
  highlight:
    anchorLineNos: false
    codeFences: true
    guessSyntax: false
    hl_Lines: ""
    lineAnchors: ""
    lineNoStart: 1
    lineNos: false
    lineNumbersInTable: true
    noClasses: true
    style: monokai
    tabWidth: 4
  tableOfContents:
    endLevel: 3
    ordered: false
    startLevel: 2

[markup]
  defaultMarkdownHandler = "goldmark"
  [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.blackFriday]
    angledQuotes = false
    footnoteAnchorPrefix = ""
    footnoteReturnLinkContents = ""
    fractions = true
    hrefTargetBlank = false
    latexDashes = true
    nofollowLinks = false
    noreferrerLinks = false
    plainIDAnchors = true
    skipHTML = false
    smartDashes = true
    smartypants = true
    smartypantsQuotesNBSP = false
    taskLists = true
  [markup.goldmark]
    [markup.goldmark.extensions]
      definitionList = true
      footnote = true
      linkify = true
      strikethrough = true
      table = true
      taskList = true
      typographer = true
    [markup.goldmark.parser]
      attribute = true
      autoHeadingID = true
      autoHeadingIDType = "github"
    [markup.goldmark.renderer]
      hardWraps = false
      unsafe = false
      xhtml = false
  [markup.highlight]
    anchorLineNos = false
    codeFences = true
    guessSyntax = false
    hl_Lines = ""
    lineAnchors = ""
    lineNoStart = 1
    lineNos = false
    lineNumbersInTable = true
    noClasses = true
    style = "monokai"
    tabWidth = 4
  [markup.tableOfContents]
    endLevel = 3
    ordered = false
    startLevel = 2

{
   "markup": {
      "asciidocExt": {
         "attributes": {},
         "backend": "html5",
         "extensions": [],
         "failureLevel": "fatal",
         "noHeaderOrFooter": true,
         "preserveTOC": false,
         "safeMode": "unsafe",
         "sectionNumbers": false,
         "trace": false,
         "verbose": false,
         "workingFolderCurrent": false
      },
      "blackFriday": {
         "angledQuotes": false,
         "extensions": null,
         "extensionsMask": null,
         "footnoteAnchorPrefix": "",
         "footnoteReturnLinkContents": "",
         "fractions": true,
         "hrefTargetBlank": false,
         "latexDashes": true,
         "nofollowLinks": false,
         "noreferrerLinks": false,
         "plainIDAnchors": true,
         "skipHTML": false,
         "smartDashes": true,
         "smartypants": true,
         "smartypantsQuotesNBSP": false,
         "taskLists": true
      },
      "defaultMarkdownHandler": "goldmark",
      "goldmark": {
         "extensions": {
            "definitionList": true,
            "footnote": true,
            "linkify": true,
            "strikethrough": true,
            "table": true,
            "taskList": true,
            "typographer": true
         },
         "parser": {
            "attribute": true,
            "autoHeadingID": true,
            "autoHeadingIDType": "github"
         },
         "renderer": {
            "hardWraps": false,
            "unsafe": false,
            "xhtml": false
         }
      },
      "highlight": {
         "anchorLineNos": false,
         "codeFences": true,
         "guessSyntax": false,
         "hl_Lines": "",
         "lineAnchors": "",
         "lineNoStart": 1,
         "lineNos": false,
         "lineNumbersInTable": true,
         "noClasses": true,
         "style": "monokai",
         "tabWidth": 4
      },
      "tableOfContents": {
         "endLevel": 3,
         "ordered": false,
         "startLevel": 2
      }
   }
}

Смотрите подробности в каждом разделе ниже.

Goldmark

Goldmark взят из Hugo 0.60 - библиотеки по умолчанию, используемой для Markdown. Это быстро, совместимо с CommonMark и очень гибко. Обратите внимание, что набор функций Goldmark vs Blackfriday отличается; Вы много приобретаете, но и теряете что-то, но мы будем работать над устранением пробелов в следующих версиях Hugo.

Это конфигурация по умолчанию:

config.

markup:
  goldmark:
    extensions:
      definitionList: true
      footnote: true
      linkify: true
      strikethrough: true
      table: true
      taskList: true
      typographer: true
    parser:
      attribute: true
      autoHeadingID: true
      autoHeadingIDType: github
    renderer:
      hardWraps: false
      unsafe: false
      xhtml: false

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      definitionList = true
      footnote = true
      linkify = true
      strikethrough = true
      table = true
      taskList = true
      typographer = true
    [markup.goldmark.parser]
      attribute = true
      autoHeadingID = true
      autoHeadingIDType = "github"
    [markup.goldmark.renderer]
      hardWraps = false
      unsafe = false
      xhtml = false

{
   "markup": {
      "goldmark": {
         "extensions": {
            "definitionList": true,
            "footnote": true,
            "linkify": true,
            "strikethrough": true,
            "table": true,
            "taskList": true,
            "typographer": true
         },
         "parser": {
            "attribute": true,
            "autoHeadingID": true,
            "autoHeadingIDType": "github"
         },
         "renderer": {
            "hardWraps": false,
            "unsafe": false,
            "xhtml": false
         }
      }
   }
}

Подробнее о расширениях смотрите этот раздел документации Goldmark.

Пояснения к некоторым настройкам:

unsafe: По умолчанию Goldmark не отображает необработанный HTML и потенциально опасные ссылки. Если у Вас много встроенного HTML и/или JavaScript, Вам может потребоваться включить это.
typographer: Это расширение заменяет знаки препинания типографскими объектами, такими как smartypants.
autoHeadingIDType (“github”): Стратегия, используемая для создания автоматических идентификаторов (имен привязок). Доступные типы: github, github-ascii и blackfriday. github создает идентификаторы, совместимые с GitHub, github-ascii удаляет все символы, отличные от Ascii, после нормализации акцента, а blackfriday заставляет идентификаторы работать так же, как с Blackfriday, движком Markdown по умолчанию до Hugo 0,60. Обратите внимание: если Goldmark является Вашим механизмом Markdown по умолчанию, эта же стратегия используется в функции шаблона anchorize.

Blackfriday

Blackfriday был механизмом рендеринга Markdown по умолчанию для Hugo, теперь замененным на Goldmark. Но Вы все равно можете использовать его: просто установите для defaultMarkdownHandler значение blackfriday в конфигурации разметки верхнего уровня markup.

Это конфигурация по умолчанию:

config.

markup:
  blackFriday:
    angledQuotes: false
    extensions: null
    extensionsMask: null
    footnoteAnchorPrefix: ""
    footnoteReturnLinkContents: ""
    fractions: true
    hrefTargetBlank: false
    latexDashes: true
    nofollowLinks: false
    noreferrerLinks: false
    plainIDAnchors: true
    skipHTML: false
    smartDashes: true
    smartypants: true
    smartypantsQuotesNBSP: false
    taskLists: true

[markup]
  [markup.blackFriday]
    angledQuotes = false
    footnoteAnchorPrefix = ""
    footnoteReturnLinkContents = ""
    fractions = true
    hrefTargetBlank = false
    latexDashes = true
    nofollowLinks = false
    noreferrerLinks = false
    plainIDAnchors = true
    skipHTML = false
    smartDashes = true
    smartypants = true
    smartypantsQuotesNBSP = false
    taskLists = true

{
   "markup": {
      "blackFriday": {
         "angledQuotes": false,
         "extensions": null,
         "extensionsMask": null,
         "footnoteAnchorPrefix": "",
         "footnoteReturnLinkContents": "",
         "fractions": true,
         "hrefTargetBlank": false,
         "latexDashes": true,
         "nofollowLinks": false,
         "noreferrerLinks": false,
         "plainIDAnchors": true,
         "skipHTML": false,
         "smartDashes": true,
         "smartypants": true,
         "smartypantsQuotesNBSP": false,
         "taskLists": true
      }
   }
}

Highlight

Это конфигурация подсветки highlight по умолчанию. Обратите внимание, что некоторые из этих настроек могут быть установлены для каждого блока кода, смотрите подсветку синтаксиса.

config.

markup:
  highlight:
    anchorLineNos: false
    codeFences: true
    guessSyntax: false
    hl_Lines: ""
    lineAnchors: ""
    lineNoStart: 1
    lineNos: false
    lineNumbersInTable: true
    noClasses: true
    style: monokai
    tabWidth: 4

[markup]
  [markup.highlight]
    anchorLineNos = false
    codeFences = true
    guessSyntax = false
    hl_Lines = ""
    lineAnchors = ""
    lineNoStart = 1
    lineNos = false
    lineNumbersInTable = true
    noClasses = true
    style = "monokai"
    tabWidth = 4

{
   "markup": {
      "highlight": {
         "anchorLineNos": false,
         "codeFences": true,
         "guessSyntax": false,
         "hl_Lines": "",
         "lineAnchors": "",
         "lineNoStart": 1,
         "lineNos": false,
         "lineNumbersInTable": true,
         "noClasses": true,
         "style": "monokai",
         "tabWidth": 4
      }
   }
}

Для стилей style, смотрите эти галереи:

Для CSS смотрите создание CSS-выделения синтаксиса.

Содержание

config.

markup:
  tableOfContents:
    endLevel: 3
    ordered: false
    startLevel: 2

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

{
   "markup": {
      "tableOfContents": {
         "endLevel": 3,
         "ordered": false,
         "startLevel": 2
      }
   }
}

Эти настройки работают только для средства визуализации Goldmark:

startLevel: Уровень заголовка, значения начинаются с 1 (h1), чтобы начать рендеринг оглавления.
endLevel: Уровень заголовка включительно для остановки отображения оглавления.
ordered: Следует ли создавать упорядоченный список вместо неупорядоченного списка.

Хуки рендеринга разметки

Обратите внимание, что это поддерживается только средством визуализации Goldmark.

Хуки рендеринга позволяют настраиваемым шаблонам переопределять функциональность рендеринга уценки. Вы можете сделать это, создав шаблоны с базовыми именами render-{feature} в layouts/_default/_markup.

Вы также можете создать хуки для конкретного типа/раздела в layouts/[type/section]/_markup, например: layouts/blog/_markup.

В настоящее время поддерживаются следующие функции:

При необходимости вы можете определить специальные шаблоны Формат вывода и язык. Ваша папка layout может выглядеть так:

layouts
└── _default
    └── _markup
        ├── render-image.html
        ├── render-image.rss.xml
        └── render-link.html

Некоторые варианты использования для вышеуказанного:

Разрешение ссылки на ссылки с помощью .GetPage. Это сделало бы ссылки переносимыми, поскольку вы могли бы перевести ./my-post.md (и аналогичные конструкции, которые будут работать на GitHub) в /blog/2019/01/01/my-post/ и т.д.
Добавление target=_blank к внешним ссылкам.
Решение и обработка изображения.
Добавление ссылок заголовка.

Шаблоны хуков рендеринга

Шаблоны render-link и render-image получат этот контекст:

Page: Отображаемая Страница.
Destination: URL-адрес.
Title: Атрибут title.
Text: Отображаемый текст ссылки (HTML).
PlainText: Простой вариант вышеперечисленного.

Шаблон render-heading получит этот контекст:

Page: Отображаемая Страница.
Level: Уровень заголовка (1–6).
Anchor: Автоматически сгенерированный html-идентификатор, уникальный для заголовка на странице.
Text: Отображаемый текст (HTML).
PlainText: Простой вариант вышеперечисленного.

Ссылка с заголовком примера разметки

[Text](https://www.gohugo.io "Title")

Вот пример кода, как может выглядеть шаблон render-link.html:

layouts/_default/_markup/render-link.html


<a href="{{ .Destination | safeURL }}"{{ with .Title}} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>

Пример разметки изображения

![Text](https://d33wubrfki0l68.cloudfront.net/c38c7334cc3f23585738e40334284fddcaf03d5e/2e17c/images/hugo-logo-wide.svg "Title")

Вот пример кода, как может выглядеть шаблон render-image.html:

layouts/_default/_markup/render-image.html


<p class="md__image">
  <img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title}} title="{{ . }}"{{ end }} />
</p>

Пример ссылки заголовка

Учитывая этот файл шаблона

layouts/_default/_markup/render-heading.html


<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} <a href="#{{ .Anchor | safeURL }}">¶</a></h{{ .Level }}>

и эта разметка

### Секция А

Визуализированный html будет

<h3 id="section-a">Секция А <a href="#section-a">¶</a></h3>

Конфигурация разметки