mirror of
https://github.com/gohugoio/hugoDocs.git
synced 2025-08-05 13:39:12 -04:00
Joe Mooring
Bjørn Erik Pedersen
parent
f9b5938dde
commit
c60cd20a87
@ -15,7 +15,7 @@ features:
|
||||
- heading: Shortcodes
|
||||
image_path: /images/icon-shortcodes.svg
|
||||
tagline: Hugo's shortcodes are Markdown's hidden superpower.
|
||||
copy: We love the beautiful simplicity of markdown’s syntax, but there are times when we want more flexibility. Hugo shortcodes allow for both beauty and flexibility.
|
||||
copy: We love the beautiful simplicity of Markdown’s syntax, but there are times when we want more flexibility. Hugo shortcodes allow for both beauty and flexibility.
|
||||
|
||||
- heading: Built-in Templates
|
||||
image_path: /images/icon-built-in-templates.svg
|
||||
|
||||
@ -7,7 +7,7 @@ cascade:
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
||||
@ -15,7 +15,7 @@ aliases: [/content/archetypes/]
|
||||
|
||||
## Overview
|
||||
|
||||
A content file consists of [front matter] and markup. The markup is typically markdown, but Hugo also supports other [content formats]. Front matter can be TOML, YAML, or JSON.
|
||||
A content file consists of [front matter] and markup. The markup is typically Markdown, but Hugo also supports other [content formats]. Front matter can be TOML, YAML, or JSON.
|
||||
|
||||
The `hugo new content` command creates a new file in the `content` directory, using an archetype as a template. This is the default archetype:
|
||||
|
||||
|
||||
@ -60,7 +60,7 @@ index.md can be reference either by its path or by its containing folder without
|
||||
{{</* ref "/products/index" */>}} // <- References /products/index.md
|
||||
```
|
||||
|
||||
To generate a hyperlink using `ref` or `relref` in markdown:
|
||||
To generate a hyperlink using `ref` or `relref` in Markdown:
|
||||
|
||||
```text
|
||||
[About]({{</* ref "/about" */>}} "About Us")
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Diagrams
|
||||
description: Use fenced code blocks and markdown render hooks to display diagrams.
|
||||
description: Use fenced code blocks and Markdown render hooks to display diagrams.
|
||||
categories: [content management]
|
||||
keywords: [diagrams,drawing]
|
||||
menu:
|
||||
|
||||
@ -24,7 +24,7 @@ The current list of content formats in Hugo:
|
||||
|
||||
| Name | Markup identifiers | Comment |
|
||||
| ------------- | ------------- |-------------|
|
||||
| Goldmark | `markdown`, `goldmark` |Note that you can set the default handler of `md` and `markdown` to something else, see [Configure Markup](/getting-started/configuration-markup/).|
|
||||
| Goldmark | `markdown`, `goldmark` |Note that you can set the default handler of `md` and `Markdown` to something else, see [Configure Markup](/getting-started/configuration-markup/).|
|
||||
|Emacs Org-Mode|`org`|See [go-org](https://github.com/niklasfasching/go-org).|
|
||||
|AsciiDoc|`asciidocext`, `adoc`, `ad`|Needs [Asciidoctor][ascii] installed.|
|
||||
|RST|`rst`|Needs [RST](https://docutils.sourceforge.io/rst.html) installed.|
|
||||
@ -63,7 +63,7 @@ Some Asciidoctor parameters can be customized in Hugo. See [details].
|
||||
|
||||
[details]: /getting-started/configuration-markup/#asciidoc
|
||||
|
||||
## Learn markdown
|
||||
## Learn Markdown
|
||||
|
||||
Markdown syntax is simple enough to learn in a single sitting. The following are excellent resources to get you up and running:
|
||||
|
||||
@ -75,8 +75,8 @@ Markdown syntax is simple enough to learn in a single sitting. The following are
|
||||
[ascii]: https://asciidoctor.org/
|
||||
[config]: /getting-started/configuration/
|
||||
[developer tools]: /tools/
|
||||
[fireball]: https://daringfireball.net/projects/markdown/
|
||||
[gfmtasks]: https://guides.github.com/features/mastering-markdown/#syntax
|
||||
[fireball]: https://daringfireball.net/projects/Markdown/
|
||||
[gfmtasks]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#syntax
|
||||
[helperssource]: https://github.com/gohugoio/hugo/blob/77c60a3440806067109347d04eb5368b65ea0fe8/helpers/general.go#L65
|
||||
[hl]: /content-management/syntax-highlighting/
|
||||
[hlsc]: /content-management/shortcodes/#highlight
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Markdown attributes
|
||||
description: Use mardown attributes to add HTML attributes when rendering markdown to HTML.
|
||||
description: Use mardown attributes to add HTML attributes when rendering Markdown to HTML.
|
||||
categories: [content management]
|
||||
keywords: [goldmark,markdown]
|
||||
menu:
|
||||
@ -13,7 +13,7 @@ toc: true
|
||||
|
||||
## Overview
|
||||
|
||||
Hugo supports markdown attributes on images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
|
||||
Hugo supports Markdown attributes on images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
|
||||
|
||||
For example:
|
||||
|
||||
@ -37,7 +37,7 @@ Hugo renders both of these to:
|
||||
|
||||
## Block elements
|
||||
|
||||
Update your site configuration to enable markdown attributes for block-level elements.
|
||||
Update your site configuration to enable Markdown attributes for block-level elements.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.parser.attribute]
|
||||
@ -48,7 +48,7 @@ block = true # default is false
|
||||
|
||||
## 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].
|
||||
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
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Mathematics in markdown
|
||||
title: Mathematics in Markdown
|
||||
linkTitle: Mathematics
|
||||
description: Include mathematical equations and expressions in your markdown using LaTeX or TeX typesetting syntax.
|
||||
description: Include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax.
|
||||
categories: [content management]
|
||||
keywords: [chemical,chemistry,latex,math,mathjax,tex,typesetting]
|
||||
menu:
|
||||
@ -45,11 +45,11 @@ The approach described below avoids reliance on platform-specific features like
|
||||
|
||||
## Setup
|
||||
|
||||
Follow these instructions to include mathematical equations and expressions in your markdown using LaTeX or TeX typesetting syntax.
|
||||
Follow these instructions to include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax.
|
||||
|
||||
###### Step 1
|
||||
|
||||
Enable and configure the Goldmark [passthrough extension] in your site configuration. The passthrough extension preserves raw markdown within delimited snippets of text, including the delimiters themselves.
|
||||
Enable and configure the Goldmark [passthrough extension] in your site configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves.
|
||||
|
||||
{{< code-toggle file=hugo copy=true >}}
|
||||
[markup.goldmark.extensions.passthrough]
|
||||
@ -122,7 +122,7 @@ The example above loads the partial template if you have set the `math` paramete
|
||||
|
||||
###### Step 4
|
||||
|
||||
Include mathematical equations and expressions in your markdown using LaTeX or TeX typesetting syntax.
|
||||
Include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax.
|
||||
|
||||
{{< code file=content/math-examples.md copy=true >}}
|
||||
This is an inline \(a^*=x-b^*\) equation.
|
||||
|
||||
@ -144,7 +144,7 @@ A _Branch Bundle_ is any directory at any hierarchy within the
|
||||
This `_index.md` can also be directly under the `content/` directory.
|
||||
|
||||
{{% note %}}
|
||||
Here `md` (markdown) is used just as an example. You can use any file
|
||||
Here `md` (Markdown) is used just as an example. You can use any file
|
||||
type as a content resource as long as it is a content type recognized by Hugo.
|
||||
{{% /note %}}
|
||||
|
||||
|
||||
@ -210,7 +210,7 @@ the `Name` and `Title` will be assigned to the resource files as follows:
|
||||
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.
|
||||
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 %}}
|
||||
@ -289,9 +289,9 @@ public/
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
|
||||
|
||||
@ -54,11 +54,11 @@ You can pass multiple lines as parameters to a shortcode by using raw string lit
|
||||
and a new line with a "quoted string".` */>}}
|
||||
```
|
||||
|
||||
### Shortcodes with markdown
|
||||
### Shortcodes with Markdown
|
||||
|
||||
Shortcodes using the `%` as the outer-most delimiter will be fully rendered when sent to the content renderer. This means that the rendered output from a shortcode can be part of the page's table of contents, footnotes, etc.
|
||||
|
||||
### Shortcodes without markdown
|
||||
### Shortcodes without Markdown
|
||||
|
||||
The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without Markdown include internal HTML:
|
||||
|
||||
|
||||
@ -307,7 +307,7 @@ Hugo provides two mutually exclusive configuration options to alter URLs _after_
|
||||
#### Canonical URLs
|
||||
|
||||
{{% note %}}
|
||||
This is a legacy configuration option, superseded by template functions and markdown render hooks, and will likely be [removed in a future release].
|
||||
This is a legacy configuration option, superseded by template functions and Markdown render hooks, and will likely be [removed in a future release].
|
||||
|
||||
[removed in a future release]: https://github.com/gohugoio/hugo/issues/4733
|
||||
{{% /note %}}
|
||||
|
||||
@ -7,7 +7,7 @@ cascade:
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
||||
@ -34,7 +34,7 @@ Hugo natively supports [GoAT](https://github.com/bep/goat) diagrams with an [emb
|
||||
|
||||
[embedded code block render hook]: {{% eturl render-codeblock-goat %}}
|
||||
|
||||
This markdown:
|
||||
This Markdown:
|
||||
|
||||
````
|
||||
```goat
|
||||
@ -83,7 +83,7 @@ By way of example, let's create a code block render hook to render GoAT diagrams
|
||||
</figure>
|
||||
{{< /code >}}
|
||||
|
||||
This markdown:
|
||||
This Markdown:
|
||||
|
||||
{{< code file=content/example.md lang=text >}}
|
||||
```goat {class="foo" caption="Diagram 1: Example"}
|
||||
|
||||
@ -7,7 +7,7 @@ cascade:
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
||||
@ -7,7 +7,7 @@ cascade:
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
||||
@ -7,7 +7,7 @@ cascade:
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
||||
@ -6,7 +6,7 @@ _build:
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
||||
@ -30,7 +30,7 @@ By default, `findRESubmatch` finds all matches. You can limit the number of matc
|
||||
|
||||
## Practical example
|
||||
|
||||
This markdown:
|
||||
This Markdown:
|
||||
|
||||
```text
|
||||
- [Example](https://example.org)
|
||||
|
||||
@ -32,7 +32,7 @@ To remove leading and trailing newline characters and carriage returns:
|
||||
|
||||
The `strings.Trim` function is commonly used in shortcodes to remove leading and trailing newlines characters and carriage returns from the content within the opening and closing shortcode tags.
|
||||
|
||||
For example, with this markdown:
|
||||
For example, with this Markdown:
|
||||
|
||||
```text
|
||||
{{</* my-shortcode */>}}
|
||||
|
||||
@ -7,7 +7,7 @@ cascade:
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: transform.Markdownify
|
||||
description: Renders markdown to HTML.
|
||||
description: Renders Markdown to HTML.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
@ -24,8 +24,8 @@ To keep the wrapping `p` tags for a single paragraph, use the [`RenderString`] m
|
||||
[`RenderString`]: /methods/page/renderstring/
|
||||
|
||||
{{% note %}}
|
||||
Although the `markdownify` function honors [markdown render hooks] when rendering markdown to HTML, use the `RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details.
|
||||
Although the `markdownify` function honors [Markdown render hooks] when rendering Markdown to HTML, use the `RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details.
|
||||
|
||||
[markdown render hooks]: /render-hooks/
|
||||
[Markdown render hooks]: /render-hooks/
|
||||
[#9692]: https://github.com/gohugoio/hugo/issues/9692
|
||||
{{% /note %}}
|
||||
|
||||
@ -16,14 +16,14 @@ aliases: [/functions/anchorize]
|
||||
|
||||
## Sanitizing logic
|
||||
|
||||
With the default markdown renderer, Goldmark, the sanitizing logic is controlled by your site configuration:
|
||||
With the default Markdown renderer, Goldmark, the sanitizing logic is controlled by your site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.parser]
|
||||
autoHeadingIDType = 'github'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
This controls the behavior of the `anchorize` function and the generation of heading IDs when rendering markdown to HTML.
|
||||
This controls the behavior of the `anchorize` function and the generation of heading IDs when rendering Markdown to HTML.
|
||||
|
||||
Set `autoHeadingIDType` to one of:
|
||||
|
||||
|
||||
@ -7,7 +7,7 @@ cascade:
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
||||
@ -14,16 +14,16 @@ toc: true
|
||||
|
||||
## Default handler
|
||||
|
||||
Hugo uses [Goldmark] to render markdown to HTML.
|
||||
Hugo uses [Goldmark] to render Markdown to HTML.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup]
|
||||
defaultMarkdownHandler = 'goldmark'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Files with the `.md` or `.markdown` extension are processed as markdown, provided that you have not specified a different [content format] using the `markup` field in front matter.
|
||||
Files with the `.md` or `.markdown` extension are processed as Markdown, provided that you have not specified a different [content format] using the `markup` field in front matter.
|
||||
|
||||
To use a different renderer for markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your site configuration.
|
||||
To use a different renderer for Markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your site configuration.
|
||||
|
||||
defaultMarkdownHandler|Description
|
||||
:--|:--
|
||||
@ -36,7 +36,7 @@ defaultMarkdownHandler|Description
|
||||
To use Asciidoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy].
|
||||
|
||||
{{% note %}}
|
||||
Unless you need a unique capability provided by one of the alternate markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the [CommonMark] specification, and is compatible with [GitHub Flavored Markdown] (GFM).
|
||||
Unless you need a unique capability provided by one of the alternate Markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the [CommonMark] specification, and is compatible with [GitHub Flavored Markdown] (GFM).
|
||||
|
||||
[commonmark]: https://spec.commonmark.org/0.30/
|
||||
[github flavored markdown]: https://github.github.com/gfm/
|
||||
@ -52,7 +52,7 @@ Unless you need a unique capability provided by one of the alternate markdown ha
|
||||
|
||||
## Goldmark
|
||||
|
||||
This is the default configuration for the Goldmark markdown renderer:
|
||||
This is the default configuration for the Goldmark Markdown renderer:
|
||||
|
||||
{{< code-toggle config=markup.goldmark />}}
|
||||
|
||||
@ -60,9 +60,9 @@ This is the default configuration for the Goldmark markdown renderer:
|
||||
|
||||
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.
|
||||
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/
|
||||
[mathematics in Markdown]: content-management/mathematics/
|
||||
|
||||
Extension|Documentation
|
||||
:--|:--
|
||||
@ -122,7 +122,7 @@ With multilingual single-host sites, setting this parameter to `false` will enab
|
||||
|
||||
###### 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`.
|
||||
(`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/
|
||||
|
||||
@ -132,19 +132,19 @@ With multilingual single-host sites, setting this parameter to `false` will enab
|
||||
|
||||
- `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
|
||||
- `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`.
|
||||
(`bool`) If `true`, enables [Markdown attributes] for block elements. Default is `false`.
|
||||
|
||||
[markdown attributes]: /content-management/markdown-attributes/
|
||||
[Markdown attributes]: /content-management/markdown-attributes/
|
||||
|
||||
###### parser.attribute.title
|
||||
|
||||
(`bool`) If `true`, enables [markdown attributes] for headings. Default is `true`.
|
||||
(`bool`) If `true`, enables [Markdown attributes] for headings. Default is `true`.
|
||||
|
||||
###### renderHooks.image.enableDefault
|
||||
|
||||
@ -180,11 +180,11 @@ The embedded link render hook is automatically enabled for multilingual single-h
|
||||
|
||||
###### 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`.
|
||||
(`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
|
||||
|
||||
This is the default configuration for the AsciiDoc markdown renderer:
|
||||
This is the default configuration for the AsciiDoc Markdown renderer:
|
||||
|
||||
{{< code-toggle config=markup.asciidocExt />}}
|
||||
|
||||
|
||||
@ -88,7 +88,7 @@ config
|
||||
: The `config` directory contains your site configuration, possibly split into multiple subdirectories and files. For projects with minimal configuration or projects that do not need to behave differently in different environments, a single configuration file named `hugo.toml` in the root of the project is sufficient. See [details](/getting-started/configuration/#configuration-directory).
|
||||
|
||||
content
|
||||
: The `content` directory contains the markup files (typically markdown) and page resources that comprise the content of your site. See [details](/content-management/organization/).
|
||||
: The `content` directory contains the markup files (typically Markdown) and page resources that comprise the content of your site. See [details](/content-management/organization/).
|
||||
|
||||
data
|
||||
: The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/templates/data-templates/).
|
||||
|
||||
@ -86,7 +86,7 @@ An [array](#array), [slice](#slice), or [map](#map).
|
||||
|
||||
###### content format
|
||||
|
||||
A markup language for creating content. Typically markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText. See [details](/content-management/formats/).
|
||||
A markup language for creating content. Typically Markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText. See [details](/content-management/formats/).
|
||||
|
||||
###### content type
|
||||
|
||||
@ -206,9 +206,9 @@ Adaptation of a site to meet language and regional requirements. This includes t
|
||||
|
||||
An unordered group of elements, each indexed by a unique key. See the [Go documentation](https://go.dev/ref/spec#Map_types) for details.
|
||||
|
||||
###### markdown attribute
|
||||
###### Markdown attribute
|
||||
|
||||
A list of attributes, containing one or more key/value pairs, separated by spaces or commas, and wrapped by braces. Apply markdown attributes to images and block-level elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables. See [details](/getting-started/configuration-markup/#goldmark).
|
||||
A list of attributes, containing one or more key/value pairs, separated by spaces or commas, and wrapped by braces. Apply Markdown attributes to images and block-level elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables. See [details](/getting-started/configuration-markup/#goldmark).
|
||||
|
||||
###### marshal
|
||||
|
||||
@ -309,7 +309,7 @@ The host-relative URL of a published resource or a rendered page.
|
||||
|
||||
###### render hook
|
||||
|
||||
A [template](#template) that overrides standard markdown rendering. See [details](/render-hooks).
|
||||
A [template](#template) that overrides standard Markdown rendering. See [details](/render-hooks).
|
||||
|
||||
###### remote resource
|
||||
|
||||
@ -343,7 +343,7 @@ Content with the "section" [page kind](#page-kind). Typically a listing of [regu
|
||||
|
||||
###### shortcode
|
||||
|
||||
A [template](#template) called from within markdown, taking zero or more [arguments](#argument). See [details](/content-management/shortcodes/).
|
||||
A [template](#template) called from within Markdown, taking zero or more [arguments](#argument). See [details](/content-management/shortcodes/).
|
||||
|
||||
###### slice
|
||||
|
||||
|
||||
@ -125,7 +125,7 @@ draft = true
|
||||
|
||||
Notice the `draft` value in the [front matter] is `true`. By default, Hugo does not publish draft content when you build the site. Learn more about [draft, future, and expired content].
|
||||
|
||||
Add some [markdown] to the body of the post, but do not change the `draft` value.
|
||||
Add some [Markdown] to the body of the post, but do not change the `draft` value.
|
||||
|
||||
[markdown]: https://commonmark.org/help/
|
||||
|
||||
@ -154,7 +154,7 @@ View your site at the URL displayed in your terminal. Keep the development serve
|
||||
When satisfied with your new content, set the front matter `draft` parameter to `false`.
|
||||
|
||||
{{% note %}}
|
||||
Hugo's rendering engine conforms to the CommonMark [specification] for markdown. The CommonMark organization provides a useful [live testing tool] powered by the reference implementation.
|
||||
Hugo's rendering engine conforms to the CommonMark [specification] for Markdown. The CommonMark organization provides a useful [live testing tool] powered by the reference implementation.
|
||||
|
||||
[live testing tool]: https://spec.commonmark.org/dingus/
|
||||
[specification]: https://spec.commonmark.org/
|
||||
|
||||
@ -7,7 +7,7 @@ cascade:
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
||||
@ -7,7 +7,7 @@ cascade:
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
||||
@ -7,7 +7,7 @@ cascade:
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
||||
@ -13,7 +13,7 @@ action:
|
||||
signatures: [PAGE.Content]
|
||||
---
|
||||
|
||||
The `Content` method on a `Page` object renders markdown and shortcodes to HTML. The content does not include front matter.
|
||||
The `Content` method on a `Page` object renders Markdown and shortcodes to HTML. The content does not include front matter.
|
||||
|
||||
[shortcodes]: /getting-started/glossary/#shortcode
|
||||
|
||||
|
||||
@ -21,7 +21,7 @@ In a URL, whether absolute or relative, the [fragment] links to an `id` attribut
|
||||
path fragment
|
||||
```
|
||||
|
||||
Hugo assigns an `id` attribute to each markdown [ATX] and [setext] heading within the page content. You can override the `id` with a [markdown attribute] as needed. This creates the relationship between an entry in the [table of contents] (TOC) and a heading on the page.
|
||||
Hugo assigns an `id` attribute to each Markdown [ATX] and [setext] heading within the page content. You can override the `id` with a [Markdown attribute] as needed. This creates the relationship between an entry in the [table of contents] (TOC) and a heading on the page.
|
||||
|
||||
Use the `Fragments` method on a `Page` object to create a table of contents with the `Fragments.ToHTML` method, or by [walking] the `Fragments.Map` data structure.
|
||||
|
||||
|
||||
@ -13,7 +13,7 @@ action:
|
||||
signatures: [PAGE.Plain]
|
||||
---
|
||||
|
||||
The `Plain` method on a `Page` object renders markdown and [shortcodes] to HTML, then strips the HTML [tags]. It does not strip HTML [entities]. The plain content does not include front matter.
|
||||
The `Plain` method on a `Page` object renders Markdown and [shortcodes] to HTML, then strips the HTML [tags]. It does not strip HTML [entities]. The plain content does not include front matter.
|
||||
|
||||
To prevent Go's [html/template] package from escaping HTML entities, pass the result through the [`htmlUnescape`] function.
|
||||
|
||||
|
||||
@ -26,7 +26,7 @@ For example:
|
||||
{{ $p.RenderShortcodes }}
|
||||
{{< /code >}}
|
||||
|
||||
Then in your markdown:
|
||||
Then in your Markdown:
|
||||
|
||||
{{< code file=content/about.md lang=md >}}
|
||||
{{%/* include "/snippets/services.md" */%}}
|
||||
@ -34,14 +34,14 @@ Then in your markdown:
|
||||
{{%/* include "/snippets/leadership.md" */%}}
|
||||
{{< /code >}}
|
||||
|
||||
Each of the included markdown files can contain calls to other shortcodes.
|
||||
Each of the included Markdown files can contain calls to other shortcodes.
|
||||
|
||||
## Shortcode notation
|
||||
|
||||
In the example above it's important to understand the difference between the two delimiters used when calling a shortcode:
|
||||
|
||||
- `{{</* myshortcode */>}}` tells Hugo that the rendered shortcode does not need further processing. For example, the shortcode content is HTML.
|
||||
- `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing. For example, the shortcode content is markdown.
|
||||
- `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing. For example, the shortcode content is Markdown.
|
||||
|
||||
Use the latter for the "include" shortcode described above.
|
||||
|
||||
@ -75,4 +75,4 @@ https://example.org/privacy/
|
||||
An *emphasized* word.
|
||||
```
|
||||
|
||||
Note that the shortcode within the content file was rendered, but the surrounding markdown was preserved.
|
||||
Note that the shortcode within the content file was rendered, but the surrounding Markdown was preserved.
|
||||
|
||||
@ -25,7 +25,7 @@ To create a locally scoped scratch pad that is not attached to a `Page` object,
|
||||
|
||||
## Determinate values
|
||||
|
||||
The `Scratch` method is often used to set "scratch pad" values within a shortcode, a partial template called by a shortcode, or by a markdown render hook. In all three cases, the "scratch pad" values are not determinate until Hugo renders the page content.
|
||||
The `Scratch` method is often used to set "scratch pad" values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the "scratch pad" values are not determinate until Hugo renders the page content.
|
||||
|
||||
If you need to access a "scratch pad" value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a noop variable:
|
||||
|
||||
|
||||
@ -106,7 +106,7 @@ Removes the given key.
|
||||
|
||||
## Determinate values
|
||||
|
||||
The `Store` method is often used to set "scratch pad" values within a shortcode, a partial template called by a shortcode, or by a markdown render hook. In all three cases, the "scratch pad" values are not determinate until Hugo renders the page content.
|
||||
The `Store` method is often used to set "scratch pad" values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the "scratch pad" values are not determinate until Hugo renders the page content.
|
||||
|
||||
If you need to access a "scratch pad" value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a noop variable:
|
||||
|
||||
|
||||
@ -14,7 +14,7 @@ action:
|
||||
There are three ways to define the [content summary]:
|
||||
|
||||
1. Let Hugo create the summary based on the first 70 words. You can change the number of words by setting the `summaryLength` in your site configuration.
|
||||
2. Manually split the content with a `<--more-->` tag in markdown. Everything before the tag is included in the summary.
|
||||
2. Manually split the content with a `<--more-->` tag in Markdown. Everything before the tag is included in the summary.
|
||||
3. Create a `summary` field in front matter.
|
||||
|
||||
To list the pages in a section with a summary beneath each link:
|
||||
|
||||
@ -10,7 +10,7 @@ action:
|
||||
signatures: [PAGE.TableOfContents]
|
||||
---
|
||||
|
||||
The `TableOfContents` method on a `Page` object returns an ordered or unordered list of the markdown [ATX] and [setext] headings within the page content.
|
||||
The `TableOfContents` method on a `Page` object returns an ordered or unordered list of the Markdown [ATX] and [setext] headings within the page content.
|
||||
|
||||
[atx]: https://spec.commonmark.org/0.30/#atx-headings
|
||||
[setext]: https://spec.commonmark.org/0.30/#setext-headings
|
||||
|
||||
@ -13,7 +13,7 @@ action:
|
||||
There are three ways to define the [content summary]:
|
||||
|
||||
1. Let Hugo create the summary based on the first 70 words. You can change the number of words by setting the `summaryLength` in your site configuration.
|
||||
2. Manually split the content with a `<--more-->` tag in markdown. Everything before the tag is included in the summary.
|
||||
2. Manually split the content with a `<--more-->` tag in Markdown. Everything before the tag is included in the summary.
|
||||
3. Create a `summary` field in front matter.
|
||||
|
||||
{{% note %}}
|
||||
|
||||
@ -7,7 +7,7 @@ cascade:
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
||||
@ -7,7 +7,7 @@ cascade:
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
||||
@ -7,7 +7,7 @@ cascade:
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
||||
@ -12,7 +12,7 @@ action:
|
||||
toc: true
|
||||
---
|
||||
|
||||
Specify the parameter by position or by name. When calling a shortcode within markdown, use either positional or named parameters, but not both.
|
||||
Specify the parameter by position or by name. When calling a shortcode within Markdown, use either positional or named parameters, but not both.
|
||||
|
||||
{{% note %}}
|
||||
Some shortcodes support positional parameters, some support named parameters, and others support both. Refer to the shortcode's documentation for usage details.
|
||||
|
||||
@ -46,13 +46,13 @@ Is rendered to:
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the markdown. Use the [`trim`] function as shown above to remove both carriage returns and newlines.
|
||||
Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the Markdown. Use the [`trim`] function as shown above to remove both carriage returns and newlines.
|
||||
|
||||
[`trim`]: /functions/strings/trim/
|
||||
{{% /note %}}
|
||||
|
||||
{{% note %}}
|
||||
In the example above, the value returned by `Inner` is markdown, but it was rendered as plain text. Use either of the following approaches to render markdown to HTML.
|
||||
In the example above, the value returned by `Inner` is Markdown, but it was rendered as plain text. Use either of the following approaches to render Markdown to HTML.
|
||||
{{% /note %}}
|
||||
|
||||
|
||||
@ -99,9 +99,9 @@ We design the **best** widgets in the world.
|
||||
{{%/* /card */%}}
|
||||
{{< /code >}}
|
||||
|
||||
When you use the `{{%/* */%}}` notation, Hugo renders the entire shortcode as markdown, requiring the following changes.
|
||||
When you use the `{{%/* */%}}` notation, Hugo renders the entire shortcode as Markdown, requiring the following changes.
|
||||
|
||||
First, configure the renderer to allow raw HTML within markdown:
|
||||
First, configure the renderer to allow raw HTML within Markdown:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.renderer]
|
||||
@ -110,7 +110,7 @@ unsafe = true
|
||||
|
||||
This configuration is not unsafe if _you_ control the content. Read more about Hugo's [security model].
|
||||
|
||||
Second, because we are rendering the entire shortcode as markdown, we must adhere to the rules governing [indentation] and inclusion of [raw HTML blocks] as provided in the [CommonMark] specification.
|
||||
Second, because we are rendering the entire shortcode as Markdown, we must adhere to the rules governing [indentation] and inclusion of [raw HTML blocks] as provided in the [CommonMark] specification.
|
||||
|
||||
{{< code file=layouts/shortcodes/card.html >}}
|
||||
<div class="card">
|
||||
|
||||
@ -14,7 +14,7 @@ Similar to the [`Inner`] method, `InnerDeindent` returns the content between ope
|
||||
|
||||
This allows us to effectively bypass the rules governing [indentation] as provided in the [CommonMark] specification.
|
||||
|
||||
Consider this markdown, an unordered list with a small gallery of thumbnail images within each list item:
|
||||
Consider this Markdown, an unordered list with a small gallery of thumbnail images within each list item:
|
||||
|
||||
{{< code file=content/about.md lang=md >}}
|
||||
- Gallery one
|
||||
@ -42,7 +42,7 @@ With this shortcode, calling `Inner` instead of `InnerDeindent`:
|
||||
</div>
|
||||
{{< /code >}}
|
||||
|
||||
Hugo renders the markdown to:
|
||||
Hugo renders the Markdown to:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
@ -73,7 +73,7 @@ Although technically correct per the CommonMark specification, this is not what
|
||||
</div>
|
||||
{{< /code >}}
|
||||
|
||||
Hugo renders the markdown to:
|
||||
Hugo renders the Markdown to:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
|
||||
@ -7,7 +7,7 @@ cascade:
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Emojis
|
||||
description: Include emoji shortcodes in your markdown or templates.
|
||||
description: Include emoji shortcodes in your Markdown or templates.
|
||||
categories: [quick reference]
|
||||
keywords: [emoji]
|
||||
menu:
|
||||
@ -11,13 +11,13 @@ weight: 20
|
||||
toc: true
|
||||
---
|
||||
|
||||
Configure Hugo to enable emoji processing in markdown:
|
||||
Configure Hugo to enable emoji processing in Markdown:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
enableEmoji = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
With emoji processing enabled, this markdown:
|
||||
With emoji processing enabled, this Markdown:
|
||||
|
||||
```md
|
||||
Hello! :wave:
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Render hooks
|
||||
linkTitle: Overview
|
||||
description: Create render hooks to override the rendering of markdown to HTML.
|
||||
description: Create render hooks to override the rendering of Markdown to HTML.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
@ -14,4 +14,4 @@ showSectionMenu: false
|
||||
aliases: [/templates/render-hooks/]
|
||||
---
|
||||
|
||||
Create render hooks to override the rendering of markdown to HTML.
|
||||
Create render hooks to override the rendering of Markdown to HTML.
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Code block render hooks
|
||||
linkTitle: Code blocks
|
||||
description: Create a code block render hook to override the rendering of markdown code blocks to HTML.
|
||||
description: Create a code block render hook to override the rendering of Markdown code blocks to HTML.
|
||||
categories: [render hooks]
|
||||
keywords: []
|
||||
menu:
|
||||
@ -14,7 +14,7 @@ toc: true
|
||||
|
||||
## Markdown
|
||||
|
||||
This markdown example contains a fenced code block:
|
||||
This Markdown example contains a fenced code block:
|
||||
|
||||
{{< code file=content/example.md lang=text >}}
|
||||
```bash {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2}
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Heading render hooks
|
||||
linkTitle: Headings
|
||||
description: Create a heading render hook to override the rendering of markdown headings to HTML.
|
||||
description: Create a heading render hook to override the rendering of Markdown headings to HTML.
|
||||
categories: [render hooks]
|
||||
keywords: []
|
||||
menu:
|
||||
@ -24,7 +24,7 @@ Heading render hook templates receive the following [context]:
|
||||
|
||||
###### Attributes
|
||||
|
||||
(`map`) The markdown attributes, available if you configure your site as follows:
|
||||
(`map`) The Markdown attributes, available if you configure your site as follows:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.parser.attribute]
|
||||
@ -49,7 +49,7 @@ title = true
|
||||
|
||||
## Examples
|
||||
|
||||
In its default configuration, Hugo renders markdown headings according to the [CommonMark specification] with the addition of automatic `id` attributes. To create a render hook that does the same thing:
|
||||
In its default configuration, Hugo renders Markdown headings according to the [CommonMark specification] with the addition of automatic `id` attributes. To create a render hook that does the same thing:
|
||||
|
||||
[CommonMark specification]: https://spec.commonmark.org/current/
|
||||
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Image render hooks
|
||||
linkTitle: Images
|
||||
description: Create an image render to hook override the rendering of markdown images to HTML.
|
||||
description: Create an image render to hook override the rendering of Markdown images to HTML.
|
||||
categories: [render hooks]
|
||||
keywords: []
|
||||
menu:
|
||||
@ -14,7 +14,7 @@ toc: true
|
||||
|
||||
## Markdown
|
||||
|
||||
A markdown image has three components: the image description, the image destination, and optionally the image title.
|
||||
A Markdown image has three components: the image description, the image destination, and optionally the image title.
|
||||
|
||||
```text
|
||||
|
||||
@ -32,7 +32,7 @@ Image render hook templates receive the following context:
|
||||
|
||||
###### Attributes
|
||||
|
||||
(`map`) The markdown attributes, available if you configure your site as follows:
|
||||
(`map`) The Markdown attributes, available if you configure your site as follows:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.parser]
|
||||
@ -75,7 +75,7 @@ block = true
|
||||
With inline elements such as images and links, remove leading and trailing white space using the `{{‑ ‑}}` delimiter notation to prevent white space between adjacent inline elements and text.
|
||||
{{% /note %}}
|
||||
|
||||
In its default configuration, Hugo renders markdown images according to the [CommonMark specification]. To create a render hook that does the same thing:
|
||||
In its default configuration, Hugo renders Markdown images according to the [CommonMark specification]. To create a render hook that does the same thing:
|
||||
|
||||
[CommonMark specification]: https://spec.commonmark.org/current/
|
||||
|
||||
@ -116,7 +116,7 @@ wrapStandAloneImageWithinParagraph = false
|
||||
|
||||
{{< 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:
|
||||
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]: {{% eturl render-image %}}
|
||||
|
||||
@ -133,7 +133,7 @@ The embedded image render hook is automatically enabled for multilingual single-
|
||||
[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.
|
||||
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.
|
||||
|
||||
[page resource]: /getting-started/glossary/#page-resource
|
||||
[global resource]: /getting-started/glossary/#global-resource
|
||||
@ -150,4 +150,4 @@ source = 'static'
|
||||
target = 'assets'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Note that the embedded image render hook does not perform image processing. Its sole purpose is to resolve markdown image destinations.
|
||||
Note that the embedded image render hook does not perform image processing. Its sole purpose is to resolve Markdown image destinations.
|
||||
|
||||
@ -11,7 +11,7 @@ menu:
|
||||
weight: 20
|
||||
---
|
||||
|
||||
When rendering markdown to HTML, render hooks override the conversion. Each render hook is a template, with one template for each supported element type:
|
||||
When rendering Markdown to HTML, render hooks override the conversion. Each render hook is a template, with one template for each supported element type:
|
||||
|
||||
- [Code blocks](/render-hooks/code-blocks)
|
||||
- [Headings](/render-hooks/headings)
|
||||
@ -19,14 +19,14 @@ When rendering markdown to HTML, render hooks override the conversion. Each rend
|
||||
- [Links](/render-hooks/links)
|
||||
|
||||
{{% note %}}
|
||||
Hugo supports multiple [content formats] including markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, and reStructuredText.
|
||||
Hugo supports multiple [content formats] including Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, and reStructuredText.
|
||||
|
||||
The render hook capability is limited to markdown. You cannot create render hooks for the other content formats.
|
||||
The render hook capability is limited to Markdown. You cannot create render hooks for the other content formats.
|
||||
|
||||
[content formats]: /content-management/formats/
|
||||
{{% /note %}}
|
||||
|
||||
For example, consider this markdown:
|
||||
For example, consider this Markdown:
|
||||
|
||||
```text
|
||||
[Hugo](https://gohugo.io)
|
||||
@ -41,7 +41,7 @@ Without link or image render hooks, this example above is rendered to:
|
||||
<p><img alt="kitten" src="kitten.jpg"></p>
|
||||
```
|
||||
|
||||
By creating link and image render hooks, you can alter the conversion from markdown to HTML. For example:
|
||||
By creating link and image render hooks, you can alter the conversion from Markdown to HTML. For example:
|
||||
|
||||
```html
|
||||
<p><a href="https://gohugo.io" rel="external">Hugo</a></p>
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Link render hooks
|
||||
linkTitle: Links
|
||||
description: Create a link render hook to override the rendering of markdown links to HTML.
|
||||
description: Create a link render hook to override the rendering of Markdown links to HTML.
|
||||
categories: [render hooks]
|
||||
keywords: []
|
||||
menu:
|
||||
@ -14,7 +14,7 @@ toc: true
|
||||
|
||||
## Markdown
|
||||
|
||||
A markdown link has three components: the link text, the link destination, and optionally the link title.
|
||||
A Markdown link has three components: the link text, the link destination, and optionally the link title.
|
||||
|
||||
```text
|
||||
[Post 1](/posts/post-1 "My first post")
|
||||
@ -58,7 +58,7 @@ Link render hook templates receive the following context:
|
||||
With inline elements such as images and links, remove leading and trailing white space using the `{{‑ ‑}}` delimiter notation to prevent white space between adjacent inline elements and text.
|
||||
{{% /note %}}
|
||||
|
||||
In its default configuration, Hugo renders markdown links according to the [CommonMark specification]. To create a render hook that does the same thing:
|
||||
In its default configuration, Hugo renders Markdown links according to the [CommonMark specification]. To create a render hook that does the same thing:
|
||||
|
||||
[CommonMark specification]: https://spec.commonmark.org/current/
|
||||
|
||||
@ -88,7 +88,7 @@ To include a `rel` attribute set to `external` for external links:
|
||||
|
||||
{{< 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:
|
||||
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]: {{% eturl render-link %}}
|
||||
|
||||
@ -105,7 +105,7 @@ The embedded link render hook is automatically enabled for multilingual single-h
|
||||
[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.
|
||||
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.
|
||||
|
||||
[page resource]: /getting-started/glossary/#page-resource
|
||||
[global resource]: /getting-started/glossary/#global-resource
|
||||
|
||||
@ -26,5 +26,5 @@ Below is an overview of what we used with Hugo to build our website:
|
||||
* Our search is powered by a custom solution that we’ve built. It allows our pages, blog, and knowledge base to be searched. It uses [Axios](https://github.com/axios/axios) to send a `POST` request containing the search query. An index file in JSON generated by Hugo is searched and the results are then returned.
|
||||
* Our commenting system is also powered by a custom solution that we’ve built. It uses Axios to send a `GET` request containing the slug to pull the comment thread and a `POST` request containing the name, email address, and comment when submitting a comment.
|
||||
* Our contact form is a simple HTML form, which uses Axios as well.
|
||||
* Our writers use shortcodes to enhance the capability of markdown.
|
||||
* Our writers use shortcodes to enhance the capability of Markdown.
|
||||
* Our entire website is delivered through KeyCDN using a Pull Zone, which means all of our edge locations are delivering our website.
|
||||
|
||||
@ -24,6 +24,6 @@ With the launch of our Employee Communications app Quiply we created a very simp
|
||||
|
||||
As our customer base and demand for marketing and communication started to grow, we needed a solution to easily grow and extend the contents of our web presence. As we do not have the need to serve dynamic content, we decided to use a static site generator. Amongst a couple of others, we tried Hugo and it became immediately clear that we'd use Hugo going forward as it compiles super-fast, is intuitive to use and offers all the features we need.
|
||||
|
||||
Our website which we launched a couple of weeks ago is still growing and new content is being added constantly. By using Hugo, this can be easily done by content authors writing markdown files without always having to touch HTML or CSS code. It is available in German only for the time being, an English version is in the works.
|
||||
Our website which we launched a couple of weeks ago is still growing and new content is being added constantly. By using Hugo, this can be easily done by content authors writing Markdown files without always having to touch HTML or CSS code. It is available in German only for the time being, an English version is in the works.
|
||||
|
||||
Huge thanks to everyone involved in making Hugo a success.
|
||||
|
||||
@ -93,7 +93,7 @@ You can now access this `_index.md`'s' content in your list template:
|
||||
<header>
|
||||
<h1>{{ .Title }}</h1>
|
||||
</header>
|
||||
<!-- "{{ .Content }}" pulls from the markdown content of the corresponding _index.md -->
|
||||
<!-- "{{ .Content }}" pulls from the Markdown content of the corresponding _index.md -->
|
||||
{{ .Content }}
|
||||
</article>
|
||||
<ul>
|
||||
|
||||
@ -18,6 +18,6 @@ And for all the other small things around Hugo:
|
||||
- [hugo-openapispec-shortcode](https://github.com/tenfourty/hugo-openapispec-shortcode) A shortcode that allows you to include [Open API Spec](https://openapis.org) (formerly known as Swagger Spec) in a page.
|
||||
- [HugoPhotoSwipe](https://github.com/GjjvdBurg/HugoPhotoSwipe) makes it easy to create image galleries using PhotoSwipe.
|
||||
- [Hugo SFTP Upload](https://github.com/thomasmey/HugoSftpUpload) Syncs the local build of your Hugo website with your remote web server via SFTP.
|
||||
- [Emacs Easy Hugo](https://github.com/masasam/emacs-easy-hugo) Emacs package for writing blog posts in markdown or org-mode and building your site with Hugo.
|
||||
- [Emacs Easy Hugo](https://github.com/masasam/emacs-easy-hugo) Emacs package for writing blog posts in Markdown or org-mode and building your site with Hugo.
|
||||
- [JAMStack Themes](https://jamstackthemes.dev/ssg/hugo/). JAMStack themes is a collection of site themes filterable by static site generator and supported CMS to help build CMS-connected sites using Hugo (linking to Hugo-specific themes).
|
||||
- [plausible-hugo](https://github.com/divinerites/plausible-hugo). Easy Hugo integration for Plausible Analytics, a simple, open-source, lightweight and privacy-friendly web analytics alternative to Google Analytics.
|
||||
|
||||
@ -32,7 +32,7 @@ A static website with a dynamic search function? Yes, Hugo provides an alternati
|
||||
: This gist demonstrates how to leverage Hugo's existing build time processing to generate a searchable JSON index used by [Fuse.js](https://fusejs.io/) on the client-side. Although this gist uses Fuse.js for fuzzy matching, any client-side search tool capable of reading JSON indexes will work. Does not require npm, grunt, or other build-time tools except Hugo!
|
||||
|
||||
[hugo-search-index](https://www.npmjs.com/package/hugo-search-index)
|
||||
: A library containing Gulp tasks and a prebuilt browser script that implements search. Gulp generates a search index from project markdown files.
|
||||
: A library containing Gulp tasks and a prebuilt browser script that implements search. Gulp generates a search index from project Markdown files.
|
||||
|
||||
[hugofastsearch](https://gist.github.com/cmod/5410eae147e4318164258742dd053993)
|
||||
: A usability and speed update to "GitHub Gist for Fuse.js integration" — global, keyboard-optimized search.
|
||||
|
||||
@ -53,7 +53,7 @@ _Tested with GNU Bash 5.1 and GNU grep 3.7._
|
||||
### Patterns
|
||||
|
||||
`<!-- raw HTML omitted -->`
|
||||
: By default, Hugo strips raw HTML from your markdown prior to rendering, and leaves this HTML comment in its place.
|
||||
: By default, Hugo strips raw HTML from your Markdown prior to rendering, and leaves this HTML comment in its place.
|
||||
|
||||
`ZgotmplZ`
|
||||
: ZgotmplZ is a special value that indicates that unsafe content reached a CSS or URL context at runtime. See [details].
|
||||
|
||||
@ -83,7 +83,7 @@ You are probably invoking the [`Paginate`] or [`Paginator`] method more than onc
|
||||
|
||||
###### Why are there two ways to call a shortcode?
|
||||
|
||||
Use the `{{%/* shortcode */%}}` notation if the shortcode template, or the content between the opening and closing shortcode tags, contains markdown. Otherwise use the\
|
||||
Use the `{{%/* shortcode */%}}` notation if the shortcode template, or the content between the opening and closing shortcode tags, contains Markdown. Otherwise use the\
|
||||
`{{</* shortcode */>}}` notation. See [details](/content-management/shortcodes/).
|
||||
|
||||
###### Can I use environment variables to control configuration?
|
||||
@ -106,7 +106,7 @@ In these cases, instead of monitoring native file system events, use the `--poll
|
||||
|
||||
###### Why is my page Scratch or Store missing a value?
|
||||
|
||||
The [`Scratch`] and [`Store`] methods on a `Page` object allow you to create a "scratch pad" on the given page to store and manipulate data. Values are often set within a shortcode, a partial template called by a shortcode, or by a markdown render hook. In all three cases, the "scratch pad" values are not determinate until Hugo renders the page content.
|
||||
The [`Scratch`] and [`Store`] methods on a `Page` object allow you to create a "scratch pad" on the given page to store and manipulate data. Values are often set within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the "scratch pad" values are not determinate until Hugo renders the page content.
|
||||
|
||||
If you need to access a "scratch pad" value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a noop variable:
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user