diff options
Diffstat (limited to 'docs/content/en/content-management')
25 files changed, 4146 insertions, 0 deletions
diff --git a/docs/content/en/content-management/_index.md b/docs/content/en/content-management/_index.md new file mode 100644 index 000000000..28f2ecf82 --- /dev/null +++ b/docs/content/en/content-management/_index.md @@ -0,0 +1,20 @@ +--- +title: Content Management +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 +keywords: [source, organization] +categories: [content management] +weight: 01 #rem +draft: false +aliases: [/content/,/content/organization] +toc: false +--- + +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..354ef0fef --- /dev/null +++ b/docs/content/en/content-management/archetypes.md @@ -0,0 +1,97 @@ +--- +title: 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"] +menu: + docs: + parent: "content-management" + weight: 70 + quicklinks: +weight: 70 #rem +draft: false +aliases: [/content/archetypes/] +toc: true +--- + +## What are Archetypes? + +**Archetypes** are content template files in the [archetypes directory][] of your project that contain preconfigured [front matter][] and possibly also a content disposition for your website's [content types][]. These will be used when you run `hugo new`. + + +The `hugo new` uses the `content-section` to find the most suitable archetype template in your project. If your project does not contain any archetype files, it will also look in the theme. + +{{< code file="archetype-example.sh" >}} +hugo new posts/my-first-post.md +{{< /code >}} + +The above will create a new content file in `content/posts/my-first-post.md` using the first archetype file found of these: + +1. `archetypes/posts.md` +2. `archetypes/default.md` +3. `themes/my-theme/archetypes/posts.md` +4. `themes/my-theme/archetypes/default.md` + +The last two list items are only applicable if you use a theme and it uses the `my-theme` theme name as an example. + +## Create a New Archetype Template + +A fictional example for the section `newsletter` and the archetype file `archetypes/newsletter.md`. Create a new file in `archetypes/newsletter.md` and open it in a text editor. + +{{< code file="archetypes/newsletter.md" >}} +--- +title: "{{ replace .Name "-" " " | title }}" +date: {{ .Date }} +draft: true +--- + +**Insert Lead paragraph here.** + +## New Cool Posts + +{{ range first 10 ( where .Site.RegularPages "Type" "cool" ) }} +* {{ .Title }} +{{ end }} +{{< /code >}} + +When you create a new newsletter with: + +```bash +hugo new newsletter/the-latest-cool.stuff.md +``` + +It will create a new newsletter type of content file based on the archetype template. + +**Note:** the site will only be built if the `.Site` is in use in the archetype file, and this can be time consuming for big sites. + +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: + +```bash +archetypes +├── default.md +└── post-bundle + ├── bio.md + ├── images + │ └── featured.jpg + └── index.md +``` + +```bash +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 new file mode 100644 index 000000000..93da7c421 --- /dev/null +++ b/docs/content/en/content-management/build-options.md @@ -0,0 +1,119 @@ +--- +title: 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"] +menu: + docs: + parent: "content-management" + weight: 31 +weight: 31 #rem +draft: false +aliases: [/content/build-options/] +toc: true +--- + +They are stored in a reserved Front Matter object named `_build` with the following defaults: + +```yaml +_build: + render: always + list: always + publishResources: true +``` + +#### 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: + +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`. + +#### list + +Note that we extended this property from a boolean to an enum in Hugo 0.68.0. + +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`, `$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" >}} + +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. +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 %}} +Any page, regardless of their build options, will always be available using the [`.GetPage`]({{< relref "functions/GetPage" >}}) methods. +{{% /note %}} + +------ + +### 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 +# content/who-we-are.md` +title: Who we are +_build: + list: false + render: false +``` + +```go-html-template +{{/* layouts/index.html */}} +<section id="who-we-are"> +{{ with site.GetPage "who-we-are" }} + {{ .Content }} +{{ end }} +</section> +``` + +#### Listing pages without publishing them + +Website needs to showcase a few of the hundred "testimonials" available as content files without publishing any of them. + +To avoid setting the build options on every testimonials, one can use [`cascade`]({{< relref "/content-management/front-matter#front-matter-cascade" >}}) on the testimonial section's content file. + +```yaml +#content/testimonials/_index.md +title: Testimonials +# section build options: +_build: + render: true +# children build options with cascade +cascade: + _build: + render: false + list: true # default +``` + +```go-html-template +{{/* layouts/_defaults/testimonials.html */}} +<section id="testimonials"> +{{ range first 5 .Pages }} + <blockquote cite="{{ .Params.cite }}"> + {{ .Content }} + </blockquote> +{{ end }} +</section> diff --git a/docs/content/en/content-management/comments.md b/docs/content/en/content-management/comments.md new file mode 100644 index 000000000..b5357cba4 --- /dev/null +++ b/docs/content/en/content-management/comments.md @@ -0,0 +1,77 @@ +--- +title: 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 +lastmod: 2017-03-09 +keywords: [sections,content,organization] +categories: [project organization, fundamentals] +menu: + docs: + parent: "content-management" + weight: 140 +weight: 140 #rem +draft: false +aliases: [/extras/comments/] +toc: true +--- + +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 copy="false" >}} +disqusShortname = "yourdiscussshortname" +{{</ 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](https://gohugo.io/templates/internal/#disqus) available, to render it add the following code where you want comments to appear: + +``` +{{ template "_internal/disqus.html" . }} +``` + +## Comments Alternatives + +There are a few alternatives to commenting on static sites for those who do not want to use Disqus: + +* [Staticman](https://staticman.net/) +* [Talkyard](https://www.talkyard.io/blog-comments) (Open source, & serverless hosting) +* [IntenseDebate](https://intensedebate.com/) +* [Graph Comment][] +* [Muut](https://muut.com/) +* [Isso](https://posativ.org/isso/) (Self-hosted, Python) + * [Tutorial on Implementing Isso with Hugo][issotutorial] +* [Utterances](https://utteranc.es/) (Open source, GitHub comments widget built on GitHub issues) +* [Remark](https://github.com/umputun/remark) (Open source, Golang, Easy to run docker) +* [Commento](https://commento.io/) (Open Source, available as a service, local install, or docker image) +* [Hyvor Talk](https://talk.hyvor.com/) (Available as a service) + + +[configuration]: /getting-started/configuration/ +[disquspartial]: /templates/partials/#disqus +[disqussetup]: https://disqus.com/profile/signup/ +[forum]: https://discourse.gohugo.io +[front matter]: /content-management/front-matter/ +[Graph Comment]: https://graphcomment.com/ +[kaijuissue]: https://github.com/spf13/kaiju/issues/new +[issotutorial]: https://stiobhart.net/2017-02-24-isso-comments/ +[partials]: /templates/partials/ +[MongoDB]: https://www.mongodb.com/ +[tweet]: https://twitter.com/spf13 diff --git a/docs/content/en/content-management/cross-references.md b/docs/content/en/content-management/cross-references.md new file mode 100644 index 000000000..9580fd7e5 --- /dev/null +++ b/docs/content/en/content-management/cross-references.md @@ -0,0 +1,129 @@ +--- +title: 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/] +toc: true +--- + +The `ref` and `relref` shortcodes display the absolute and relative permalinks to a document, respectively. + +## Use `ref` and `relref` + +```go-html-template +{{</* ref "document" */>}} +{{</* ref "document#anchor" */>}} +{{</* ref "document.md" */>}} +{{</* ref "document.md#anchor" */>}} +{{</* ref "#anchor" */>}} +{{</* ref "/blog/my-post" */>}} +{{</* ref "/blog/my-post.md" */>}} +{{</* relref "document" */>}} +{{</* relref "document.md" */>}} +{{</* relref "#anchor" */>}} +{{</* relref "/blog/my-post.md" */>}} +``` + +To generate a hyperlink using `ref` or `relref` in markdown: + +```md +[About]({{</* ref "/page/about" */>}} "About Us") +``` + +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. + +Hugo emits an error or warning if a document cannot be uniquely resolved. The error behavior is configurable; see below. + +### Link to another language version + +To link to another language version of a document, use this syntax: + +```go-html-template +{{</* relref path="document.md" lang="ja" */>}} +``` + +### Get another Output Format + +To link to another Output Format of a document, use this syntax: + +```go-html-template +{{</* relref path="document.md" outputFormat="rss" */>}} +``` + +### Heading IDs + +When using Markdown document types, Hugo generates element IDs for every heading on a page. For example: + +```md +## Reference +``` + +produces this HTML: + +```html +<h2 id="reference">Reference</h2> +``` + +Get the permalink to a heading by appending the ID to the path when using the `ref` or `relref` shortcodes: + +```go-html-template +{{</* ref "document.md#reference" */>}} +{{</* relref "document.md#reference" */>}} +``` + +Generate a custom heading ID by including an attribute. For example: + +```md +## Reference A {#foo} +## Reference B {id="bar"} +``` + +produces this HTML: + +```html +<h2 id="foo">Reference A</h2> +<h2 id="bar">Reference B</h2> +``` + +Hugo will generate unique element IDs if the same heading appears more than once on a page. For example: + +```md +## Reference +## Reference +## Reference +``` + +produces this HTML: + +```html +<h2 id="reference">Reference</h2> +<h2 id="reference-1">Reference</h2> +<h2 id="reference-2">Reference</h2> +``` + +## Ref and RelRef Configuration + +The behavior can, since Hugo 0.45, be configured in `config.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`). + +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/ +[bfext]: /content-management/formats/#blackfriday-extensions diff --git a/docs/content/en/content-management/formats.md b/docs/content/en/content-management/formats.md new file mode 100644 index 000000000..5654be7f0 --- /dev/null +++ b/docs/content/en/content-management/formats.md @@ -0,0 +1,158 @@ +--- +title: Content Formats +linktitle: Content Formats +description: Both HTML and Markdown are supported content formats. +date: 2017-01-10 +publishdate: 2017-01-10 +lastmod: 2017-04-06 +categories: [content management] +keywords: [markdown,asciidoc,mmark,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/] +toc: true +--- + +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.: + +* Markdown converted to HTML +* [Shortcodes](/content-management/shortcodes/) processed +* Layout applied + +## List of content formats + +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" >}} | +| Blackfriday | blackfriday |Blackfriday will eventually be deprecated.| +|MMark|mmark|Mmark is deprecated and will be removed in a future release.| +|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](http://docutils.sourceforge.net/rst.html) installed.| +|Pandoc|pandoc, pdc|Needs [Pandoc](https://www.pandoc.org/) installed.| +|HTML|html, htm|To be treated as a content file, with layout, shortcodes etc., it must have front matter. If not, it will be copied as-is.| + +The `markup identifier` is fetched from either the `markup` variable in front matter or from the file extension. For markup-related configuration, see [Configure Markup](/getting-started/configuration-markup/). + + +## External Helpers + +Some of the formats in the table above need external helpers installed on your PC. For example, for AsciiDoc files, +Hugo will try to call the `asciidoctor` command. This means that you will have to install the associated +tool on your machine to be able to use these formats. + +Hugo passes reasonable default arguments to these external helpers by default: + +- `asciidoctor`: `--no-header-footer -` +- `rst2html`: `--leave-comments --initial-header-level=2` +- `pandoc`: `--mathjax` + +{{% warning "Performance of External Helpers" %}} +Because additional formats are external commands, generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome. +{{% /warning %}} + +### 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 +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. +[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. + +{{% note %}} +External `asciidoctor` command requires Hugo rendering to _disk_ to a specific destination directory. It is required to run Hugo with the command option `--destination`. +{{% /note %}} + +Some [Asciidoctor](https://asciidoctor.org/man/asciidoctor/) parameters can be customized in Hugo: + +Parameter | Comment +--- | --- +backend | Don't change this unless you know what you are doing. +doctype | Currently, the only document type supported in Hugo is `article`. +extensions | Possible extensions are `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, `asciidoctor-question`, `asciidoctor-rouge`. +attributes | Variables to be referenced in your AsciiDoc file. This is a list of variable name/value maps. See [Asciidoctor's attributes](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions). +noHeaderOrFooter | Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Don't change this unless you know what you are doing. +safeMode | Safe mode level `unsafe`, `safe`, `server` or `secure`. Don't change this unless you know what you are doing. +sectionNumbers | Auto-number section titles. +verbose | Verbosely print processing information and configuration file checks to stderr. +trace | Include backtrace information on errors. +failureLevel | The minimum logging level that triggers a non-zero exit code (failure). + +Hugo provides additional settings that don't map directly to Asciidoctor's CLI options: + +workingFolderCurrent +: Sets the working directory to be the same as that of the AsciiDoc file being processed, so that [include](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files) will work with relative paths. This setting uses the `asciidoctor` cli parameter `--base-dir` and attribute `outdir=`. For rendering diagrams with [asciidoctor-diagram](https://asciidoctor.org/docs/asciidoctor-diagram/), `workingFolderCurrent` must be set to `true`. + +preserveTOC +: By default, Hugo removes the table of contents generated by Asciidoctor and provides it through the built-in variable [`.TableOfContents`](/content-management/toc/) to enable further customization and better integration with the various Hugo themes. This option can be set to `true` to preserve Asciidoctor's TOC in the generated page. + +Below are all the AsciiDoc related settings in Hugo with their default values: + +{{< code-toggle config="markup.asciidocExt" />}} + +Notice that for security concerns only extensions that do not have path separators (either `\`, `/` or `.`) are allowed. That means that extensions can only be invoked if they are in one's ruby's `$LOAD_PATH` (ie. most likely, the extension has been installed by the user). Any extension declared relative to the website's path will not be accepted. + +Example of how to set extensions and attributes: + +``` +[markup.asciidocExt] + extensions = ["asciidoctor-html5s", "asciidoctor-diagram"] + workingFolderCurrent = true + [markup.asciidocExt.attributes] + my-base-url = "https://example.com/" + 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 +parameters. Run Hugo with `-v`. You will get an output like + +``` +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 -] ... +``` + +## Learn Markdown + +Markdown syntax is simple enough to learn in a single sitting. The following are excellent resources to get you up and running: + +* [Daring Fireball: Markdown, John Gruber (Creator of Markdown)][fireball] +* [Markdown Cheatsheet, Adam Pritchard][mdcheatsheet] +* [Markdown Tutorial (Interactive), Garen Torikian][mdtutorial] |