diff options
Diffstat (limited to 'docs/content/en/content-management')
28 files changed, 5192 insertions, 0 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 new file mode 100644 index 000000000..66af24681 --- /dev/null +++ b/docs/content/en/content-management/_index.md @@ -0,0 +1,16 @@ +--- +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 +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 new file mode 100644 index 000000000..94f038848 --- /dev/null +++ b/docs/content/en/content-management/archetypes.md @@ -0,0 +1,184 @@ +--- +title: Archetypes +description: An archetype is a template for new content. +categories: [content management] +keywords: [archetypes,generators,metadata,front matter] +menu: + docs: + parent: content-management + weight: 140 + quicklinks: +weight: 140 +toc: true +aliases: [/content/archetypes/] +--- + +## Overview + +A content file consists of [front matter] and markup. The markup is typically markdown, but Hugo also supports other [content formats]. Front matter can be TOML, YAML, or JSON. + +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 fm=true >}} +title = '{{ replace .File.ContentBaseName `-` ` ` | title }}' +date = '{{ .Date }}' +draft = true +{{< /code-toggle >}} + +When you create new content, Hugo evaluates the [template actions] within the archetype. For example: + +```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 fm=true >}} +title = 'My First Post' +date = '2023-08-24T11:49:46-07:00' +draft = true +{{< /code-toggle >}} + +You can create an archetype for one or more [content types]. For example, use one archetype for posts, and use the default archetype for everything else: + +```text +archetypes/ +├── default.md +└── posts.md +``` + +## Lookup order + +Hugo looks for archetypes in the `archetypes` directory in the root of your project, falling back to the `archetypes` directory in themes or installed modules. An archetype for a specific content type takes precedence over the default archetype. + +For example, with this command: + +```sh +hugo new content posts/my-first-post.md +``` + +The archetype lookup order is: + +1. archetypes/posts.md +1. archetypes/default.md +1. themes/my-theme/archetypes/posts.md +1. themes/my-theme/archetypes/default.md + +If none of these exists, Hugo uses a built-in default archetype. + +## Functions and context + +You can use any [template function] within an archetype. As shown above, the default archetype uses the [`replace`](/functions/strings/replace) function to replace hyphens with spaces when populating the title in front matter. + +Archetypes receive the following objects and values in [context]: + +- `.Date` +- `.Type` +- `.Site` (see [details](/variables/site/)) +- `.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. + +## Include content + +Although typically used as a front matter template, you can also use an archetype to populate content. + +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 >}} +--- +date: '{{ .Date }}' +draft: true +title: '{{ replace .File.ContentBaseName `-` ` ` | title }}' +--- + +A brief description of what the function does, using simple present tense in the third person singular form. For example: + +`someFunction` returns the string `s` repeated `n` times. + +## Signature + +```text +func someFunction(s string, n int) string +``` + +## Examples + +One or more practical examples, each within a fenced code block. + +## Notes + +Additional information to clarify as needed. +{{< /code >}} + +Although you can include [template actions] within the content body, remember that Hugo evaluates these once---at the time of content creation. In most cases, place template actions in a [template] where Hugo evaluates the actions every time you [build](/getting-started/glossary/#build) the site. + +## Leaf bundles + +You can also create archetypes for [leaf bundles](/getting-started/glossary/#leaf-bundle). + +For example, in a photography site you might have a section (content type) for galleries. Each gallery is leaf bundle with content and images. + +Create an archetype for galleries: + +```text +archetypes/ +├── galleries/ +│ ├── 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: + +```sh +hugo new galleries/bryce-canyon +``` + +This produces: + +```text +content/ +├── galleries/ +│ └── bryce-canyon/ +│ ├── images/ +│ │ └── .gitkeep +│ └── index.md +└── _index.md +``` + +## Use alternate archetype + +Use the `--kind` command line flag to specify an alternate archetype when creating content. + +For example, let's say your site has two sections: articles and tutorials. Create an archetype for each content type: + +```text +archetypes/ +├── articles.md +├── default.md +└── tutorials.md +``` + +To create an article using the articles archetype: + +```sh +hugo new content articles/something.md +``` + +To create an article using the tutorials archetype: + +```sh +hugo new content --kind tutorials articles/something.md +``` + +[content formats]: /getting-started/glossary/#content-format +[content types]: /getting-started/glossary/#content-type +[context]: /getting-started/glossary/#context +[front matter]: /getting-started/glossary/#front-matter +[template actions]: /getting-started/glossary/#template-action +[template]: /getting-started/glossary/#template +[template function]: /getting-started/glossary/#function diff --git a/docs/content/en/content-management/build-options.md b/docs/content/en/content-management/build-options.md new file mode 100644 index 000000000..bc9d7ff49 --- /dev/null +++ b/docs/content/en/content-management/build-options.md @@ -0,0 +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] +menu: + docs: + parent: content-management + weight: 70 +weight: 70 +toc: true +aliases: [/content/build-options/] +--- + +Build options are stored in a reserved front matter object named `_build` with these defaults: + +{{< code-toggle file=content/example/index.md fm=true >}} +[_build] +list = 'always' +publishResources = true +render = 'always' +{{< /code-toggle >}} + + +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. + + - `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` + : Do not include the page in _any_ page collection. + +publishResources +: Applicable to [page bundles], determines whether to publish the associated [page resources]. Specify one of: + + - `true` + : Always publish resources. This is the default value. + + - `false` + : Only publish a resource when invoking its [`Permalink`], [`RelPermalink`], or [`Publish`] method within a template. + +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 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 %}} + +## 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 + +Create a unpublished section whose content and resources can be included in other pages. + +[branch bundle]: /content-management/page-bundles + +```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 >}} + +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 }} +{{ end }} +{{< /code >}} + +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 + +Publish a section page without publishing the descendant pages. For example, to create a glossary: + +```text +content/ +├── glossary/ +│ ├── _index.md +│ ├── bar.md +│ ├── baz.md +│ └── foo.md +└── _index.md +``` + +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 >}} + +To render the glossary: + +{{< code file=layouts/glossary/list.html >}} +<dl> + {{ range .Pages }} + <dt>{{ .Title }}</dt> + <dd>{{ .Content }}</dd> + {{ end }} +</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 new file mode 100644 index 000000000..9985dd1e6 --- /dev/null +++ b/docs/content/en/content-management/comments.md @@ -0,0 +1,73 @@ +--- +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] +menu: + docs: + parent: content-management + weight: 220 +weight: 220 +toc: true +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. + +Your theme may already support Disqus, but if not, it is easy to add to your templates via [Hugo's built-in Disqus partial][disquspartial]. + +## Add Disqus + +Hugo comes with all the code you need to load Disqus into your templates. Before adding Disqus to your site, you'll need to [set up an account][disqussetup]. + +### Configure Disqus + +Disqus comments require you set a single value in your [site's configuration file][configuration] like so: + +{{< code-toggle file="hugo" >}} +[services.disqus] +shortname = 'your-disqus-shortname' +{{</ code-toggle >}} + +For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter] of a single content file: + +* `disqus_identifier` +* `disqus_title` +* `disqus_url` + +### Render Hugo's built-in Disqus partial template + +Disqus has its own [internal template](/templates/internal/#disqus) available, to render it add the following code where you want comments to appear: + +```go-html-template +{{ template "_internal/disqus.html" . }} +``` + +# |