diff --git a/content/en/content-management/diagrams.md b/content/en/content-management/diagrams.md index 7477fa2e31..2951dd8b2d 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 e1242a24bb..a5a2d4bb75 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. @@ -194,6 +193,8 @@ path ###### params +{{< new-in 0.123.0 >}} + (`map`) A map of custom [page parameters]. [page parameters]: #parameters @@ -262,7 +263,9 @@ path ## Parameters -Specify custom page parameters, including taxonomy terms, under the `params` key in front matter: +{{< new-in 0.123.0 >}} + +Specify custom page parameters under the `params` key in front matter: {{< code-toggle file=content/example.md fm=true >}} title = 'Example' @@ -270,8 +273,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 +281,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 +386,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 0000000000..29649cede0 --- /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 69552763a8..740f34926a 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/page-resources.md b/content/en/content-management/page-resources.md index f141510bb5..623a9ed2ce 100644 --- a/content/en/content-management/page-resources.md +++ b/content/en/content-management/page-resources.md @@ -10,6 +10,7 @@ menu: weight: 80 toc: true --- + Page resources are only accessible from [page bundles](/content-management/page-bundles), those directories with `index.md` or `_index.md` files at their root. Page resources are only available to the page with which they are bundled. @@ -114,7 +115,7 @@ GetMatch .Resources.Match "*sunset.jpg" 🚫 ``` -## Page resources metadata +## Metadata The page resources' metadata is managed from the corresponding page's front matter with an array/table parameter named `resources`. You can batch assign values using [wildcards](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). @@ -201,3 +202,108 @@ the `Name` and `Title` will be assigned to the resource files as follows: | guide.pdf | `"pdf-file-2.pdf` | `"guide.pdf"` | | other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` | | photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` | + +## Multilingual + +{{< new-in 0.123.0 >}} + +By default, with a multilingual single-host site, Hugo does not duplicate shared page resources when building the site. + +{{% note %}} +This behavior is limited to markdown content. Shared page resources for other [content formats] are copied into each language bundle. + +[content formats]: /content-management/formats/ +{{% /note %}} + +Consider this site configuration: + +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'de' +defaultContentLanguageInSubdir = true + +[languages.de] +languageCode = 'de-DE' +languageName = 'Deutsch' +weight = 1 + +[languages.en] +languageCode = 'en-US' +languageName = 'English' +weight = 2 +{{< /code-toggle >}} + +And this content: + +```text +content/ +└── my-bundle/ + β”œβ”€β”€ a.jpg <-- shared page resource + β”œβ”€β”€ b.jpg <-- shared page resource + β”œβ”€β”€ c.de.jpg + β”œβ”€β”€ c.en.jpg + β”œβ”€β”€ index.de.md + └── index.en.md +``` + +With v0.122.0 and earlier, Hugo duplicated the shared page resources, creating copies for each language: + +```text +public/ +β”œβ”€β”€ de/ +β”‚ β”œβ”€β”€ my-bundle/ +β”‚ β”‚ β”œβ”€β”€ a.jpg <-- shared page resource +β”‚ β”‚ β”œβ”€β”€ b.jpg <-- shared page resource +β”‚ β”‚ β”œβ”€β”€ c.de.jpg +β”‚ β”‚ └── index.html +β”‚ └── index.html +β”œβ”€β”€ en/ +β”‚ β”œβ”€β”€ my-bundle/ +β”‚ β”‚ β”œβ”€β”€ a.jpg <-- shared page resource (duplicate) +β”‚ β”‚ β”œβ”€β”€ b.jpg <-- shared page resource (duplicate) +β”‚ β”‚ β”œβ”€β”€ c.en.jpg +β”‚ β”‚ └── index.html +β”‚ └── index.html +└── index.html + +``` + +With v0.123.0 and later, Hugo places the shared resources in the page bundle for the default content language: + +```text +public/ +β”œβ”€β”€ de/ +β”‚ β”œβ”€β”€ my-bundle/ +β”‚ β”‚ β”œβ”€β”€ a.jpg <-- shared page resource +β”‚ β”‚ β”œβ”€β”€ b.jpg <-- shared page resource +β”‚ β”‚ β”œβ”€β”€ c.de.jpg +β”‚ β”‚ └── index.html +β”‚ └── index.html +β”œβ”€β”€ en/ +β”‚ β”œβ”€β”€ my-bundle/ +β”‚ β”‚ β”œβ”€β”€ c.en.jpg +β”‚ β”‚ └── index.html +β”‚ └── index.html +└── index.html +``` + +This approach reduces build times, storage requirements, bandwidth consumption, and deployment times, ultimately reducing cost. + +{{% note %}} +To resolve markdown link and image destinations to the correct location, you must use link and image render hooks that capture the page resource with the [`Resources.Get`] method, and then invoke its [`RelPermalink`] method. + +By default, with multilingual single-host sites, Hugo enables its [embedded link render hook] and [embedded image render hook] to resolve markdown link and image destinations. + +You may override the embedded render hooks as needed, provided they capture the resource as described above. + +[embedded link render hook]: /render-hooks/links/#default +[embedded image render hook]: /render-hooks/images/#default +[`Resources.Get`]: /methods/page/resources/#get +[`RelPermalink`]: /methods/resource/relpermalink/ +{{% /note %}} + +Although duplicating shared page resources is inefficient, you can enable this feature in your site configuration if desired: + +{{< code-toggle file=hugo >}} +[markup.goldmark] +duplicateResourceFiles = true +{{< /code-toggle >}} diff --git a/content/en/content-management/syntax-highlighting.md b/content/en/content-management/syntax-highlighting.md index 62071cd465..d61afa289f 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 2a166c718d..e09522a588 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 9bc1d4ed63..ff0eace253 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,86 @@ 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} -``` +{{< new-in 0.123.0 >}} -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} -``` +(`bool`) If `true`, shared page resources on multilingual single-host sites will be duplicated for each language. See [multilingual page resources] for details. Default is `false`. -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.: +[multilingual page resources]: /content-management/page-resources/#multilingual -````txt -```go {.myclass linenos=table,hl_lines=[8,"15-17"],linenostart=199} -// ... code -``` -```` +{{% 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. + +[embedded image render hook]: /render-hooks/images/#default +[embedded link render hook]: /render-hooks/links/#default +{{% /note %}} + +###### 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 `true`. + +###### renderHooks.image.enableDefault + +{{< new-in 0.123.0 >}} + +(`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 if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. + +[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles +{{% /note %}} + +###### renderHooks.link.enableDefault + +{{< new-in 0.123.0 >}} -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. +(`bool`) If `true`, enables Hugo's [embedded link render hook]. Default is `false`. + +[embedded link render hook]: /render-hooks/links/#default + +{{% note %}} +The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. + +[duplication of shared page resources]: /getting-started/configuration-markup/#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 +188,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 + +(`string`) The backend output file format. Default is `html5`. + +###### extensions -extensions -: (`[]string`) Possible extensions are `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, and `asciidoctor-question`. +(`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`. -failureLevel -: (`string`) The minimum logging level that triggers a non-zero exit code (failure). +{{% 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 %}} -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. +###### failureLevel -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. +(`string`) The minimum logging level that triggers a non-zero exit code (failure). Default is `fatal`. -safeMode -: (`string`) Safe mode level `unsafe`, `safe`, `server`, or `secure`. Don’t change this unless you know what you are doing. +###### noHeaderOrFooter -sectionNumbers -: (`bool`) Auto-number section titles. +(`bool`) If `true`, outputs an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Default is `true`. -trace -: (`bool`) Include backtrace information on errors. +###### preserveTOC -verbose -: (`bool`) Verbosely print processing information and configuration file checks to stderr. +(`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`. -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`. +[`TableOfContents`]: /methods/page/tableofcontents/ -[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/ -[include]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files +###### safeMode + +(`string`) The safe mode level, one of `unsafe`, `safe`, `server`, or `secure`. Default is `unsafe`. -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. +###### sectionNumbers -Example of how to set extensions and attributes: +(`bool`) If `true`, numbers each section title. Default is `false`. -```yml +###### trace + +(`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 >}} -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 +### AsciiDoc troubleshooting + +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 +279,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/getting-started/usage.md b/content/en/getting-started/usage.md index 268aed2e4f..7879770a3f 100644 --- a/content/en/getting-started/usage.md +++ b/content/en/getting-started/usage.md @@ -65,6 +65,16 @@ Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [ - The `publishDate` is in the future - The `expiryDate` is in the past +{{< new-in 0.123.0 >}} + +{{% note %}} +Hugo publishes descendants of draft, future, and expired [node] pages. To prevent publication of these descendants, use the [`cascade`] front matter field to cascade [build options] to the descendent pages. + +[build options]: /content-management/build-options/ +[`cascade`]: /content-management/front-matter/#cascade-field +[node]: /getting-started/glossary/#node +{{% /note %}} + You can override the default behavior when running `hugo` or `hugo server` with command line flags: ```sh diff --git a/content/en/methods/page/Path.md b/content/en/methods/page/Path.md index 34ac3854f3..e09e771a97 100644 --- a/content/en/methods/page/Path.md +++ b/content/en/methods/page/Path.md @@ -11,6 +11,8 @@ action: signatures: [PAGE.Path] --- +{{< new-in 0.123.0 >}} + The `Path` method on a `Page` object returns the canonical page path of the given page, regardless of whether the page is backed by a file. ```go-html-template diff --git a/content/en/render-hooks/images.md b/content/en/render-hooks/images.md index 33c4dcfd41..183650278a 100755 --- a/content/en/render-hooks/images.md +++ b/content/en/render-hooks/images.md @@ -80,7 +80,7 @@ In its default configuration, Hugo renders markdown images according to the [Com [CommonMark specification]: https://spec.commonmark.org/current/ {{< code file=layouts/_default/_markup/render-image.html copy=true >}} -{{ . }} @@ -92,13 +92,13 @@ To render standalone images within `figure` elements: {{< code file=layouts/_default/_markup/render-image.html copy=true >}} {{- if .IsBlock -}}
- {{ . }}
{{ .Title }}
{{- else -}} - {{ . }} @@ -114,21 +114,23 @@ wrapStandAloneImageWithinParagraph = false ## Default -{{< new-in v0.123.0 >}} +{{< new-in 0.123.0 >}} Hugo includes an [embedded image render hook] to resolve markdown image destinations. Disabled by default, you can enable it in your site configuration: [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 if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. + +[duplication of shared page resources]: /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 941aff7854..6f5b80b719 100755 --- a/content/en/render-hooks/links.md +++ b/content/en/render-hooks/links.md @@ -63,7 +63,7 @@ In its default configuration, Hugo renders markdown links according to the [Comm [CommonMark specification]: https://spec.commonmark.org/current/ {{< code file=layouts/_default/_markup/render-link.html copy=true >}} - {{- with .Text | safeHTML }}{{ . }}{{ end -}} @@ -75,7 +75,7 @@ To include a `rel` attribute set to `external` for external links: {{< code file=layouts/_default/_markup/render-link.html copy=true >}} {{- $u := urls.Parse .Destination -}} - @@ -86,21 +86,23 @@ To include a `rel` attribute set to `external` for external links: ## Default -{{< new-in v0.123.0 >}} +{{< new-in 0.123.0 >}} Hugo includes an [embedded link render hook] to resolve markdown link destinations. Disabled by default, you can enable it in your site configuration: [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 if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. + +[duplication of shared page resources]: /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. diff --git a/layouts/shortcodes/new-in.html b/layouts/shortcodes/new-in.html new file mode 100644 index 0000000000..87fae16123 --- /dev/null +++ b/layouts/shortcodes/new-in.html @@ -0,0 +1,36 @@ +{{- /* +Renders a "new in" button indicating the version in which a feature was added. + +When comparing the current version to the specified version, the "new in" +button will be hidden if any of the following conditions is true: + +- The major version difference exceeds the majorVersionDiffThreshold +- The minor version difference exceeds the minorVersionDiffThreshold + +@param {string} version The semantic version string, with or without a leading v. +@returns {template.HTML} + +@example {{< new-in 0.100.0 >}} +*/}} + +{{- /* Set defaults. */}} +{{- $majorVersionDiffThreshold := 0 }} +{{- $minorVersionDiffThreshold := 30 }} +{{- $displayExpirationWarning := true }} + +{{- /* Render. */}} +{{- with $version := .Get 0 | strings.TrimPrefix "v" }} + {{- $majorVersionDiff := sub (index (split hugo.Version ".") 0 | int) (index (split $version ".") 0 | int) }} + {{- $minorVersionDiff := sub (index (split hugo.Version ".") 1 | int) (index (split $version ".") 1 | int) }} + {{- if or (gt $majorVersionDiff $majorVersionDiffThreshold) (gt $minorVersionDiff $minorVersionDiffThreshold) }} + {{- if $displayExpirationWarning }} + {{- warnf "This call to the %q shortcode should be removed: %s. The button is now hidden because the specified version (%s) is older than the display threshold." $.Name $.Position $version }} + {{- end }} + {{- else }} + + {{- end }} +{{- else }} + {{- errorf "The %q shortcode requires a positional parameter (version). See %s" .Name .Position }} +{{- end -}}