From d7222bd360e76d692660b4efb2c6a379f9b55a52 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Sat, 3 Feb 2024 20:38:59 -0800 Subject: [PATCH] More updates for v0.123.00 --- content/en/content-management/diagrams.md | 4 +- content/en/content-management/front-matter.md | 40 +++- .../content-management/markdown-attributes.md | 115 ++++++++++ content/en/content-management/mathematics.md | 4 +- .../content-management/syntax-highlighting.md | 4 +- content/en/functions/go-template/return.md | 2 +- .../getting-started/configuration-markup.md | 211 +++++++++++------- content/en/render-hooks/images.md | 6 +- content/en/render-hooks/links.md | 6 +- 9 files changed, 295 insertions(+), 97 deletions(-) create mode 100644 content/en/content-management/markdown-attributes.md diff --git a/content/en/content-management/diagrams.md b/content/en/content-management/diagrams.md index 7477fa2e31c..2951dd8b2d6 100644 --- a/content/en/content-management/diagrams.md +++ b/content/en/content-management/diagrams.md @@ -6,8 +6,8 @@ keywords: [diagrams,drawing] menu: docs: parent: content-management - weight: 245 -weight: 245 + weight: 260 +weight: 260 toc: true --- {{< new-in 0.93.0 >}} diff --git a/content/en/content-management/front-matter.md b/content/en/content-management/front-matter.md index e1242a24bb7..a8c18be1efe 100644 --- a/content/en/content-management/front-matter.md +++ b/content/en/content-management/front-matter.md @@ -36,8 +36,7 @@ date = 2024-02-02T04:14:54-08:00 draft = false weight = 10 [params] -myparam = 42 -tags = ['red','blue'] +author = 'John Smith' {{< /code-toggle >}} Front matter fields may be [scalar], [arrays], or [maps] containing [boolean], [integer], [float], or [string] values. Note that the TOML format also supports date/time values using unquoted strings. @@ -262,7 +261,7 @@ path ## Parameters -Specify custom page parameters, including taxonomy terms, under the `params` key in front matter: +Specify custom page parameters under the `params` key in front matter: {{< code-toggle file=content/example.md fm=true >}} title = 'Example' @@ -270,8 +269,7 @@ date = 2024-02-02T04:14:54-08:00 draft = false weight = 10 [params] -myparam = 42 -tags = ['red','blue'] +author = 'John Smith' {{< /code-toggle >}} Access these values from a template using the [`Params`] or [`Param`] method on a `Page` object. @@ -279,6 +277,34 @@ Access these values from a template using the [`Params`] or [`Param`] method on [`param`]: /methods/page/param/ [`params`]: /methods/page/params/ +## Taxonomies + +Classify content by adding taxonomy terms to front matter. For example, with this site configuration: + +{{< code-toggle file=hugo >}} +[taxonomies] +tag = 'tags' +genre = 'genres' +{{< /code-toggle >}} + +Add taxonomy terms as shown below: + +{{< code file=content/example.md >}} +title = 'Example' +date = 2024-02-02T04:14:54-08:00 +draft = false +weight = 10 +tags = ['red','blue'] +genres = ['mystery','romance'] +[params] +author = 'John Smith' +{{< /code >}} + +Access taxonomy terms from a template using the [`Params`] or [`GetTerms`] method on a `Page` object: + +[`Params`]: /methods/page/params/ +[`GetTerms`]: /methods/page/getterms/ + ## Cascade Any [node] can pass down to its descendants a set of front matter values. @@ -356,7 +382,9 @@ If your [content format] is [Emacs Org Mode], you may provide front matter using #+TITLE: Example #+DATE: 2024-02-02T04:14:54-08:00 #+DRAFT: false -#+MYPARAM: 42 +#+AUTHOR: John Smith +#+GENRES: mystery +#+GENRES: romance #+TAGS: red #+TAGS: blue #+WEIGHT: 10 diff --git a/content/en/content-management/markdown-attributes.md b/content/en/content-management/markdown-attributes.md new file mode 100644 index 00000000000..29649cede09 --- /dev/null +++ b/content/en/content-management/markdown-attributes.md @@ -0,0 +1,115 @@ +--- +title: Markdown attributes +description: Use mardown attributes to add HTML attributes when rendering markdown to HTML. +categories: [content management] +keywords: [goldmark,markdown] +menu: + docs: + parent: content-management + weight: 240 +weight: 240 +toc: true +--- + +## Overview + +Hugo supports markdown attributes on images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables. + +For example: + +```text +This is a paragraph. +{class="foo bar" id="baz"} +``` + +With `class` and `id` you can use shorthand notation: + +```text +This is a paragraph. +{.foo .bar #baz} +``` + +Hugo renders both of these to: + +```html +

This is a paragraph.

+``` + +## Block elements + +Update your site configuration to enable markdown attributes for block-level elements. + +{{< code-toggle file=hugo >}} +[markup.goldmark.parser.attribute] +title = true # default is true +block = true # default is false +{{< /code-toggle >}} + + +## Standalone images + +By default, when the [Goldmark] markdown renderer encounters a standalone image element (no other elements or text on the same line), it wraps the image element within a paragraph element per the [CommonMark specification]. + +[CommonMark specification]: https://spec.commonmark.org/current/ +[Goldmark]: https://github.com/yuin/goldmark + +If you were to place an attribute list beneath an image element, Hugo would apply the attributes to the surrounding paragraph, not the image. + +To apply attributes to a standalone image element, you must disable the default wrapping behavior: + +{{< code-toggle file=hugo >}} +[markup.goldmark.parser] +wrapStandAloneImageWithinParagraph = false # default is true +{{< /code-toggle >}} + +## Usage + +You may add [global HTML attributes], or HTML attributes specific to the current element type. Consistent with its content security model, Hugo removes HTML event attributes such as `onclick` and `onmouseover`. + +[global HTML attributes]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes + +The attribute list consists of one or more key/value pairs, separated by spaces or commas, wrapped by braces. You must quote string values that contain spaces. Unlike HTML, boolean attributes must have both key and value. + +For example: + +```text +> This is a blockquote. +{class="foo bar" hidden=hidden} +``` + +Hugo renders this to: + +```html + +``` + +In most cases, place the attribute list beneath the markup element. For headings and fenced code blocks, place the attribute list on the right. + +Element|Position of attribute list +:--|:-- +blockquote | bottom +fenced code block | right +heading | right +horizontal rule | bottom +image | bottom +list | bottom +paragraph | bottom +table | bottom + +For example: + +````text +## Section 1 {class=foo} + +```bash {class=foo linenos=inline} +declare a=1 +echo "${a}" +``` + +This is a paragraph. +{class=foo} +```` + +As shown above, the attribute list for fenced code blocks is not limited to HTML attributes. You can also configure syntax highlighting by passing one or more of [these options](/functions/transform/highlight/#options). diff --git a/content/en/content-management/mathematics.md b/content/en/content-management/mathematics.md index 69552763a81..740f34926ae 100644 --- a/content/en/content-management/mathematics.md +++ b/content/en/content-management/mathematics.md @@ -7,8 +7,8 @@ keywords: [chemical,chemistry,latex,math,mathjax,tex,typesetting] menu: docs: parent: content-management - weight: 250 -weight: 250 + weight: 270 +weight: 270 toc: true math: true --- diff --git a/content/en/content-management/syntax-highlighting.md b/content/en/content-management/syntax-highlighting.md index 62071cd465e..d61afa289fb 100644 --- a/content/en/content-management/syntax-highlighting.md +++ b/content/en/content-management/syntax-highlighting.md @@ -6,8 +6,8 @@ keywords: [highlighting,chroma,code blocks,syntax] menu: docs: parent: content-management - weight: 240 -weight: 240 + weight: 250 +weight: 250 toc: true aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/] --- diff --git a/content/en/functions/go-template/return.md b/content/en/functions/go-template/return.md index 2a166c718d7..e09522a5883 100644 --- a/content/en/functions/go-template/return.md +++ b/content/en/functions/go-template/return.md @@ -80,7 +80,7 @@ See additional examples in the [partial templates] section. ## Usage {{% note %}} -Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks +Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. {{% /note %}} A partial that returns a value must contain only one `return` statement, placed at the end of the template. diff --git a/content/en/getting-started/configuration-markup.md b/content/en/getting-started/configuration-markup.md index 9bc1d4ed63a..4b8655e3972 100644 --- a/content/en/getting-started/configuration-markup.md +++ b/content/en/getting-started/configuration-markup.md @@ -2,7 +2,7 @@ title: Configure markup description: Configure rendering of markup to HTML. categories: [getting started,fundamentals] -keywords: [configuration,highlighting] +keywords: [markup,markdown,goldmark,asciidoc,asciidoctor,highlighting] menu: docs: parent: getting-started @@ -14,7 +14,7 @@ toc: true ## Default handler -By default, Hugo uses [Goldmark] to render markdown to HTML. +Hugo uses [Goldmark] to render markdown to HTML. {{< code-toggle file=hugo >}} [markup] @@ -58,6 +58,11 @@ This is the default configuration for the Goldmark markdown renderer: ### Goldmark extensions +The extensions below, excluding passthrough, are enabled by default. + +Enable the passthrough extension if you include mathematical equations and expressions in your markdown using LaTeX or TeX typesetting syntax. See [mathematics in markdown] for details. + +[mathematics in markdown]: content-management/mathematics/ Extension|Documentation :--|:-- @@ -81,16 +86,7 @@ typographer|[Goldmark Extensions: Typographer] [PHP Markdown Extra: Definition lists]: https://michelf.ca/projects/php-markdown/extra/#def-list [PHP Markdown Extra: Footnotes]: https://michelf.ca/projects/php-markdown/extra/#footnotes -### Goldmark settings - -hardWraps -: By default, Goldmark ignores newlines within a paragraph. Set to `true` to render newlines as `
` elements. - -unsafe -: By default, Goldmark does not render raw HTML and potentially dangerous links. If you have lots of inline HTML and/or JavaScript, you may need to turn this on. - -typographer -: The typographer extension replaces certain character combinations with HTML entities as specified below: +The typographer extension replaces certain character combinations with HTML entities as specified below: Markdown|Replaced by|Description :--|:--|:-- @@ -105,44 +101,78 @@ Markdown|Replaced by|Description `”`|`”`|right double quote `’`|`’`|right single quote -attribute -: Enable custom attribute support for titles and blocks by adding attribute lists inside single curly brackets (`{.myclass class="class1 class2" }`) and placing it _after the Markdown element it decorates_, on the same line for titles and on a new line directly below for blocks. +### Goldmark settings explained -Hugo supports adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc. +Most of the Goldmark settings above are self-explanatory, but some require explanation. -A blockquote with a CSS class: +###### duplicateResourceFiles -```md -> foo -> bar -{.myclass} -``` +(`bool`) If `true`, page resources on multilingual, single-host sites will be duplicated for each language. Default is `false`. -There are some current limitations: For tables you can currently only apply it to the full table, and for lists the `ul`/`ol`-nodes only, e.g.: - -```md -* Fruit - * Apple - * Orange - * Banana - {.fruits} -* Dairy - * Milk - * Cheese - {.dairies} -{.list} -``` +{{% note %}} +With multilingual, single-host sites, setting this parameter to `false` will enable Hugo's [embedded link render hook] and [embedded image render hook]. This is the default configuration for multilingual, single-host sites. -Note that attributes in [code fences](/content-management/syntax-highlighting/#highlighting-in-code-fences) must come after the opening tag, with any other highlighting processing instruction, e.g.: +[embedded image render hook]: /render-hooks/images/#default +[embedded link render hook]: /render-hooks/links/#default +{{% /note %}} -````txt -```go {.myclass linenos=table,hl_lines=[8,"15-17"],linenostart=199} -// ... code -``` -```` +###### parser.wrapStandAloneImageWithinParagraph + +(`bool`) If `true`, image elements without adjacent content will be wrapped within a `p` element when rendered. This is the default markdown behavior. Set to `false` when using an [image render hook] to render standalone images as `figure` elements. Default is `true`. + +[image render hook]: /render-hooks/images/ + +###### parser.autoHeadingIDType + +(`string`) The strategy used to automatically generate heading `id` attributes, one of `github`, `github-ascii` or `blackfriday`. + +- `github` produces GitHub-compatible `id` attributes +- `github-ascii` drops any non-ASCII characters after accent normalization +- `blackfriday` produces `id` attributes compatible with the Blackfriday markdown renderer + +This is also the strategy used by the [anchorize](/functions/urls/anchorize) template function. Default is `github`. + +###### parser.attribute.block + +(`bool`) If `true`, enables [markdown attributes] for block elements. Default is `false`. + +[markdown attributes]: /content-management/markdown-attributes/ + +###### parser.attribute.title + +(`bool`) If `true`, enables [markdown attributes] for headings. Default is `false`. + +###### renderHooks.image.enableDefault + +(`bool`) If `true`, enables Hugo's [embedded image render hook]. Default is `false`. + +[embedded image render hook]: /render-hooks/images/#default + +{{% note %}} +The embedded image render hook is automatically enabled for multilingual, single-host sites provided that [page resource duplication] across languages is disabled. This is the default configuration for multilingual, single-host sites. + +[page resource duplication]: #duplicateresourcefiles +{{% /note %}} + +###### renderHooks.link.enableDefault + +(`bool`) If `true`, enables Hugo's [embedded link render hook]. Default is `false`. + +[embedded link render hook]: /render-hooks/links/#default -autoHeadingIDType ("github") -: The strategy used for creating auto IDs (anchor names). Available types are `github`, `github-ascii` and `blackfriday`. `github` produces GitHub-compatible IDs, `github-ascii` will drop any non-ASCII characters after accent normalization, and `blackfriday` will make the IDs compatible with Blackfriday, the default Markdown engine before Hugo 0.60. Note that if Goldmark is your default Markdown engine, this is also the strategy used in the [anchorize](/functions/urls/anchorize) template func. +{{% note %}} +The embedded link render hook is automatically enabled for multilingual, single-host sites provided that [page resource duplication] across languages is disabled. This is the default configuration for multilingual, single-host sites. + +[page resource duplication]: #duplicateresourcefiles +{{% /note %}} + +###### renderer.hardWraps + +(`bool`) If `true`, Goldmark replaces newline characters within a paragraph with `br` elements. Default is `false`. + +###### renderer.unsafe + +(`bool`) If `true`, Goldmark renders raw HTML mixed within the markdown. This is unsafe unless the content is under your control. Default is `false`. ## Asciidoc @@ -150,59 +180,77 @@ This is the default configuration for the AsciiDoc markdown renderer: {{< code-toggle config=markup.asciidocExt />}} -attributes -: (`map`) Variables to be referenced in your AsciiDoc file. This is a list of variable name/value maps. See Asciidoctor’s [attributes]. +### Asciidoc settings explained + +###### attributes + +(`map`) A map of key/value pairs, each a document attributes,See Asciidoctor’s [attributes]. [attributes]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions -backend: -: (`string`) Don’t change this unless you know what you are doing. +###### backend -extensions -: (`[]string`) Possible extensions are `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, and `asciidoctor-question`. +(`string`) The backend output file format. Default is `html5`. -failureLevel -: (`string`) The minimum logging level that triggers a non-zero exit code (failure). +###### extensions -noHeaderOrFooter -: (`bool`) Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Don’t change this unless you know what you are doing. +(`string array`) An array of enabled extensions, one or more of `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, or `asciidoctor-question`. -preserveTOC -: (`bool`) By default, Hugo removes the table of contents generated by Asciidoctor and provides it through the built-in variable `.TableOfContents` to enable further customization and better integration with the various Hugo themes. This option can be set to true to preserve Asciidoctor’s TOC in the generated page. +{{% note %}} +To mitigate security risks, entries in the extension array may not contain forward slashes (`/`), backslashes (`\`), or periods. Due to this restriction, extensions must be in Ruby's `$LOAD_PATH`. +{{% /note %}} -safeMode -: (`string`) Safe mode level `unsafe`, `safe`, `server`, or `secure`. Don’t change this unless you know what you are doing. +###### failureLevel -sectionNumbers -: (`bool`) Auto-number section titles. +(`string`) The minimum logging level that triggers a non-zero exit code (failure). Default is `fatal`. -trace -: (`bool`) Include backtrace information on errors. +###### noHeaderOrFooter -verbose -: (`bool`) Verbosely print processing information and configuration file checks to stderr. +(`bool`) If `true`, outputs an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Default is `true`. -workingFolderCurrent -: (`bool`) Sets the working directory to be the same as that of the AsciiDoc file being processed, so that [include] will work with relative paths. This setting uses the asciidoctor cli parameter --base-dir and attribute outdir=. For rendering diagrams with [asciidoctor-diagram], `workingFolderCurrent` must be set to `true`. +###### preserveTOC -[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/ -[include]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files +(`bool`) If `true`, preserves the table of contents (TOC) rendered by Asciidoctor. By default, to make the TOC compatible with existing themes, Hugo removes the TOC rendered by Asciidoctor. To render the TOC, use the [`TableOfContents`] method on a `Page` object in your templates. Default is `false`. + +[`TableOfContents`]: /methods/page/tableofcontents/ + +###### safeMode + +(`string`) The safe mode level, one of `unsafe`, `safe`, `server`, or `secure`. Default is `unsafe`. + +###### sectionNumbers -Notice that for security concerns only extensions that do not have path separators (either `\`, `/` or `.`) are allowed. That means that extensions can only be invoked if they are in the Ruby's `$LOAD_PATH` (ie. most likely, the extension has been installed by the user). Any extension declared relative to the website's path will not be accepted. +(`bool`) If `true`, numbers each section title. Default is `false`. -Example of how to set extensions and attributes: +###### trace -```yml +(`bool`) If `true`, include backtrace information on errors. Default is `false`. + +###### verbose + +(`bool`)If `true`, verbosely prints processing information and configuration file checks to stderr. Default is `false`. + +###### workingFolderCurrent + +(`bool`) If `true`, sets the working directory to be the same as that of the AsciiDoc file being processed, allowing [includes] to work with relative paths. Set to `true` to render diagrams with the [asciidoctor-diagram] extension. Default is `false`. + +[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/ +[includes]: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#includes + +### AsciiDoc configuration example + +{{< code-toggle file=hugo >}} [markup.asciidocExt] extensions = ["asciidoctor-html5s", "asciidoctor-diagram"] workingFolderCurrent = true [markup.asciidocExt.attributes] my-base-url = "https://example.com/" my-attribute-name = "my value" -``` +{{< /code-toggle >}} + +### AsciiDoc troubleshooting -In a complex Asciidoctor environment it is sometimes helpful to debug the exact call to your external helper with all -parameters. Run Hugo with `-v`. You will get an output like +Run `hugo --logLevel debug` to examine Hugo's call to the Asciidoctor executable: ```txt 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 -] ... @@ -223,15 +271,18 @@ For CSS, see [Generate Syntax Highlighter CSS](/content-management/syntax-highli ## Table of contents +This is the default configuration for the table of contents, applicable to Goldmark and Asciidoctor: + {{< code-toggle config=markup.tableOfContents />}} -These settings only works for the Goldmark renderer: +###### startLevel + +(`int`) Heading levels less than this value will be excluded from the table of contents. For example, to exclude `h1` elements from the table of contents, set this value to `2`. Default is `2`. + +###### endLevel -startLevel -: The heading level, values starting at 1 (`h1`), to start render the table of contents. +(`int`) Heading levels greater than this value will be excluded from the table of contents. For example, to exclude `h4`, `h5`, and `h6` elements from the table of contents, set this value to `3`. Default is `3`. -endLevel -: The heading level, inclusive, to stop render the table of contents. +###### ordered -ordered -: If `true`, generates an ordered list instead of an unordered list. +(`bool`) If `true`, generates an ordered list instead of an unordered list. Default is `false`. diff --git a/content/en/render-hooks/images.md b/content/en/render-hooks/images.md index 33c4dcfd419..a6fd3917d53 100755 --- a/content/en/render-hooks/images.md +++ b/content/en/render-hooks/images.md @@ -121,14 +121,16 @@ Hugo includes an [embedded image render hook] to resolve markdown image destinat [embedded image render hook]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/_markup/render-image.html {{< code-toggle file=hugo >}} -[markup.goldmark.renderhooks.image] +[markup.goldmark.renderHooks.image] enableDefault = true {{< /code-toggle >}} A custom render hook, even when provided by a theme or module, will override the embedded render hook regardless of the configuration setting above. {{% note %}} -The embedded image render hook is automatically enabled for multilingual, single-host sites provided that page resource duplication across languages is disabled. This is the default configuration for multilingual, single-host sites. +The embedded image render hook is automatically enabled for multilingual, single-host sites provided that [page resource duplication] across languages is disabled. This is the default configuration for multilingual, single-host sites. + +[page resource duplication]: /getting-started/configuration-markup/#duplicateresourcefiles {{% /note %}} The embedded image render hook resolves internal markdown destinations by looking for a matching [page resource], falling back to a matching [global resource]. Remote destinations are passed through, and the render hook will not throw an error or warning if it is unable to resolve a destination. diff --git a/content/en/render-hooks/links.md b/content/en/render-hooks/links.md index 941aff78541..8ce4a6d5e7a 100755 --- a/content/en/render-hooks/links.md +++ b/content/en/render-hooks/links.md @@ -93,14 +93,16 @@ Hugo includes an [embedded link render hook] to resolve markdown link destinatio [embedded link render hook]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/_markup/render-link.html {{< code-toggle file=hugo >}} -[markup.goldmark.renderhooks.link] +[markup.goldmark.renderHooks.link] enableDefault = true {{< /code-toggle >}} A custom render hook, even when provided by a theme or module, will override the embedded render hook regardless of the configuration setting above. {{% note %}} -The embedded link render hook is automatically enabled for multilingual, single-host sites provided that page resource duplication across languages is disabled. This is the default configuration for multilingual, single-host sites. +The embedded link render hook is automatically enabled for multilingual, single-host sites provided that [page resource duplication] across languages is disabled. This is the default configuration for multilingual, single-host sites. + +[page resource duplication]: /getting-started/configuration-markup/#duplicateresourcefiles {{% /note %}} The embedded link render hook resolves internal markdown destinations by looking for a matching page, falling back to a matching [page resource], then falling back to a matching [global resource]. Remote destinations are passed through, and the render hook will not throw an error or warning if it is unable to resolve a destination.