diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2023-12-04 15:24:01 +0100 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2023-12-04 15:24:01 +0100 |
commit | d19ed4d4e69f51873135f05a51831d25ecc2071e (patch) | |
tree | 74dfd9af2b0f4a6c0933266c50ceaa569d388c71 /docs/content/en/content-management | |
parent | 9f978d387f8b7cb6bc03fe6b4dd52bb16862a784 (diff) | |
parent | 35dec7c96f7ee3eb17dd444f7067f0c776fb56ae (diff) |
Merge commit '35dec7c96f7ee3eb17dd444f7067f0c776fb56ae'
Diffstat (limited to 'docs/content/en/content-management')
26 files changed, 615 insertions, 391 deletions
diff --git a/docs/content/en/content-management/_common/_index.md b/docs/content/en/content-management/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/docs/content/en/content-management/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + +<!-- +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. +--> diff --git a/docs/content/en/content-management/_common/page-kinds.md b/docs/content/en/content-management/_common/page-kinds.md new file mode 100644 index 000000000..07a53e8e6 --- /dev/null +++ b/docs/content/en/content-management/_common/page-kinds.md @@ -0,0 +1,17 @@ +--- +# Do not remove front matter. +--- + +| Kind | Description | Example | +|----------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------| +| `home` | The landing page for the home page | `/index.html` | +| `page` | The landing page for a given page | `my-post` page (`/posts/my-post/index.html`) | +| `section` | The landing page of a given section | `posts` section (`/posts/index.html`) | +| `taxonomy` | The landing page for a taxonomy | `tags` taxonomy (`/tags/index.html`) | +| `term` | The landing page for one taxonomy's term | term `awesome` in `tags` taxonomy (`/tags/awesome/index.html`) | + +Four other page kinds unrelated to content are `robotsTXT`, `RSS`, `sitemap`, and `404`. Although primarily for internal use, you can specify the name when disabling one or more page kinds on your site. For example: + +{{< code-toggle file=hugo >}} +disableKinds = ['robotsTXT','404'] +{{< /code-toggle >}} diff --git a/docs/content/en/content-management/_index.md b/docs/content/en/content-management/_index.md index 35f85a641..66af24681 100644 --- a/docs/content/en/content-management/_index.md +++ b/docs/content/en/content-management/_index.md @@ -2,13 +2,13 @@ title: Content management linkTitle: Overview description: Hugo makes managing large static sites easy with support for archetypes, content types, menus, cross references, summaries, and more. +categories: [] +keywords: [] menu: docs: identifier: content-management-overview parent: content-management weight: 10 -keywords: [source, organization] -categories: [content management] weight: 10 aliases: [/content/,/content/organization] --- diff --git a/docs/content/en/content-management/archetypes.md b/docs/content/en/content-management/archetypes.md index fe460f91f..94f038848 100644 --- a/docs/content/en/content-management/archetypes.md +++ b/docs/content/en/content-management/archetypes.md @@ -1,15 +1,15 @@ --- title: Archetypes description: An archetype is a template for new content. -keywords: [archetypes,generators,metadata,front matter] categories: [content management] +keywords: [archetypes,generators,metadata,front matter] menu: docs: parent: content-management weight: 140 quicklinks: -toc: true weight: 140 +toc: true aliases: [/content/archetypes/] --- @@ -19,7 +19,7 @@ A content file consists of [front matter] and markup. The markup is typically ma The `hugo new content` command creates a new file in the `content` directory, using an archetype as a template. This is the default archetype: -{{< code-toggle file="archetypes/default.md" copy=false fm=true >}} +{{< code-toggle file=archetypes/default.md fm=true >}} title = '{{ replace .File.ContentBaseName `-` ` ` | title }}' date = '{{ .Date }}' draft = true @@ -27,13 +27,13 @@ draft = true When you create new content, Hugo evaluates the [template actions] within the archetype. For example: -```text +```sh hugo new content posts/my-first-post.md ``` With the default archetype shown above, Hugo creates this content file: -{{< code-toggle file="content/posts/my-first-post.md" copy=false fm=true >}} +{{< code-toggle file=content/posts/my-first-post.md fm=true >}} title = 'My First Post' date = '2023-08-24T11:49:46-07:00' draft = true @@ -53,7 +53,7 @@ Hugo looks for archetypes in the `archetypes` directory in the root of your proj For example, with this command: -```text +```sh hugo new content posts/my-first-post.md ``` @@ -75,7 +75,7 @@ Archetypes receive the following objects and values in [context]: - `.Date` - `.Type` - `.Site` (see [details](/variables/site/)) -- `.File` (see [details](/variables/files/)) +- `.File` (see [details](/variables/file/)) As shown above, the default archetype passes `.File.ContentBaseName` as the argument to the `replace` function when populating the title in front matter. @@ -85,8 +85,7 @@ Although typically used as a front matter template, you can also use an archetyp For example, in a documentation site you might have a section (content type) for functions. Every page within this section should follow the same format: a brief description, the function signature, examples, and notes. We can pre-populate the page to remind content authors of the standard format. - -{{< code file="archetypes/functions.md" copy=false >}} +{{< code file=archetypes/functions.md >}} --- date: '{{ .Date }}' draft: true @@ -125,17 +124,17 @@ Create an archetype for galleries: ```text archetypes/ ├── galleries/ -│ ├── images/ -│ │ └── .gitkeep -│ └── index.md <-- same format as default.md +│ ├── images/ +│ │ └── .gitkeep +│ └── index.md <-- same format as default.md └── default.md ``` Subdirectories within an archetype must contain at least one file. Without a file, Hugo will not create the subdirectory when you create new content. The name and size of the file are irrelevant. The example above includes a `.gitkeep` file, an empty file commonly used to preserve otherwise empty directories in a Git repository. - To create a new gallery: -```text + +```sh hugo new galleries/bryce-canyon ``` @@ -166,13 +165,13 @@ archetypes/ To create an article using the articles archetype: -```text +```sh hugo new content articles/something.md ``` To create an article using the tutorials archetype: -```text +```sh hugo new content --kind tutorials articles/something.md ``` diff --git a/docs/content/en/content-management/build-options.md b/docs/content/en/content-management/build-options.md index 378a31144..bc9d7ff49 100644 --- a/docs/content/en/content-management/build-options.md +++ b/docs/content/en/content-management/build-options.md @@ -1,102 +1,321 @@ --- title: Build options description: Build options help define how Hugo must treat a given page when building the site. +categories: [content management,fundamentals] keywords: [build,content,front matter, page resources] -categories: [fundamentals,content management] menu: docs: parent: content-management weight: 70 -toc: true weight: 70 +toc: true aliases: [/content/build-options/] --- -They are stored in a reserved front matter object named `_build` with the following defaults: +Build options are stored in a reserved front matter object named `_build` with these defaults: -{{< code-toggle >}} -_build: - render: always - list: always - publishResources: true +{{< code-toggle file=content/example/index.md fm=true >}} +[_build] +list = 'always' +publishResources = true +render = 'always' {{< /code-toggle >}} -#### render -If `always`, the page will be treated as a published page, holding its dedicated output files (`index.html`, etc...) and permalink. +list +: When to include the page within page collections. Specify one of: + + - `always` + : Include the page in _all_ page collections. For example, `site.RegularPages`, `.Pages`, etc. This is the default value. -Valid values are: + - `local` + : Include the page in _local_ page collections. For example, `.RegularPages`, `.Pages`, etc. Use this option to create fully navigable but headless content sections. - `never` - : The page will not be included in any page collection. - - `always (default)` - : The page will be rendered to disk and get a `RelPermalink` etc. - - `link` - : The page will be not be rendered to disk, but will get a `RelPermalink`. + : Do not include the page in _any_ page collection. -#### list +publishResources +: Applicable to [page bundles], determines whether to publish the associated [page resources]. Specify one of: -Valid values are: - - - `never` - : The page will not be included in any page collection. - - `always (default)` - : The page will be included in all page collections, e.g. `site.RegularPages`, `.Pages`. - - `local` - : The page will be included in any _local_ page collection, e.g. `.RegularPages`, `.Pages`. One use case for this would be to create fully navigable, but headless content sections. + - `true` + : Always publish resources. This is the default value. -#### publishResources + - `false` + : Only publish a resource when invoking its [`Permalink`], [`RelPermalink`], or [`Publish`] method within a template. -If set to `true` (default) the [Bundle's Resources](/content-management/page-bundles) will be published. -Setting this to `false` will still publish Resources on demand (when a resource's `.Permalink` or `.RelPermalink` is invoked from the templates) but will skip the others. +render +: When to render the page. Specify one of: + + - `always` + : Always render the page to disk. This is the default value. + + - `link` + : Do not render the page to disk, but include it in all page collections. + + - `never` + : Never render the page to disk, and exclude it from all page collections. + +[page bundles]: content-management/page-bundles +[page resources]: /content-management/page-resources +[`Permalink`]: /methods/resource/permalink +[`RelPermalink`]: /methods/resource/relpermalink +[`Publish`]: /methods/resource/publish {{% note %}} -Any page, regardless of their build options, will always be available using the [`.GetPage`](/functions/getpage) methods. +Any page, regardless of its build options, will always be available by using the [`.Page.GetPage`] or [`.Site.GetPage`] method. + +[`.Page.GetPage`]: /methods/page/getpage +[`.Site.GetPage`]: /methods/site/getpage {{% /note %}} -### Illustrative use cases +## Example -- headless page + +Create a unpublished page whose content and resources can be included in other pages. + +```text +content/ +├── headless/ +│ ├── a.jpg +│ ├── b.jpg +│ └── index.md <-- leaf bundle +└── _index.md <-- home page +``` + +Set the build options in front matter: + +{{< code-toggle file=content/headless/index.md fm=true >}} +title = 'Headless page' +[_build] + list = 'never' + publishResources = false + render = 'never' +{{< /code-toggle >}} + +To include the content and images on the home page: + +{{< code file=layouts/_default/home.html >}} +{{ with .Site.GetPage "/headless" }} + {{ .Content }} + {{ range .Resources.ByType "image" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} +{{ end }} +{{< /code >}} + +The published site will have this structure: + +```text +public/ +├── headless/ +│ ├── a.jpg +│ └── b.jpg +└── index.html +``` + +In the example above, note that: + +1. Hugo did not publish an HTML file for the page. +2. Despite setting `publishResources` to `false` in front matter, Hugo published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior. + +## Example -- headless section -#### Not publishing a page +Create a unpublished section whose content and resources can be included in other pages. -Project needs a "Who We Are" content file for front matter and body to be used by the homepage but nowhere else. +[branch bundle]: /content-management/page-bundles -{{< code-toggle file="content/who-we-are.md" fm=true copy=false >}} -title: Who we are -_build: - list: false - render: false +```text +content/ +├── headless/ +│ ├── note-1/ +│ │ ├── a.jpg +│ │ ├── b.jpg +│ │ └── index.md <-- leaf bundle +│ ├── note-2/ +│ │ ├── c.jpg +│ │ ├── d.jpg +│ │ └── index.md <-- leaf bundle +│ └── _index.md <-- branch bundle +└── _index.md <-- home page +``` + +Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages. + +{{< code-toggle file=content/headless/_index.md fm=true >}} +title = 'Headless section' +[[cascade]] +[cascade._build] + list = 'local' + publishResources = false + render = 'never' {{< /code-toggle >}} -{{< code file="layouts/index.html" copy=false >}} -<section id="who-we-are"> - {{ with site.GetPage "who-we-are" }} +In the front matter above, note that we have set `list` to `local` to include the descendant pages in local page collections. + +To include the content and images on the home page: + +{{< code file=layouts/_default/home.html >}} +{{ with .Site.GetPage "/headless" }} + {{ range .Pages }} {{ .Content }} + {{ range .Resources.ByType "image" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} {{ end }} -</section> +{{ end }} {{< /code >}} -#### Listing pages without publishing them +The published site will have this structure: + +```text +public/ +├── headless/ +│ ├── note-1/ +│ │ ├── a.jpg +│ │ └── b.jpg +│ └── note-2/ +│ ├── c.jpg +│ └── d.jpg +└── index.html +``` + +In the example above, note that: + +1. Hugo did not publish an HTML file for the page. +2. Despite setting `publishResources` to `false` in front matter, Hugo correctly published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior. + +## Example -- list without publishing -Website needs to showcase a few of the hundred "testimonials" available as content files without publishing any of them. +Publish a section page without publishing the descendant pages. For example, to create a glossary: -To avoid setting the build options on every testimonials, one can use [`cascade`](/content-management/front-matter#front-matter-cascade) on the testimonial section's content file. +```text +content/ +├── glossary/ +│ ├── _index.md +│ ├── bar.md +│ ├── baz.md +│ └── foo.md +└── _index.md +``` -{{< code-toggle >}} -title: Testimonials -_build: - render: true -cascade: - _build: - render: false - list: true # default +Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages. + +{{< code-toggle file=content/glossary/_index.md fm=true >}} +title = 'Glossary' +[_build] +render = 'always' +[[cascade]] +[cascade._build] + list = 'local' + publishResources = false + render = 'never' {{< /code-toggle >}} -{{< code file="layouts/_defaults/testimonials.html" copy=false >}} -<section id="testimonials"> - {{ range first 5 .Pages }} - <blockquote cite="{{ .Params.cite }}"> - {{ .Content }} - </blockquote> +To render the glossary: + +{{< code file=layouts/glossary/list.html >}} +<dl> + {{ range .Pages }} + <dt>{{ .Title }}</dt> + <dd>{{ .Content }}</dd> {{ end }} -</section> +</dl> {{< /code >}} + +The published site will have this structure: + +```text +public/ +├── glossary/ +│ └── index.html +└── index.html +``` + +## Example -- publish without listing + +Publish a section's descendant pages without publishing the section page itself. + +```text +content/ +├── books/ +│ ├── _index.md +│ ├── book-1.md +│ └── book-2.md +└── _index.md +``` + +Set the build options in front matter: + +{{< code-toggle file=content/books/_index.md >}} +title = 'Books' +[_build] +render = 'never' +list = 'never' +{{< /code-toggle >}} + +The published site will have this structure: + +```html +public/ +├── books/ +│ ├── book-1/ +│ │ └── index.html +│ └── book-2/ +│ └── index.html +└── index.html +``` + +## Example -- conditionally hide section + +Consider this example. A documentation site has a team of contributors with access to 20 custom shortcodes. Each shortcode takes several arguments, and requires documentation for the contributors to reference when using them. + +Instead of external documentation for the shortcodes, include an "internal" section that is hidden when building the production site. + +```text +content/ +├── internal/ +│ ├── shortcodes/ +│ │ ├── _index.md +│ │ ├── shortcode-1.md +│ │ └── shortcode-2.md +│ └── _index.md +├── reference/ +│ ├── _index.md +│ ├── reference-1.md +│ └── reference-2.md +├── tutorials/ +│ ├── _index.md +│ ├── tutorial-1.md +│ └── tutorial-2.md +└── _index.md +``` + +Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages, and use the `target` keyword to target the production environment. + +{{< code-toggle file=content/internal/_index.md >}} +title = 'Internal' +[[cascade]] +[cascade._build] +render = 'never' +list = 'never' +[cascade._target] +environment = 'production' +{{< /code-toggle >}} + +The production site will have this structure: + +```html +public/ +├── reference/ +│ ├── reference-1/ +│ │ └── index.html +│ ├── reference-2/ +│ │ └── index.html +│ └── index.html +├── tutorials/ +│ ├── tutorial-1/ +│ │ └── index.html +│ ├── tutorial-2/ +│ │ └── index.html +│ └── index.html +└── index.html +``` diff --git a/docs/content/en/content-management/comments.md b/docs/content/en/content-management/comments.md index 39663013b..9985dd1e6 100644 --- a/docs/content/en/content-management/comments.md +++ b/docs/content/en/content-management/comments.md @@ -1,14 +1,14 @@ --- title: Comments description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website. +categories: [content management] keywords: [sections,content,organization] -categories: [project organization] menu: docs: parent: content-management weight: 220 -toc: true weight: 220 +toc: true aliases: [/extras/comments/] --- diff --git a/docs/content/en/content-management/cross-references.md b/docs/content/en/content-management/cross-references.md index c989cc560..500e388a4 100644 --- a/docs/content/en/content-management/cross-references.md +++ b/docs/content/en/content-management/cross-references.md @@ -2,13 +2,13 @@ title: Links and cross references description: Shortcodes for creating links to documents. categories: [content management] -keywords: ["cross references","references", "anchors", "urls"] +keywords: [cross references,references,anchors,urls] menu: docs: parent: content-management weight: 170 -toc: true weight: 170 +toc: true aliases: [/extras/crossreferences/] --- @@ -35,7 +35,6 @@ The `ref` and `relref` shortcodes require a single parameter: the path to a cont The pages can be referenced as follows: - ```text {{</* ref "document2" */>}} // <- From pages/document1.md, relative path {{</* ref "document2#anchor" */>}} @@ -138,7 +137,7 @@ produces this HTML: ## Ref and RelRef Configuration -The behavior can, since Hugo 0.45, be configured in `hugo.toml`: +The behavior can be configured in `hugo.toml`: refLinksErrorLevel ("ERROR") : When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`). @@ -146,7 +145,6 @@ refLinksErrorLevel ("ERROR") refLinksNotFoundURL : URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is. - [lists]: /templates/lists/ [output formats]: /templates/output-formats/ [shortcode]: /content-management/shortcodes/ diff --git a/docs/content/en/content-management/diagrams.md b/docs/content/en/content-management/diagrams.md index c0b2349b0..17407098f 100644 --- a/docs/content/en/content-management/diagrams.md +++ b/docs/content/en/content-management/diagrams.md @@ -7,12 +7,12 @@ menu: docs: parent: content-management weight: 50 -toc: true weight: 50 +toc: true --- -{{< new-in "0.93.0" >}} +{{< new-in 0.93.0 >}} -## GoAT diagrams (Ascii) +## GoAT diagrams (ASCII) Hugo supports [GoAT](https://github.com/bep/goat) natively. This means that this code block: @@ -165,7 +165,6 @@ Created from <https://arthursonzogni.com/Diagon |