From: Bjørn Erik Pedersen Date: Wed, 4 Sep 2024 16:57:34 +0000 (+0200) Subject: Merge commit '39fd3b557014e339bc6c68a7ff34a7734a735ee0' X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=b570a5f1184fe275ad6fc04b82050ad8fce95651;p=brevno-suite%2Fhugo Merge commit '39fd3b557014e339bc6c68a7ff34a7734a735ee0' --- b570a5f1184fe275ad6fc04b82050ad8fce95651 diff --cc docs/content/en/about/features.md index 835384723,000000000..58d324853 mode 100644,000000..100644 --- a/docs/content/en/about/features.md +++ b/docs/content/en/about/features.md @@@ -1,139 -1,0 +1,139 @@@ +--- +title: Features +description: Hugo's rich and powerful feature set provides the framework and tools to create static sites that build in seconds, often less. +categories: [about] +keywords: [] +menu: + docs: + parent: about + weight: 30 +weight: 30 +toc: true +--- + +## Framework + +[Multiplatform] +: Install Hugo's single executable on Linux, macOS, Windows, and more. + +[Multilingual] +: Localize your project for each language and region, including translations, images, dates, currencies, numbers, percentages, and collation sequence. Hugo's multilingual framework supports single-host and multihost configurations. + +[Output formats] +: Render each page of your site to one or more output formats, with granular control by page kind, section, and path. While HTML is the default output format, you can add JSON, RSS, CSV, and more. For example, create a REST API to access content. + +[Templates] +: Create templates using variables, functions, and methods to transform your content, resources, and data into a published page. While HTML templates are the most common, you can create templates for any output format. + +[Themes] +: Reduce development time and cost by using one of the hundreds of themes contributed by the Hugo community. Themes are available for corporate sites, documentation projects, image portfolios, landing pages, personal and professional blogs, resumes, CVs, and more. + +[Modules] +: Reduce development time and cost by creating or importing packaged combinations of archetypes, assets, content, data, templates, translation tables, static files, or configuration settings. A module may serve as the basis for a new site, or to augment an existing site. + +[Privacy] +: Configure the behavior of Hugo's embedded templates and shortcodes to facilitate compliance with regional privacy regulations, including the [GDPR] and [CCPA]. + +[Security] +: Hugo's security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection. Other protections prevent "shelling out" to arbitrary applications, limit access to specific environment variables, prevent connections to arbitrary remote data sources, and more. + +## Content authoring + +[Content formats] +: Create your content using Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, or reStructuredText. Markdown is the default content format, conforming to the [CommonMark] and [GitHub Flavored Markdown] specifications. + +[Markdown attributes] +: Apply HTML attributes such as `class` and `id` to Markdown images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables. + +[Markdown extensions] +: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more. + +[Markdown render hooks] - : Override the conversion of Markdown to HTML when rendering blockquotes, fenced code blocks, headings, images, and links. For example, render every standalone image as an HTML `figure` element. ++: Override the conversion of Markdown to HTML when rendering blockquotes, fenced code blocks, headings, images, links, and tables. For example, render every standalone image as an HTML `figure` element. + +[Diagrams] +: Use fenced code blocks and Markdown render hooks to include diagrams in your content. + +[Mathematics] +: Include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax. + +[Syntax highlighting] +: Syntactically highlight code examples using Hugo's embedded syntax highlighter, enabled by default for fenced code blocks in Markdown. The syntax highlighter supports hundreds of code languages and dozens of styles. + +[Shortcodes] +: Use Hugo's embedded shortcodes, or create your own, to insert complex content. For example, use shortcodes to include `audio` and `video` elements, render tables from local or remote data sources, insert snippets from other pages, and more. + +## Content management + +[Content adapters] +: Create content adapters to dynamically add content when building your site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML. + +[Taxonomies] +: Classify content to establish simple or complex logical relationships between pages. For example, create an authors taxonomy, and assign one or more authors to each page. Among other uses, the taxonomy system provides an inverted, weighted index to render a list of related pages, ordered by relevance. + +[Data] +: Augment your content using local or remote data sources including CSV, JSON, TOML, YAML, and XML. For example, create a shortcode to render an HTML table from a remote CSV file. + +[Menus] +: Provide rapid access to content via Hugo's menu system, configured automatically, globally, or on a page-by-page basis. The menu system is a key component of Hugo's multilingual architecture. + +[URL management] +: Serve any page from any path via global configuration or on a page-by-page basis. + +## Asset pipelines + +[Image processing] +: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract EXIF data. + +[JavaScript bundling] +: Transpile TypeScript and JSX to JavaScript, bundle, tree shake, minify, create source maps, and perform SRI hashing. + +[Sass processing] +: Transpile Sass to CSS, bundle, tree shake, minify, create source maps, perform SRI hashing, and integrate with PostCSS. + +[Tailwind CSS processing] +: Compile Tailwind CSS utility classes into standard CSS, bundle, tree shake, optimize, minify, perform SRI hashing, and integrate with PostCSS. + +## Performance + +[Caching] +: Reduce build time and cost by rendering a partial template once then cache the result, either globally or within a given context. For example, cache the result of an asset pipeline to prevent reprocessing on every rendered page. + +[Segmentation] +: Reduce build time and cost by partitioning your sites into segments. For example, render the home page and the "news section" every hour, and render the entire site once a week. + +[Minification] +: Minify HTML, CSS, and JavaScript to reduce file size, bandwidth consumption, and loading times. + +[CCPA]: https://en.wikipedia.org/wiki/California_Consumer_Privacy_Act +[Sass processing]: /functions/css/Sass/ +[Caching]: /functions/partials/includecached/ +[CommonMark]: https://spec.commonmark.org/current/ +[Content adapters]: /content-management/content-adapters/ +[Content formats]: /content-management/formats/ +[Data]: /content-management/data-sources/ +[Diagrams]: /content-management/diagrams/ +[GDPR]: https://en.wikipedia.org/wiki/General_Data_Protection_Regulation +[GitHub Flavored Markdown]: https://github.github.com/gfm/ +[Image processing]: /content-management/image-processing/ +[JavaScript bundling]: /functions/js/build/ +[Markdown attributes]: /content-management/markdown-attributes/ +[Markdown extensions]: /getting-started/configuration-markup/#goldmark-extensions +[Markdown render hooks]: /render-hooks/introduction/ +[Mathematics]: /content-management/mathematics/ +[Menus]: /content-management/menus/ +[Minification]: /getting-started/configuration/#configure-minify +[Modules]: https://gohugo.io/hugo-modules/ +[Multilingual]: /content-management/multilingual/ +[Multiplatform]: /installation/ +[Output formats]: /templates/output-formats/ +[Privacy]: /about/privacy/ +[Security]: /about/security/ +[Segmentation]: /getting-started/configuration/#configure-segments +[Shortcodes]: /content-management/shortcodes/ +[Syntax highlighting]: /content-management/syntax-highlighting/ +[Tailwind CSS processing]: /functions/css/tailwindcss/ +[Taxonomies]: /content-management/taxonomies/ +[Templates]: templates/introduction/ +[Themes]: https://themes.gohugo.io/ +[URL management]: /content-management/urls/ diff --cc docs/content/en/content-management/summaries.md index 7b81cf0a0,000000000..e0b2c9590 mode 100644,000000..100644 --- a/docs/content/en/content-management/summaries.md +++ b/docs/content/en/content-management/summaries.md @@@ -1,117 -1,0 +1,117 @@@ +--- +title: Content summaries +linkTitle: Summaries +description: Create and render content summaries. +categories: [content management] +keywords: [summaries,abstracts,read more] +menu: + docs: + parent: content-management + weight: 160 +weight: 160 +toc: true +aliases: [/content/summaries/,/content-management/content-summaries/] +--- + + + + + +You can define a content summary manually, in front matter, or automatically. A manual content summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary. + +Review the [comparison table](#comparison) below to understand the characteristics of each summary type. + +## Manual summary + +Use a `` divider to indicate the end of the content summary. Hugo will not render the summary divider itself. + +{{< code file=content/sample.md >}} ++++ +title: 'Example' +date: 2024-05-26T09:10:33-07:00 ++++ + +Thénardier was not mistaken. The man was sitting there, and letting +Cosette get somewhat rested. + + + +The inn-keeper walked round the brushwood and presented himself +abruptly to the eyes of those whom he was in search of. +{{< /code >}} + +When using the Emacs Org Mode [content format], use a `# more` divider to indicate the end of the content summary. + +[content format]: /content-management/formats/ + +## Front matter summary + +Use front matter to define a summary independent of content. + +{{< code file=content/sample.md >}} ++++ +title: 'Example' +date: 2024-05-26T09:10:33-07:00 +summary: 'Learn more about _Les Misérables_ by Victor Hugo.' ++++ + +Thénardier was not mistaken. The man was sitting there, and letting +Cosette get somewhat rested. The inn-keeper walked round the +brushwood and presented himself abruptly to the eyes of those whom +he was in search of. +{{< /code >}} + +## Automatic summary + +If you have not defined the summary manually or in front matter, Hugo automatically defines the summary based on the [`summaryLength`] in your site configuration. + +[`summaryLength`]: /getting-started/configuration/#summarylength + +{{< code file=content/sample.md >}} ++++ +title: 'Example' +date: 2024-05-26T09:10:33-07:00 ++++ + +Thénardier was not mistaken. The man was sitting there, and letting +Cosette get somewhat rested. The inn-keeper walked round the +brushwood and presented himself abruptly to the eyes of those whom +he was in search of. +{{< /code >}} + +For example, with a `summaryLength` of 10, the automatic summary will be: + +```text +Thénardier was not mistaken. The man was sitting there, and letting +Cosette get somewhat rested. +``` + +Note that the `summaryLength` is an approximate number of words. + +## Comparison + +Each summary type has different characteristics: + - Type|Precedence|Renders markdown|Renders shortcodes|Strips HTML tags|Wraps single lines with `

` - :--|:-:|:-:|:-:|:-:|:-: - Manual|1|:heavy_check_mark:|:heavy_check_mark:|:x:|:heavy_check_mark: - Front matter|2|:heavy_check_mark:|:x:|:x:|:x: - Automatic|3|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:x: ++Type|Precedence|Renders markdown|Renders shortcodes|Wraps single lines with `

` ++:--|:-:|:-:|:-:|:-: ++Manual|1|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: ++Front matter|2|:heavy_check_mark:|:x:|:x: ++Automatic|3|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: + +## Rendering + +Render the summary in a template by calling the [`Summary`] method on a `Page` object. + +[`Summary`]: /methods/page/summary + +```go-html-template +{{ range site.RegularPages }} +

{{ .LinkTitle }}

+
+ {{ .Summary }} + {{ if .Truncated }} + More ... + {{ end }} +
+{{ end }} +``` diff --cc docs/content/en/methods/page/Content.md index a9d38367c,000000000..373c6590a mode 100644,000000..100644 --- a/docs/content/en/methods/page/Content.md +++ b/docs/content/en/methods/page/Content.md @@@ -1,22 -1,0 +1,22 @@@ +--- +title: Content +description: Returns the rendered content of the given page. +categories: [] +keywords: [] +action: + related: ++ - methods/page/Summary ++ - methods/page/ContentWithoutSummary + - methods/page/RawContent + - methods/page/Plain + - methods/page/PlainWords + - methods/page/RenderShortcodes + returnType: template.HTML + signatures: [PAGE.Content] +--- + - 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 ++The `Content` method on a `Page` object renders Markdown and shortcodes to HTML. + +```go-html-template +{{ .Content }} +``` diff --cc docs/content/en/methods/page/ContentWithoutSummary.md index 000000000,000000000..5080f6717 new file mode 100644 --- /dev/null +++ b/docs/content/en/methods/page/ContentWithoutSummary.md @@@ -1,0 -1,0 +1,28 @@@ ++--- ++title: ContentWithoutSummary ++description: Returns the rendered content of the given page, excluding the content summary. ++categories: [] ++keywords: [] ++action: ++ related: ++ - methods/page/Content ++ - methods/page/Summary ++ - methods/page/RawContent ++ - methods/page/Plain ++ - methods/page/PlainWords ++ - methods/page/RenderShortcodes ++ returnType: template.HTML ++ signatures: [PAGE.ContentWithoutSummary] ++--- ++ ++{{< new-in 0.134.0 >}} ++ ++Applicable when using manual or automatic [content summaries], the `ContentWithoutSummary` method on a `Page` object renders Markdown and shortcodes to HTML, excluding the content summary from the result. ++ ++[content summaries]: /content-management/summaries/#manual-summary ++ ++```go-html-template ++{{ .ContentWithoutSummary }} ++``` ++ ++The `ContentWithoutSummary` method returns an empty string if you define the content summary in front matter. diff --cc docs/content/en/methods/page/Plain.md index 3aae1ed61,000000000..06d2bde48 mode 100644,000000..100644 --- a/docs/content/en/methods/page/Plain.md +++ b/docs/content/en/methods/page/Plain.md @@@ -1,28 -1,0 +1,30 @@@ +--- +title: Plain +description: Returns the rendered content of the given page, removing all HTML tags. +categories: [] +keywords: [] +action: + related: + - methods/page/Content ++ - methods/page/Summary ++ - methods/page/ContentWithoutSummary + - methods/page/RawContent + - methods/page/PlainWords + - methods/page/RenderShortcodes + returnType: string + 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]. + +To prevent Go's [html/template] package from escaping HTML entities, pass the result through the [`htmlUnescape`] function. + +```go-html-template +{{ .Plain | htmlUnescape }} +``` + +[shortcodes]: /getting-started/glossary/#shortcode +[html/template]: https://pkg.go.dev/html/template +[entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity +[tags]: https://developer.mozilla.org/en-US/docs/Glossary/Tag +[`htmlUnescape`]: /functions/transform/htmlunescape/ diff --cc docs/content/en/methods/page/PlainWords.md index 4f70193fe,000000000..221fd741b mode 100644,000000..100644 --- a/docs/content/en/methods/page/PlainWords.md +++ b/docs/content/en/methods/page/PlainWords.md @@@ -1,36 -1,0 +1,39 @@@ +--- +title: PlainWords +description: Calls the Plain method, splits the result into a slice of words, and returns the slice. +categories: [] +keywords: [] +action: + related: + - methods/page/Content ++ - methods/page/Summary ++ - methods/page/ContentWithoutSummary + - methods/page/RawContent + - methods/page/Plain ++ - methods/page/RenderShortcodes + returnType: '[]string' + signatures: [PAGE.PlainWords] +--- + +The `PlainWords` method on a `Page` object calls the [`Plain`] method, then uses Go's [`strings.Fields`] function to split the result into words. + +{{% note %}} +_Fields splits the string s around each instance of one or more consecutive whitespace characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of s or an empty slice if s contains only whitespace._ + +[`unicode.IsSpace`]: https://pkg.go.dev/unicode#IsSpace +{{% /note %}} + +As a result, elements within the slice may contain leading or trailing punctuation. + +```go-html-template +{{ .PlainWords }} +``` + +To determine the approximate number of unique words on a page: + +```go-html-template +{{ .PlainWords | uniq }} → 42 +``` + +[`Plain`]: /methods/page/plain/ +[`strings.Fields`]: https://pkg.go.dev/strings#Fields diff --cc docs/content/en/methods/page/RawContent.md index 12686c695,000000000..e4ab8a28e mode 100644,000000..100644 --- a/docs/content/en/methods/page/RawContent.md +++ b/docs/content/en/methods/page/RawContent.md @@@ -1,31 -1,0 +1,33 @@@ +--- +title: RawContent +description: Returns the raw content of the given page. +categories: [] +keywords: [] +action: + related: + - methods/page/Content ++ - methods/page/Summary ++ - methods/page/ContentWithoutSummary + - methods/page/Plain + - methods/page/PlainWords + - methods/page/RenderShortcodes + returnType: string + signatures: [PAGE.RawContent] +--- + +The `RawContent` method on a `Page` object returns the raw content. The raw content does not include front matter. + +```go-html-template +{{ .RawContent }} +``` + +This is useful when rendering a page in a plain text [output format]. + +{{% note %}} +[Shortcodes] within the content are not rendered. To get the raw content with shortcodes rendered, use the [`RenderShortcodes`] method on a `Page` object. + +[shortcodes]: /getting-started/glossary/#shortcode +[`RenderShortcodes`]: /methods/page/rendershortcodes/ +{{% /note %}} + +[output format]: /templates/output-formats/ diff --cc docs/content/en/methods/page/RenderShortcodes.md index a4120f69a,000000000..9679fc8d5 mode 100644,000000..100644 --- a/docs/content/en/methods/page/RenderShortcodes.md +++ b/docs/content/en/methods/page/RenderShortcodes.md @@@ -1,79 -1,0 +1,81 @@@ +--- +title: RenderShortcodes +description: Renders all shortcodes in the content of the given page, preserving the surrounding markup. +categories: [] +keywords: [] +action: + related: - - methods/page/RenderString + - methods/page/Content ++ - methods/page/Summary ++ - methods/page/ContentWithoutSummary + - methods/page/RawContent + - methods/page/Plain + - methods/page/PlainWords ++ - methods/page/RenderString + returnType: template.HTML + signatures: [PAGE.RenderShortcodes] +toc: true +--- + +{{< new-in 0.117.0 >}} + +Use this method in shortcode templates to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents. + +For example: + +{{< code file=layouts/shortcodes/include.html >}} +{{ with site.GetPage (.Get 0) }} + {{ .RenderShortcodes }} +{{ end }} +{{< /code >}} + +Then call the shortcode in your Markdown: + +{{< code file=content/about.md lang=md >}} +{{%/* include "/snippets/services.md" */%}} +{{%/* include "/snippets/values.md" */%}} +{{%/* include "/snippets/leadership.md" */%}} +{{< /code >}} + +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: + +- `{{}}` 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. + +Use the latter for the "include" shortcode described above. + +## Further explanation + +To understand what is returned by the `RenderShortcodes` method, consider this content file + +{{< code file=content/about.md lang=text >}} ++++ +title = 'About' +date = 2023-10-07T12:28:33-07:00 ++++ + +{{}} + +An *emphasized* word. +{{< /code >}} + +With this template code: + +```go-html-template +{{ $p := site.GetPage "/about" }} +{{ $p.RenderShortcodes }} +``` + +Hugo renders this:; + +```html +https://example.org/privacy/ + +An *emphasized* word. +``` + +Note that the shortcode within the content file was rendered, but the surrounding Markdown was preserved. diff --cc docs/content/en/render-hooks/blockquotes.md index 607514f04,000000000..143c536d1 mode 100755,000000..100755 --- a/docs/content/en/render-hooks/blockquotes.md +++ b/docs/content/en/render-hooks/blockquotes.md @@@ -1,185 -1,0 +1,207 @@@ +--- +title: Blockquote render hooks +linkTitle: Blockquotes +description: Create a blockquote render hook to override the rendering of Markdown blockquotes to HTML. +categories: [render hooks] +keywords: [] +menu: + docs: + parent: render-hooks + weight: 30 +weight: 30 +toc: true +--- + +{{< new-in 0.132.0 >}} + +## Context + +Blockquote render hook templates receive the following [context]: + +[context]: /getting-started/glossary/#context + +###### AlertType + +(`string`) Applicable when [`Type`](#type) is `alert`, this is the alert type converted to lowercase. See the [alerts](#alerts) section below. + +###### AlertTitle + +{{< new-in 0.134.0 >}} + - (`hstring.HTML`) Applicable when [`Type`](#type) is `alert` when using [Obsidian callouts] syntax, this is the alert title converted to HTML. ++(`template.HTML`) Applicable when [`Type`](#type) is `alert`, this is the alert title. See the [alerts](#alerts) section below. + +###### AlertSign + +{{< new-in 0.134.0 >}} + - (`string`) Applicable when [`Type`](#type) is `alert` when using [Obsidian callouts] syntax, this is one of "+", "-" or "" (empty string) to indicate the presence of a foldable sign. - - [Obsidian callouts]: https://help.obsidian.md/Editing+and+formatting/Callouts ++(`string`) Applicable when [`Type`](#type) is `alert`, this is the alert sign. Typically used to indicate whether an alert is graphically foldable, this is one of `+`, `-`, or an empty string. See the [alerts](#alerts) section below. + +###### Attributes + +(`map`) The [Markdown attributes], available if you configure your site as follows: + +[Markdown attributes]: /content-management/markdown-attributes/ + +{{< code-toggle file=hugo >}} +[markup.goldmark.parser.attribute] +block = true +{{< /code-toggle >}} + +###### Ordinal + +(`int`) The zero-based ordinal of the blockquote on the page. + +###### Page + +(`page`) A reference to the current page. + +###### PageInner + - (`page`) A reference to a page nested via the [`RenderShortcodes`] method. ++(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). + +[`RenderShortcodes`]: /methods/page/rendershortcodes + +###### Position + +(`string`) The position of the blockquote within the page content. + +###### Text - (`string`) The blockquote text, excluding the alert designator if present. See the [alerts](#alerts) section below. ++(`template.HTML`) The blockquote text, excluding the first line if [`Type`](#type) is `alert`. See the [alerts](#alerts) section below. + +###### Type + +(`bool`) The blockquote type. Returns `alert` if the blockquote has an alert designator, else `regular`. See the [alerts](#alerts) section below. + +## Examples + +In its default configuration, Hugo renders Markdown blockquotes according to the [CommonMark specification]. To create a render hook that does the same thing: + +[CommonMark specification]: https://spec.commonmark.org/current/ + +{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}} +
- {{ .Text | safeHTML }} ++ {{ .Text }} +
+{{< /code >}} + +To render a blockquote as an HTML `figure` element with an optional citation and caption: + +{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}} +
+
- {{ .Text | safeHTML }} ++ {{ .Text }} +
+ {{ with .Attributes.caption }} +
+ {{ . | safeHTML }} +
+ {{ end }} +
+{{< /code >}} + +Then in your markdown: + +```text +> Some text +{cite="https://gohugo.io" caption="Some caption"} +``` + +## Alerts + - Also known as _callouts_ or _admonitions_, alerts are blockquotes used to emphasize critical information. For example: ++Also known as _callouts_ or _admonitions_, alerts are blockquotes used to emphasize critical information. ++ ++### Basic syntax ++ ++With the basic Markdown syntax, the first line of each alert is an alert designator consisting of an exclamation point followed by the alert type, wrapped within brackets. For example: + +{{< code file=content/example.md lang=text >}} +> [!NOTE] +> Useful information that users should know, even when skimming content. + +> [!TIP] +> Helpful advice for doing things better or more easily. + +> [!IMPORTANT] +> Key information users need to know to achieve their goal. + +> [!WARNING] +> Urgent info that needs immediate user attention to avoid problems. + +> [!CAUTION] +> Advises about risks or negative outcomes of certain actions. +{{< /code >}} + ++The basic syntax is compatible with [GitHub], [Obsidian], and [Typora]. ++ ++[GitHub]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts ++[Obsidian]: https://help.obsidian.md/Editing+and+formatting/Callouts ++[Typora]: https://support.typora.io/Markdown-Reference/#callouts--github-style-alerts ++ ++### Extended syntax ++ ++With the extended Markdown syntax, you may optionally include an alert sign and/or an alert title. The alert sign is one of `+` or `-`, typically used to indicate whether an alert is graphically foldable. For example: ++ ++{{< code file=content/example.md lang=text >}} ++> [!WARNING]+ Radiation hazard ++> Do not approach or handle without protective gear. ++{{< /code >}} ++ ++The extended syntax is compatible with [Obsidian]. + +{{% note %}} - This syntax is compatible with both the GitHub Alert Markdown extension and Obsidian's callout syntax. - But note that GitHub will not recognize callouts with one of Obsidian's extensions (e.g. callout title or the foldable sign). ++The extended syntax is not compatible with GitHub or Typora. If you include an alert sign or an alert title, these applications render the Markdown as a blockquote. +{{% /note %}} + - The first line of each alert is an alert designator consisting of an exclamation point followed by the alert type, wrapped within brackets. ++### Example + - The blockquote render hook below renders a multilingual alert if an alert designator is present, otherwise it renders a blockquote according to the CommonMark specification. ++This blockquote render hook renders a multilingual alert if an alert designator is present, otherwise it renders a blockquote according to the CommonMark specification. + +{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}} +{{ $emojis := dict + "caution" ":exclamation:" + "important" ":information_source:" + "note" ":information_source:" + "tip" ":bulb:" + "warning" ":information_source:" +}} + +{{ if eq .Type "alert" }} +
+

+ {{ transform.Emojify (index $emojis .AlertType) }} - {{ or (i18n .AlertType) (title .AlertType) }} ++ {{ with .AlertTitle }} ++ {{ . }} ++ {{ else }} ++ {{ or (i18n .AlertType) (title .AlertType) }} ++ {{ end }} +

- {{ .Text | safeHTML }} ++ {{ .Text }} +
+{{ else }} +
- {{ .Text | safeHTML }} ++ {{ .Text }} +
+{{ end }} +{{< /code >}} + +To override the label, create these entries in your i18n files: + +{{< code-toggle file=i18n/en.toml >}} +caution = 'Caution' +important = 'Important' +note = 'Note' +tip = 'Tip' +warning = 'Warning' +{{< /code-toggle >}} + - +Although you can use one template with conditional logic as shown above, you can also create separate templates for each [`Type`](#type) of blockquote: + +```text +layouts/ +└── _default/ + └── _markup/ + ├── render-blockquote-alert.html + └── render-blockquote-regular.html +``` ++ ++{{% include "/render-hooks/_common/pageinner.md" %}} diff --cc docs/content/en/render-hooks/headings.md index 8ae3b808a,000000000..dc64296ea mode 100755,000000..100755 --- a/docs/content/en/render-hooks/headings.md +++ b/docs/content/en/render-hooks/headings.md @@@ -1,81 -1,0 +1,81 @@@ +--- +title: Heading render hooks +linkTitle: Headings +description: Create a heading render hook to override the rendering of Markdown headings to HTML. +categories: [render hooks] +keywords: [] +menu: + docs: + parent: render-hooks + weight: 50 +weight: 50 +toc: true +--- + +## Context + +Heading render hook templates receive the following [context]: + +[context]: /getting-started/glossary/#context + +###### Anchor + +(`string`) The `id` attribute of the heading element. + +###### Attributes + +(`map`) The [Markdown attributes], available if you configure your site as follows: + +[Markdown attributes]: /content-management/markdown-attributes/ + +{{< code-toggle file=hugo >}} +[markup.goldmark.parser.attribute] +title = true +{{< /code-toggle >}} + +###### Level + +(`int`) The heading level, 1 through 6. + +###### Page + +(`page`) A reference to the current page. + +###### PageInner + +{{< new-in 0.125.0 >}} + +(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). + +[`RenderShortcodes`]: /methods/page/rendershortcodes + +###### PlainText + +(`string`) The heading text as plain text. + +###### Text + - (`string`) The heading text. ++(`template.HTML`) The heading text. + +## 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: + +[CommonMark specification]: https://spec.commonmark.org/current/ + +{{< code file=layouts/_default/_markup/render-heading.html copy=true >}} + - {{- .Text | safeHTML -}} ++ {{- .Text -}} + +{{< /code >}} + +To add an anchor link to the right of each heading: + +{{< code file=layouts/_default/_markup/render-heading.html copy=true >}} + - {{ .Text | safeHTML }} ++ {{ .Text }} + # + +{{< /code >}} + +{{% include "/render-hooks/_common/pageinner.md" %}} diff --cc docs/content/en/render-hooks/images.md index 1638ceeae,000000000..eca346c10 mode 100755,000000..100755 --- a/docs/content/en/render-hooks/images.md +++ b/docs/content/en/render-hooks/images.md @@@ -1,165 -1,0 +1,165 @@@ +--- +title: Image render hooks +linkTitle: Images +description: Create an image render to hook override the rendering of Markdown images to HTML. +categories: [render hooks] +keywords: [] +menu: + docs: + parent: render-hooks + weight: 60 +weight: 60 +toc: true +--- + +## Markdown + +A Markdown image has three components: the image description, the image destination, and optionally the image title. + +```text +![white kitten](/images/kitten.jpg "A kitten!") + ------------ ------------------ --------- + description destination title +``` + +These components are passed into the render hook [context] as shown below. + +[context]: /getting-started/glossary/#context + +## Context + +Image render hook templates receive the following context: + +###### Attributes + +(`map`) The [Markdown attributes], available if you configure your site as follows: + +[Markdown attributes]: /content-management/markdown-attributes/ + +{{< code-toggle file=hugo >}} +[markup.goldmark.parser] +wrapStandAloneImageWithinParagraph = false +[markup.goldmark.parser.attribute] +block = true +{{< /code-toggle >}} + +###### Destination + +(`string`) The image destination. + +###### IsBlock + +(`bool`) Returns true if a standalone image is not wrapped within a paragraph element. + +###### Ordinal + +(`int`) The zero-based ordinal of the image on the page. + +###### Page + +(`page`) A reference to the current page. + +###### PageInner + +{{< new-in 0.125.0 >}} + +(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). + +[`RenderShortcodes`]: /methods/page/rendershortcodes + +###### PlainText + +(`string`) The image description as plain text. + +###### Text + - (`string`) The image description. ++(`template.HTML`) The image description. + +###### Title + +(`string`) The image title. + +## Examples + +{{% note %}} +With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace 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: + +[CommonMark specification]: https://spec.commonmark.org/current/ + +{{< code file=layouts/_default/_markup/render-image.html copy=true >}} +{{ . }} +{{- /* chomp trailing newline */ -}} +{{< /code >}} + +To render standalone images within `figure` elements: + +{{< code file=layouts/_default/_markup/render-image.html copy=true >}} +{{- if .IsBlock -}} +
+ {{ . }} + {{- with .Title }}
{{ . }}
{{ end -}} +
+{{- else -}} + {{ . }} +{{- end -}} +{{< /code >}} + +Note that the above requires the following site configuration: + +{{< code-toggle file=hugo >}} +[markup.goldmark.parser] +wrapStandAloneImageWithinParagraph = false +{{< /code-toggle >}} + +## Default + +{{< 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]: {{% eturl render-image %}} + +{{< code-toggle file=hugo >}} +[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 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. ++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 unable to resolve a destination. + +[page resource]: /getting-started/glossary/#page-resource +[global resource]: /getting-started/glossary/#global-resource + +You must place global resources in the assets directory. If you have placed your resources in the static directory, and you are unable or unwilling to move them, you must mount the static directory to the assets directory by including both of these entries in your site configuration: + +{{< code-toggle file=hugo >}} +[[module.mounts]] +source = 'assets' +target = 'assets' + +[[module.mounts]] +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. + +{{% include "/render-hooks/_common/pageinner.md" %}} diff --cc docs/content/en/render-hooks/introduction.md index 3745fc398,000000000..2d1598fcb mode 100755,000000..100755 --- a/docs/content/en/render-hooks/introduction.md +++ b/docs/content/en/render-hooks/introduction.md @@@ -1,88 -1,0 +1,91 @@@ +--- +title: Introduction +description: An introduction to Hugo's render hooks. +categories: [render hooks] +keywords: [] +menu: + docs: + identifier: render-hooks-introduction + parent: render-hooks + weight: 20 +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: + +- [Blockquotes](/render-hooks/blockquotes) +- [Code blocks](/render-hooks/code-blocks) +- [Headings](/render-hooks/headings) +- [Images](/render-hooks/images) +- [Links](/render-hooks/links) +- [Passthrough elements](/render-hooks/passthrough) ++- [Tables](/render-hooks/tables) + +{{% note %}} +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. + +[content formats]: /content-management/formats/ +{{% /note %}} + +For example, consider this Markdown: + +```text +[Hugo](https://gohugo.io) + +![kitten](kitten.jpg) +``` + +Without link or image render hooks, this example above is rendered to: + +```html +

Hugo

+

kitten

+``` + +By creating link and image render hooks, you can alter the conversion from Markdown to HTML. For example: + +```html +

Hugo

+

kitten

+``` + +Each render hook is a template, with one template for each supported element type: + +```text +layouts/ +└── _default/ + └── _markup/ + ├── render-blockquote.html + ├── render-codeblock.html + ├── render-heading.html + ├── render-image.html - └── render-link.html ++ ├── render-link.html ++ ├── render-passthrough.html ++ └── render-table.html +``` + +The template lookup order allows you to create different render hooks for each page [type], [kind], language, and [output format]. For example: + +```text +layouts/ +├── _default/ +│ └── _markup/ +│ ├── render-link.html +│ └── render-link.rss.xml +├── books/ +│ └── _markup/ +│ ├── render-link.html +│ └── render-link.rss.xml +└── films/ + └── _markup/ + ├── render-link.html + └── render-link.rss.xml +``` + +[kind]: /getting-started/glossary/#page-kind +[output format]: /getting-started/glossary/#output-format +[type]: /getting-started/glossary/#content-type + +The remaining pages in this section describe each type of render hook, including examples and the context received by each template. diff --cc docs/content/en/render-hooks/links.md index 79c3d6926,000000000..9505e989b mode 100755,000000..100755 --- a/docs/content/en/render-hooks/links.md +++ b/docs/content/en/render-hooks/links.md @@@ -1,133 -1,0 +1,133 @@@ +--- +title: Link render hooks +linkTitle: Links +description: Create a link render hook to override the rendering of Markdown links to HTML. +categories: [render hooks] +keywords: [] +menu: + docs: + parent: render-hooks + weight: 70 +weight: 70 +toc: true +--- + +## Markdown + +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") + ------ ------------- ------------- + text destination title +``` + +These components are passed into the render hook [context] as shown below. + +[context]: /getting-started/glossary/#context + +## Context + +Link render hook templates receive the following context: + +[context]: /getting-started/glossary/#context + +###### Destination + +(`string`) The link destination. + +###### Page + +(`page`) A reference to the current page. + +###### PageInner + +{{< new-in 0.125.0 >}} + +(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). + +[`RenderShortcodes`]: /methods/page/rendershortcodes + +###### PlainText + +(`string`) The link description as plain text. + +###### Text + - (`string`) The link description. ++(`template.HTML`) The link description. + +###### Title + +(`string`) The link title. + +## Examples + +{{% note %}} +With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace 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: + +[CommonMark specification]: https://spec.commonmark.org/current/ + +{{< code file=layouts/_default/_markup/render-link.html copy=true >}} + - {{- with .Text | safeHTML }}{{ . }}{{ end -}} ++ {{- with .Text }}{{ . }}{{ end -}} + +{{- /* chomp trailing newline */ -}} +{{< /code >}} + +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 -}} + - {{- with .Text | safeHTML }}{{ . }}{{ end -}} ++ {{- with .Text }}{{ . }}{{ end -}} + +{{- /* chomp trailing newline */ -}} +{{< /code >}} + +## Default + +{{< 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]: {{% eturl render-link %}} + +{{< code-toggle file=hugo >}} +[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 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. ++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 unable to resolve a destination. + +[page resource]: /getting-started/glossary/#page-resource +[global resource]: /getting-started/glossary/#global-resource + +You must place global resources in the assets directory. If you have placed your resources in the static directory, and you are unable or unwilling to move them, you must mount the static directory to the assets directory by including both of these entries in your site configuration: + +{{< code-toggle file=hugo >}} +[[module.mounts]] +source = 'assets' +target = 'assets' + +[[module.mounts]] +source = 'static' +target = 'assets' +{{< /code-toggle >}} + +{{% include "/render-hooks/_common/pageinner.md" %}} diff --cc docs/content/en/render-hooks/tables.md index 000000000,000000000..41eadad7b new file mode 100755 --- /dev/null +++ b/docs/content/en/render-hooks/tables.md @@@ -1,0 -1,0 +1,106 @@@ ++--- ++title: Table render hooks ++linkTitle: Tables ++description: Create a table render hook to override the rendering of Markdown tables to HTML. ++categories: [render hooks] ++keywords: [] ++menu: ++ docs: ++ parent: render-hooks ++ weight: 90 ++weight: 90 ++toc: true ++--- ++ ++{{< new-in 0.134.0 >}} ++ ++## Context ++ ++Table render hook templates receive the following [context]: ++ ++[context]: /getting-started/glossary/#context ++ ++###### Attributes ++ ++(`map`) The [Markdown attributes], available if you configure your site as follows: ++ ++[Markdown attributes]: /content-management/markdown-attributes/ ++ ++{{< code-toggle file=hugo >}} ++[markup.goldmark.parser.attribute] ++block = true ++{{< /code-toggle >}} ++ ++###### Ordinal ++ ++(`int`) The zero-based ordinal of the table on the page. ++ ++###### Page ++ ++(`page`) A reference to the current page. ++ ++###### PageInner ++ ++(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). ++ ++[`RenderShortcodes`]: /methods/page/rendershortcodes ++ ++###### Position ++ ++(`string`) The position of the table within the page content. ++ ++###### THead ++(`slice`) A slice of table header rows, where each element is a slice of table cells. ++ ++###### TBody ++(`slice`) A slice of table body rows, where each element is a slice of table cells. ++ ++## Table cells ++ ++Each table cell within the slice of slices returned by the `THead` and `TBody` methods has the following fields: ++ ++###### Alignment ++(`string`) The alignment of the text within the table cell, one of `left`, `center`, or `right`. ++ ++###### Text ++(`template.HTML`) The text within the table cell. ++ ++## Example ++ ++In its default configuration, Hugo renders Markdown tables according to the [GitHub Flavored Markdown specification]. To create a render hook that does the same thing: ++ ++[GitHub Flavored Markdown specification]: https://github.github.com/gfm/#tables-extension- ++ ++{{< code file=layouts/_default/_markup/render-table.html copy=true >}} ++ ++ ++ {{- range .THead }} ++ ++ {{- range . }} ++ ++ {{- end }} ++ ++ {{- end }} ++ ++ ++ {{- range .TBody }} ++ ++ {{- range . }} ++ ++ {{- end }} ++ ++ {{- end }} ++ ++
++ {{- .Text -}} ++
++ {{- .Text -}} ++
++{{< /code >}} ++ ++{{% include "/render-hooks/_common/pageinner.md" %}} diff --cc docs/netlify.toml index 44c10a3c9,000000000..2780fe747 mode 100644,000000..100644 --- a/docs/netlify.toml +++ b/docs/netlify.toml @@@ -1,30 -1,0 +1,30 @@@ +[build] + publish = "public" + command = "hugo --gc --minify" + + [build.environment] - HUGO_VERSION = "0.133.1" ++ HUGO_VERSION = "0.134.0" + +[context.production.environment] + HUGO_ENV = "production" + HUGO_ENABLEGITINFO = "true" + +[context.split1] + command = "hugo --gc --minify --enableGitInfo" + + [context.split1.environment] + HUGO_ENV = "production" + +[context.deploy-preview] + command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL" + +[context.branch-deploy] + command = "hugo --gc --minify -b $DEPLOY_PRIME_URL" + +[context.next.environment] + HUGO_ENABLEGITINFO = "true" + +[[redirects]] + from = "/npmjs/*" + to = "/npmjs/" + status = 200