diff options
Diffstat (limited to 'docs/content/en/content-management')
24 files changed, 332 insertions, 406 deletions
diff --git a/docs/content/en/content-management/_index.md b/docs/content/en/content-management/_index.md index 28f2ecf82..7cb6357c6 100644 --- a/docs/content/en/content-management/_index.md +++ b/docs/content/en/content-management/_index.md @@ -1,20 +1,16 @@ --- title: Content Management -linktitle: Content Management Overview +linkTitle: Content Management Overview description: Hugo makes managing large static sites easy with support for archetypes, content types, menus, cross references, summaries, and more. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 menu: docs: - parent: "content-management" - weight: 1 + parent: content-management + weight: 10 keywords: [source, organization] categories: [content management] -weight: 01 #rem -draft: false -aliases: [/content/,/content/organization] toc: false +weight: 10 +aliases: [/content/,/content/organization] --- A static site generator needs to extend beyond front matter and a couple of templates to be both scalable and *manageable*. Hugo was designed with not only developers in mind, but also content managers and authors. diff --git a/docs/content/en/content-management/archetypes.md b/docs/content/en/content-management/archetypes.md index 354ef0fef..31e229838 100644 --- a/docs/content/en/content-management/archetypes.md +++ b/docs/content/en/content-management/archetypes.md @@ -1,20 +1,17 @@ --- title: Archetypes -linktitle: Archetypes +linkTitle: Archetypes description: Archetypes are templates used when creating new content. -date: 2017-02-01 -publishdate: 2017-02-01 keywords: [archetypes,generators,metadata,front matter] -categories: ["content management"] +categories: [content management] menu: docs: - parent: "content-management" - weight: 70 + parent: content-management + weight: 140 quicklinks: -weight: 70 #rem -draft: false -aliases: [/content/archetypes/] toc: true +weight: 140 +aliases: [/content/archetypes/] --- ## What are Archetypes? @@ -69,7 +66,6 @@ It will create a new newsletter type of content file based on the archetype temp The above _newsletter type archetype_ illustrates the possibilities: The full Hugo `.Site` and all of Hugo's template funcs can be used in the archetype file. - ## Directory based archetypes Since Hugo `0.49` you can use complete directories as archetype templates. Given this archetype directory: @@ -90,8 +86,6 @@ hugo new --kind post-bundle posts/my-post Will create a new folder in `/content/posts/my-post` with the same set of files as in the `post-bundle` archetypes folder. All content files (`index.md` etc.) can contain template logic, and will receive the correct `.Site` for the content's language. - - [archetypes directory]: /getting-started/directory-structure/ [content types]: /content-management/types/ [front matter]: /content-management/front-matter/ diff --git a/docs/content/en/content-management/build-options.md b/docs/content/en/content-management/build-options.md index 7bbb772df..f798754f1 100644 --- a/docs/content/en/content-management/build-options.md +++ b/docs/content/en/content-management/build-options.md @@ -1,19 +1,16 @@ --- title: Build Options -linktitle: Build Options +linkTitle: Build Options description: Build options help define how Hugo must treat a given page when building the site. -date: 2020-03-02 -publishdate: 2020-03-02 keywords: [build,content,front matter, page resources] -categories: ["content management"] +categories: [content management] menu: docs: - parent: "content-management" - weight: 31 -weight: 31 #rem -draft: false -aliases: [/content/build-options/] + parent: content-management + weight: 70 toc: true +weight: 70 +aliases: [/content/build-options/] --- They are stored in a reserved Front Matter object named `_build` with the following defaults: @@ -26,9 +23,10 @@ _build: {{< /code-toggle >}} #### render + If `always`, the page will be treated as a published page, holding its dedicated output files (`index.html`, etc...) and permalink. -{{< new-in "0.76.0" >}} We extended this property from a boolean to an enum in Hugo 0.76.0. Valid values are: +We extended this property from a boolean to an enum in Hugo 0.76.0. Valid values are: never : The page will not be included in any page collection. @@ -52,13 +50,13 @@ always (default) : The page will be included in all page collections, e.g. `site.RegularPages`, `$page.Pages`. local -: The page will be included in any _local_ page collection, e.g. `$page.RegularPages`, `$page.Pages`. One use case for this would be to create fully navigable, but headless content sections. {{< new-in "0.68.0" >}} +: The page will be included in any _local_ page collection, e.g. `$page.RegularPages`, `$page.Pages`. One use case for this would be to create fully navigable, but headless content sections. If true, the page will be treated as part of the project's collections and, when appropriate, returned by Hugo's listing methods (`.Pages`, `.RegularPages` etc...). #### publishResources -If set to true the [Bundle's Resources]({{< relref "content-management/page-bundles" >}}) will be published. +If set to true the [Bundle's Resources]({{< relref "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. {{% note %}} @@ -70,6 +68,7 @@ Any page, regardless of their build options, will always be available using the ### Illustrative use cases #### Not publishing a page + Project needs a "Who We Are" content file for Front Matter and body to be used by the homepage but nowhere else. ```yaml diff --git a/docs/content/en/content-management/comments.md b/docs/content/en/content-management/comments.md index 5c604fdeb..bb6a8d6ce 100644 --- a/docs/content/en/content-management/comments.md +++ b/docs/content/en/content-management/comments.md @@ -1,19 +1,16 @@ --- title: Comments -linktitle: Comments +linkTitle: 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. -date: 2017-02-01 -publishdate: 2017-02-01 keywords: [sections,content,organization] categories: [project organization, fundamentals] menu: docs: - parent: "content-management" - weight: 140 -weight: 140 #rem -draft: false -aliases: [/extras/comments/] + parent: content-management + weight: 220 toc: true +weight: 220 +aliases: [/extras/comments/] --- Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to websites via JavaScript. @@ -42,7 +39,7 @@ For many websites, this is enough configuration. However, you also have the opti Disqus has its own [internal template](https://gohugo.io/templates/internal/#disqus) available, to render it add the following code where you want comments to appear: -``` +```go-html-template {{ template "_internal/disqus.html" . }} ``` @@ -55,9 +52,10 @@ These are some alternatives to Disqus: * [Graph Comment](https://graphcomment.com/) * [Hyvor Talk](https://talk.hyvor.com/) (Available as a service) * [IntenseDebate](https://intensedebate.com/) -* [Isso](https://posativ.org/isso/) (Self-hosted, Python) ([tutorial][issotutorial]) +* [Isso](https://isso-comments.de/) (Self-hosted, Python) ([tutorial][issotutorial]) * [Muut](https://muut.com/) * [Remark42](https://remark42.com/) (Open source, Golang, Easy to run docker) +* [ReplyBox](https://getreplybox.com/) * [Staticman](https://staticman.net/) * [Talkyard](https://blog-comments.talkyard.io/) (Open source, & serverless hosting) * [Utterances](https://utteranc.es/) (Open source, GitHub comments widget built on GitHub issues) diff --git a/docs/content/en/content-management/cross-references.md b/docs/content/en/content-management/cross-references.md index b5dd8a4c3..00fb2d973 100644 --- a/docs/content/en/content-management/cross-references.md +++ b/docs/content/en/content-management/cross-references.md @@ -1,31 +1,49 @@ --- title: Links and Cross References +linkTitle: Links and Cross References description: Shortcodes for creating links to documents. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-03-31 categories: [content management] keywords: ["cross references","references", "anchors", "urls"] menu: docs: - parent: "content-management" - weight: 100 -weight: 100 #rem -aliases: [/extras/crossreferences/] + parent: content-management + weight: 170 toc: true +weight: 170 +aliases: [/extras/crossreferences/] --- The `ref` and `relref` shortcodes display the absolute and relative permalinks to a document, respectively. -## Use `ref` and `relref` +## Use of `ref` and `relref` -```go-html-template -{{</* ref "document" */>}} -{{</* ref "document#anchor" */>}} -{{</* ref "document.md" */>}} -{{</* ref "document.md#anchor" */>}} -{{</* ref "#anchor" */>}} -{{</* ref "/blog/my-post" */>}} +The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor. Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site. + +``` +. +└── content + ├── about + | ├── _index.md + | └── credits.md + ├── pages + | ├── document1.md + | └── document2.md // has anchor #anchor + ├── products + | └── index.md + └── blog + └── my-post.md +``` + +The pages can be referenced as follows: + + +```text +{{</* ref "document2" */>}} // <- From pages/document1.md, relative path +{{</* ref "document2#anchor" */>}} +{{</* ref "document2.md" */>}} +{{</* ref "document2.md#anchor" */>}} +{{</* ref "#anchor" */>}} // <- From pages/document2.md +{{</* ref "/blog/my-post" */>}} // <- From anywhere, absolute path {{</* ref "/blog/my-post.md" */>}} {{</* relref "document" */>}} {{</* relref "document.md" */>}} @@ -33,15 +51,22 @@ The `ref` and `relref` shortcodes display the absolute and relative permalinks t {{</* relref "/blog/my-post.md" */>}} ``` -To generate a hyperlink using `ref` or `relref` in markdown: +index.md can be reference either by its path or by its containing folder without the ending `/`. \_index.md can be referenced only by its containing folder: -```md -[About]({{</* ref "/page/about" */>}} "About Us") +```text +{{</* ref "/about" */>}} // <- References /about/_index.md +{{</* ref "/about/_index" */>}} // Raises REF_NOT_FOUND error +{{</* ref "/about/credits.md" */>}} // <- References /about/credits.md + +{{</* ref "/products" */>}} // <- References /products/index.md +{{</* ref "/products/index" */>}} // <- References /products/index.md ``` -The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor. +To generate a hyperlink using `ref` or `relref` in markdown: -**Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site. +```text +[About]({{</* ref "/about" */>}} "About Us") +``` Hugo emits an error or warning if a document cannot be uniquely resolved. The error behavior is configurable; see below. @@ -116,7 +141,7 @@ produces this HTML: The behavior can, since Hugo 0.45, be configured in `config.toml`: -refLinksErrorLevel ("ERROR") +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`). refLinksNotFoundURL diff --git a/docs/content/en/content-management/diagrams.md b/docs/content/en/content-management/diagrams.md index 243a70fd4..c95548249 100644 --- a/docs/content/en/content-management/diagrams.md +++ b/docs/content/en/content-management/diagrams.md @@ -1,25 +1,23 @@ --- title: Diagrams -date: 2022-02-20 +LinkTitle: Diagrams +description: Use fenced code blocks and markdown render hooks to display diagrams. categories: [content management] keywords: [diagrams,drawing] menu: docs: - parent: "content-management" - weight: 22 -weight: 22 + parent: content-management + weight: 50 toc: true +weight: 50 --- - - {{< new-in "0.93.0" >}} - ## GoAT Diagrams (Ascii) -Hugo! supports [GoAT](https://github.com/bep/goat) natively. This means that this code block: +Hugo supports [GoAT](https://github.com/bep/goat) natively. This means that this code block: -```` +````txt ```goat . . . .--- 1 .-- 1 / 1 / \ | | .---+ .-+ + @@ -45,14 +43,9 @@ Will be rendered as: 1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4 ``` - - - - ## Mermaid Diagrams -Hugo currently does not provide default templates for Mermaid diagrams. But you can easily add your own. One way to do it would be to create ` layouts/_default/_markup/render-codeblock-mermaid.html`: - +Hugo currently does not provide default templates for Mermaid diagrams. But you can easily add your own. One way to do it would be to create `layouts/_default/_markup/render-codeblock-mermaid.html`: ```go-html-template <div class="mermaid"> @@ -61,7 +54,7 @@ Hugo currently does not provide default templates for Mermaid diagrams. But you {{ .Page.Store.Set "hasMermaid" true }} ``` -And then include this snippet at the bottom of the content template (below `.Content`): +And then include this snippet at the bottom of the content template (**Note**: below `.Content` as the render hook is not processed until `.Content` is executed): ```go-html-template {{ if .Page.Store.Get "hasMermaid" }} @@ -88,8 +81,6 @@ sequenceDiagram Bob-->>John: Jolly good! ``` - - ## Goat Ascii Diagram Examples ### Graphics @@ -160,7 +151,7 @@ sequenceDiagram ### File tree -Created from https://arthursonzogni.com/Diagon/#Tree +Created from <https://arthursonzogni.com/Diagon/#Tree> ```goat { width=300 color="orange" } ───Linux─┬─Android @@ -176,7 +167,7 @@ Created from https://arthursonzogni.com/Diagon/#Tree ### Sequence Diagram -https://arthursonzogni.com/Diagon/#Sequence +<https://arthursonzogni.com/Diagon/#Sequence> ```goat { class="w-40" } ┌─────┐ ┌───┐ @@ -197,7 +188,7 @@ https://arthursonzogni.com/Diagon/#Sequence ### Flowchart -https://arthursonzogni.com/Diagon/#Flowchart +<https://arthursonzogni.com/Diagon/#Flowchart> ```goat _________________ @@ -243,7 +234,7 @@ https://arthursonzogni.com/Diagon/#Flowchart ### Table -https://arthursonzogni.com/Diagon/#Table +<https://arthursonzogni.com/Diagon/#Table> ```goat { class="w-80 dark-blue" } ┌────────────────────────────────────────────────┐ @@ -272,6 +263,3 @@ https://arthursonzogni.com/Diagon/#Table │LITERAL = """" character { character } """" .│ └────────────────────────────────────────────────┘ ``` - - - diff --git a/docs/content/en/content-management/formats.md b/docs/content/en/content-management/formats.md index 303bb4596..a98898821 100644 --- a/docs/content/en/content-management/formats.md +++ b/docs/content/en/content-management/formats.md @@ -1,19 +1,16 @@ --- title: Content Formats -linktitle: Content Formats +linkTitle: Content Formats description: Both HTML and Markdown are supported content formats. -date: 2017-01-10 -publishdate: 2017-01-10 categories: [content management] keywords: [markdown,asciidoc,pandoc,content format] menu: docs: - parent: "content-management" - weight: 20 -weight: 20 #rem -draft: false -aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-formats/] + parent: content-management + weight: 40 toc: true +weight: 40 +aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-formats/] --- You can put any file type into your `/content` directories, but Hugo uses the `markup` front matter value if set or the file extension (see `Markup identifiers` in the table below) to determine if the markup needs to be processed, e.g.: @@ -28,7 +25,7 @@ The current list of content formats in Hugo: | Name | Markup identifiers | Comment | | ------------- | ------------- |-------------| -| Goldmark | md, markdown, goldmark |Note that you can set the default handler of `md` and `markdown` to something else, see [Configure Markup](/getting-started/configuration-markup/).{{< new-in "0.60.0" >}} | +| Goldmark | md, 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.| @@ -55,13 +52,13 @@ Because additional formats are external commands, generation performance will re ### External Helper AsciiDoc -[AsciiDoc](https://github.com/asciidoc/asciidoc) implementation EOLs in Jan 2020 and is no longer supported. -AsciiDoc development is being continued under [Asciidoctor](https://github.com/asciidoctor). The format AsciiDoc +[AsciiDoc](https://github.com/asciidoc/asciidoc) implementation EOLs in Jan 2020 and is no longer supported. +AsciiDoc development is being continued under [Asciidoctor](https://github.com/asciidoctor). The format AsciiDoc remains of course. Please continue with the implementation Asciidoctor. ### External Helper Asciidoctor -The Asciidoctor community offers a wide set of tools for the AsciiDoc format that can be installed additionally to Hugo. +The Asciidoctor community offers a wide set of tools for the AsciiDoc format that can be installed additionally to Hugo. [See the Asciidoctor docs for installation instructions](https://asciidoctor.org/docs/install-toolchain/). Make sure that also all optional extensions like `asciidoctor-diagram` or `asciidoctor-html5s` are installed if required. @@ -100,7 +97,7 @@ Notice that for security concerns only extensions that do not have path separato Example of how to set extensions and attributes: -``` +```yml [markup.asciidocExt] extensions = ["asciidoctor-html5s", "asciidoctor-diagram"] workingFolderCurrent = true @@ -109,10 +106,10 @@ Example of how to set extensions and attributes: my-attribute-name = "my value" ``` -In a complex Asciidoctor environment it is sometimes helpful to debug the exact call to your external helper with all +In a complex Asciidoctor environment it is sometimes helpful to debug the exact call to your external helper with all parameters. Run Hugo with `-v`. You will get an output like -``` +```txt INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ... ``` diff --git a/docs/content/en/content-management/front-matter.md b/docs/content/en/content-management/front-matter.md index 0d8c2e3a6..71e6e36ea 100644 --- a/docs/content/en/content-management/front-matter.md +++ b/docs/content/en/content-management/front-matter.md @@ -1,20 +1,17 @@ --- title: Front Matter -linktitle: +linkTitle: Front Matter description: Hugo allows you to add front matter in yaml, toml, or json to your content files. -date: 2017-01-09 -publishdate: 2017-01-09 lastmod: 2017-02-24 categories: [content management] keywords: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"] menu: docs: - parent: "content-management" - weight: 30 -weight: 30 #rem -draft: false -aliases: [/content/front-matter/] + parent: content-management + weight: 60 toc: true +weight: 60 +aliases: [/content/front-matter/] --- **Front matter** allows you to keep metadata attached to an instance of a [content type][]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength. @@ -68,7 +65,7 @@ cascade : a map of Front Matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See [Front Matter Cascade](#front-matter-cascade) for details. date -: the datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behaviour is configurable. +: the datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behavior is configurable. description : the description for the content. @@ -137,7 +134,7 @@ weight : used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first. If set, weights should be non-zero, as 0 is interpreted as an *unset* weight. \<taxonomies\> -: field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. _Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables._ +: field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. *Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables.* {{% note "Hugo's Default URL Destinations" %}} If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site `config` file](/content-management/urls/#permalinks), Hugo will use the filename of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors. @@ -160,9 +157,7 @@ Any node or section can pass down to descendants a set of Front Matter values as ### Target Specific Pages -{{< new-in "0.76.0" >}} - -Since Hugo 0.76 the `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets. +The `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets. {{< code-toggle copy="false" >}} title ="Blog" @@ -181,7 +176,7 @@ kind="section" Keywords available for `_target`: path -: A [Glob](https://github.com/gobwas/glob) pattern matching the content path below /content. Expects Unix-styled slashes. Note that this is the virtual path, so it starts at the mount root. The matching support double- |