blogs/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2026-08-24 23:38:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Miscellaneous edits

Browse Source
This commit is contained in:
Joe Mooring
2024-05-25 16:17:55 -07:00
committed by GitHub
parent 35849e55af
commit b76e81697b
9 changed files with 57 additions and 175 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/content-management/summaries.md
+13 -6
View File
@@ -29,14 +29,20 @@ It is natural to accompany the summary with links to the original content, and a
### Automatic summary splitting
By default, Hugo automatically takes the first 70 words of your content as its summary and stores it into the `.Summary` page variable for use in your templates. You may customize the summary length by setting `summaryLength` in your [site configuration](/getting-started/configuration/).
By default, Hugo automatically takes the first 70 words of your content as its summary. Access this value from a template using the [`Summary`] method on a `Page` object. You may customize the summary length by setting [`summaryLength`] in your site configuration.
[`Summary`]: /methods/page/summary
[`summaryLength`]: /getting-started/configuration/#summarylength
{{% note %}}
You can customize how HTML tags in the summary are loaded using functions such as `plainify` and `safeHTML`.
{{% /note %}}
{{% note %}}
The Hugo-defined summaries are set to use word count calculated by splitting the text by one or more consecutive whitespace characters. If you are creating content in a `CJK` language and want to use Hugo's automatic summary splitting, set `hasCJKLanguage` to `true` in your [site configuration](/getting-started/configuration/).
The Hugo-defined summaries are set to use word count calculated by splitting the text by one or more consecutive whitespace characters. If you are creating content in a [`CJK`] language and want to use Hugo's automatic summary splitting, set [`hasCJKLanguage`] to `true` in your site configuration.
[`CJK`]: /getting-started/glossary/#cjk
[`hasCJKLanguage`]: /getting-started/configuration/#hascjklanguage
{{% /note %}}
### Manual summary splitting
@@ -63,7 +69,7 @@ Be careful to enter `<!--more-->` exactly; i.e., all lowercase and with no white
### Front matter summary
You might want your summary to be something other than the text that starts the article. In this case you can provide a separate summary in the `summary` variable of the article front matter.
You might want your summary to be something other than the text that starts the article. In this case you can provide a separate summary in the `summary` field in front matter.
Pros
: Complete freedom of text independent of the content of the article. Markup can be used within the summary.
@@ -76,11 +82,11 @@ Cons
Because there are multiple ways in which a summary can be specified it is useful to understand the order of selection Hugo follows when deciding on the text to be returned by `.Summary`. It is as follows:
1. If there is a `<!--more-->` summary divider present in the article, the text up to the divider will be provided as per the manual summary split method
2. If there is a `summary` variable in the article front matter the value of the variable will be provided as per the front matter summary method
2. If there is a `summary` field in the article front matter the value of the variable will be provided as per the front matter summary method
3. The text at the start of the article will be provided as per the automatic summary split method
{{% note %}}
Hugo uses the _first_ of the above steps that returns text. So if, for example, your article has both `summary` variable in its front matter and a `<!--more-->` summary divider Hugo will use the manual summary split method.
Hugo uses the _first_ of the above steps that returns text. So if, for example, your article has both `summary` field in its front matter and a `<!--more-->` summary divider Hugo will use the manual summary split method.
{{% /note %}}
## Example: first 10 articles with summaries
@@ -105,8 +111,9 @@ You can show content summaries with the following code. You could use the follow
{{ end }}
{{< /code >}}
Note how the `.Truncated` boolean variable value may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article.
Note how the `Truncated` method may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article.
[`Truncated`]: /methods/page/truncated
[`Permalink`]: /methods/page/permalink/
[`RelPermalink`]: /methods/page/relpermalink/
[`Summary`]: /methods/page/summary/
content/en/content-management/taxonomies.md
+6 -17
View File
@@ -130,26 +130,15 @@ If you want to disable all taxonomies altogether, see the use of `disableKinds`
You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose.
{{% /note %}}
## Add taxonomies to content
## Assign terms to content
Once a taxonomy is defined at the site level, any piece of content can be assigned to it, regardless of [content type] or [content section].
Assigning content to a taxonomy is done in the [front matter]. Simply create a variable with the *plural* name of the taxonomy and assign all terms you want to apply to the instance of the content type.
{{% note %}}
If you would like the ability to quickly generate content files with preconfigured taxonomies or terms, read the docs on [Hugo archetypes](/content-management/archetypes/).
{{% /note %}}
### Example: front matter with taxonomies
To assign one or more terms to a page, create a front matter field using the plural name of the taxonomy, then add terms to the corresponding array. For example:
{{< code-toggle file=content/example.md fm=true >}}
title = "Hugo: A fast and flexible static site generator"
tags = [ "Development", "Go", "fast", "Blogging" ]
categories = [ "Development" ]
series = [ "Go Web Dev" ]
slug = "hugo"
project_url = "https://github.com/gohugoio/hugo"
{{</ code-toggle >}}
title = 'Example'
tags = ['Tag A','Tag B']
categories = ['Category A','Category B']
{{< /code-toggle >}}
## Order taxonomies
content/en/content-management/toc.md
-113
View File
@@ -1,113 +0,0 @@
---
title: Table of contents
description: Hugo can automatically parse Markdown content and create a Table of Contents you can use in your templates.
categories: [content management]
keywords: [table of contents, toc]
menu:
docs:
parent: content-management
weight: 210
weight: 210
toc: true
aliases: [/extras/toc/]
---
{{% note %}}
Previously, there was no out-of-the-box way to specify which heading levels you want the TOC to render. [See the related GitHub discussion (#1778)](https://github.com/gohugoio/hugo/issues/1778). As such, the resulting `<nav id="TableOfContents"><ul></ul></nav>` was going to start at `<h1>` when pulling from `{{ .Content }}`.
Hugo [v0.60.0](https://github.com/gohugoio/hugo/releases/tag/v0.60.0) made a switch to [Goldmark](https://github.com/yuin/goldmark/) as the default library for Markdown which has improved and configurable implementation of TOC. Take a look at [how to configure TOC](/getting-started/configuration-markup/#table-of-contents) for Goldmark renderer.
{{% /note %}}
## Usage
Create your Markdown the way you normally would with the appropriate headings. Here is some example content:
```md
<!-- Your front matter up here -->
## Introduction
One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin.
## My Heading
He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment.
### My Subheading
A collection of textile samples lay spread out on the table - Samsa was a traveling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops
```
Hugo will take this Markdown and create a table of contents from `## Introduction`, `## My Heading`, and `### My Subheading` and then store it in the [page variable][pagevars]`.TableOfContents`.
The `.TableOfContents` method on a `Page` object outputs a `<nav id="TableOfContents">` element with a child `<ul>`, whose child `<li>` elements begin with appropriate HTML headings. See [the available settings](/getting-started/configuration-markup/#table-of-contents) to configure what heading levels you want to include in TOC.
## Template example: basic TOC
The following is an example of a very basic [single page template]:
{{< code file=layout/_default/single.html >}}
{{ define "main" }}
<main>
<article>
<header>
<h1>{{ .Title }}</h1>
</header>
{{ .Content }}
</article>
<aside>
{{ .TableOfContents }}
</aside>
</main>
{{ end }}
{{< /code >}}
## Template example: TOC partial
The following is a [partial template][partials] that adds slightly more logic for page-level control over your table of contents. It assumes you are using a `toc` field in your content's [front matter] that, unless specifically set to `false`, will add a TOC to any page with a [`WordCount`] greater than 400. This example also demonstrates how to use [conditionals] in your templating:
{{< code file=layouts/partials/toc.html >}}
{{ if and (gt .WordCount 400 ) (.Params.toc) }}
<aside>
<header>
<h2>{{ .Title }}</h2>
</header>
{{ .TableOfContents }}
</aside>
{{ end }}
{{< /code >}}
{{% note %}}
With the preceding example, even pages with > 400 words *and* `toc` not set to `false` will not render a table of contents if there are no headings in the page for the `.TableOfContents` method to pull from.
{{% /note %}}
## Usage with AsciiDoc
In the header of your content file, specify the AsciiDoc TOC directives required to generate the table of contents. Then use the `.TableOfContents` method within your template.
```asciidoc
// <!-- Your front matter up here -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] configuration key
:toclevels: 4
== Section 1
Paragraph 1.
== Section 2
Paragraph 2.
```
Hugo will take this AsciiDoc and create a table of contents store it in the page variable `.TableOfContents`, in the same as described for Markdown.
[conditionals]: /templates/introduction/#conditional-blocks
[`WordCount`]: /methods/page/wordcount
[front matter]: /content-management/front-matter/
[pagevars]: /methods/page/
[partials]: /templates/partials/
[single page template]: /templates/single-page-templates/
content/en/functions/global/page.md
+1 -1
View File
@@ -35,7 +35,7 @@ Do not use the global `page` function in shortcodes, partials called by shortcod
## Explanation
Hugo almost always passes a `Page` as the data context into the top level template (e.g., `single.html`). The one exception is the multihost sitemap template. This means that you can access the current page with the `.` variable in the template.
Hugo almost always passes a `Page` as the data context into the top level template (e.g., `single.html`). The one exception is the multihost sitemap template. This means that you can access the current page with the `.` in the template.
But when you are deeply nested inside of a [content view], [partial], or [render hook], it is not always practical or possible to access the `Page` object.
content/en/methods/page/TableOfContents.md
+1
View File
@@ -8,6 +8,7 @@ action:
- methods/page/Fragments
returnType: template.HTML
signatures: [PAGE.TableOfContents]
aliases: [/content-management/toc/]
---
The `TableOfContents` method on a `Page` object returns an ordered or unordered list of the Markdown [ATX] and [setext] headings within the page content.
content/en/templates/404.md
+33 -35
View File
@@ -1,7 +1,7 @@
---
title: Custom 404 page
linkTitle: 404 page
description: If you know how to create a single page template, you have unlimited options for creating a custom 404.
linkTitle: 404 template
description: Create a template to render a 404 error page.
categories: [templates]
keywords: ['404',page not found]
menu:
@@ -11,45 +11,43 @@ menu:
weight: 220
---
When using Hugo with [GitHub Pages](https://pages.github.com/), you can provide your own template for a [custom 404 error page](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-custom-404-page-for-your-github-pages-site) by creating a 404.html template file in the root of your `layouts` folder. When Hugo generates your site, the `404.html` file will be placed in the root.
404 pages will have all the regular [page variables][pagevars] available to use in the templates.
In addition to the standard page variables, the 404 page has access to all site content accessible from `.Pages`.
```txt
▾ layouts/
404.html
```
## 404.html
This is a basic example of a 404.html template:
To render a 404 error page in the root of your site, create a 404 template in the root of the layouts directory. For example:
{{< code file=layouts/404.html >}}
{{ define "main" }}
<main id="main">
<div>
<h1 id="title"><a href="{{ "" | relURL }}">Go Home</a></h1>
</div>
</main>
<h1>404 Not Found</h1>
<p>The page you requested cannot be found.</p>
<p>
<a href="{{ .Site.Home.RelPermalink }}">
Return to the home page
</a>
</p>
{{ end }}
{{< /code >}}
## Automatic loading
For multilingual sites, add the language key to the file name:
Your 404.html file can be set to load automatically when a visitor enters a mistaken URL path, dependent upon the web serving environment you are using. For example:
```text
layouts/
├── 404.de.html
├── 404.en.html
└── 404.fr.html
```
* [GitHub Pages](/hosting-and-deployment/hosting-on-github/), [GitLab Pages](/hosting-and-deployment/hosting-on-gitlab/) and [Cloudflare Pages](/hosting-and-deployment/hosting-on-cloudflare-pages/). The 404 page is automatic.
* Apache. You can specify `ErrorDocument 404 /404.html` in an `.htaccess` file in the root of your site.
* Nginx. You might specify `error_page 404 /404.html;` in your `nginx.conf` file. [Details here](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page).
* Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI.
* Amazon CloudFront. You can specify the page in the Error Pages section in the CloudFront Console. [Details here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/custom-error-pages.html)
* Caddy Server. Use the `handle_errors` directive to specify error pages for one or more status codes. [Details here](https://caddyserver.com/docs/caddyfile/directives/handle_errors)
* Netlify. Add `/* /404.html 404` to `content/_redirects`. [Details Here](https://www.netlify.com/docs/redirects/#custom-404)
* Azure Static Web App. set `responseOverrides.404.rewrite` and `responseOverrides.404.statusCode` in configfile `staticwebapp.config.json`. [Details here](https://docs.microsoft.com/en-us/azure/static-web-apps/configuration#response-overrides)
* Azure Storage as Static Web Site Hosting. You can specify the `Error document path` in the Static website configuration page of the Azure portal. [Details here](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website).
* DigitalOcean App Platform. You can specify `error_document` in your app specification file or use control panel to set up error document. [Details here](https://docs.digitalocean.com/products/app-platform/how-to/manage-static-sites/#configure-a-static-site).
* [Firebase Hosting](https://firebase.google.com/docs/hosting/full-config#404): `/404.html` automatically gets used as the 404 page.
Your production server redirects the browser to the 404 page when a page is not found. Capabilities and configuration vary by host.
[pagevars]: /methods/page/
Host|Capabilities and configuration
:--|:--
Amazon CloudFront|See [details](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GeneratingCustomErrorResponses.html).
Amazon S3|See [details](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CustomErrorDocSupport.html).
Apache|See [details](https://httpd.apache.org/docs/2.4/custom-error.html).
Azure Static Web Apps|See [details](https://learn.microsoft.com/en-us/azure/static-web-apps/configuration#response-overrides).
Azure Storage|See [details](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website#setting-up-a-static-website).
Caddy|See [deatils](https://caddyserver.com/docs/caddyfile/directives/handle_errors).
Cloudflare Pages|See [details](https://developers.cloudflare.com/pages/configuration/serving-pages/#not-found-behavior).
DigitalOcean App Platform|See [details](https://docs.digitalocean.com/products/app-platform/how-to/manage-static-sites/#configure-a-static-site).
Firebase|See [details](https://firebase.google.com/docs/hosting/full-config#404).
GitHub Pages|Redirection to is automatic and not configurable.
GitLab Pages|See [details](https://docs.gitlab.com/ee/user/project/pages/introduction.html#custom-error-codes-pages).
NGINX|See [details](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page).
Netlify|See [details](https://docs.netlify.com/routing/redirects/redirect-options/).
content/en/templates/embedded.md
+1 -1
View File
@@ -143,7 +143,7 @@ To include the embedded template:
### Configure Open Graph
Hugo's Open Graph template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages.
Hugo's Open Graph template is configured using a mix of configuration settings and [front matter](/content-management/front-matter/) on individual pages.
{{< code-toggle file=hugo >}}
[params]
content/en/templates/menu-templates.md
+1 -1
View File
@@ -1,6 +1,6 @@
---
title: Menu templates
description: Use menu variables and methods in your templates to render a menu.
description: Create templates to render one or more menus.
categories: [templates]
keywords: [lists,sections,menus]
menu:
content/en/templates/partials.md
+1 -1
View File
@@ -68,7 +68,7 @@ As shown in the above example directory structure, you can nest your directories
The second argument in a partial call is the variable being passed down. The above examples are passing the `.`, which tells the template receiving the partial to apply the current [context][context].
This means the partial will *only* be able to access those variables. The partial is isolated and *has no access to the outer scope*. From within the partial, `$.Var` is equivalent to `.Var`.
This means the partial will *only* be able to access those variables. The partial is isolated and cannot access the outer scope. From within the partial, `$.Var` is equivalent to `.Var`.
## Returning a value from a partial