diff options
Diffstat (limited to 'content/en/getting-started')
| -rw-r--r-- | content/en/getting-started/_index.md | 4 | ||||
| -rw-r--r-- | content/en/getting-started/configuration-markup.md | 282 | ||||
| -rw-r--r-- | content/en/getting-started/configuration.md | 243 | ||||
| -rw-r--r-- | content/en/getting-started/directory-structure.md | 57 | ||||
| -rw-r--r-- | content/en/getting-started/external-learning-resources/build-websites-with-hugo.png | bin | 0 -> 18058 bytes | |||
| -rw-r--r-- | content/en/getting-started/external-learning-resources/hia.jpg | bin | 66768 -> 0 bytes | |||
| -rw-r--r-- | content/en/getting-started/external-learning-resources/hugo-in-action.png | bin | 0 -> 22891 bytes | |||
| -rw-r--r-- | content/en/getting-started/external-learning-resources/index.md | 75 | ||||
| -rw-r--r-- | content/en/getting-started/glossary.md | 138 | ||||
| -rw-r--r-- | content/en/getting-started/quick-start.md | 12 | ||||
| -rw-r--r-- | content/en/getting-started/usage.md | 14 |
11 files changed, 617 insertions, 208 deletions
diff --git a/content/en/getting-started/_index.md b/content/en/getting-started/_index.md index 780b96a62..1648f0224 100644 --- a/content/en/getting-started/_index.md +++ b/content/en/getting-started/_index.md @@ -1,12 +1,12 @@ --- title: Getting started -linkTitle: Overview +linkTitle: In this section description: Quick start and guides for installing Hugo on your preferred operating system. categories: [] keywords: [] menu: docs: - identifier: getting-started-overview + identifier: getting-started-in-this-section parent: getting-started weight: 10 weight: 10 diff --git a/content/en/getting-started/configuration-markup.md b/content/en/getting-started/configuration-markup.md index 607301d3a..ab3dfa221 100644 --- a/content/en/getting-started/configuration-markup.md +++ b/content/en/getting-started/configuration-markup.md @@ -2,7 +2,7 @@ title: Configure markup description: Configure rendering of markup to HTML. categories: [getting started,fundamentals] -keywords: [configuration,highlighting] +keywords: [markup,markdown,goldmark,asciidoc,asciidoctor,highlighting] menu: docs: parent: getting-started @@ -14,16 +14,16 @@ toc: true ## Default handler -By default, Hugo uses [Goldmark] to render markdown to HTML. +Hugo uses [Goldmark] to render Markdown to HTML. {{< code-toggle file=hugo >}} [markup] defaultMarkdownHandler = 'goldmark' {{< /code-toggle >}} -Files with the `.md` or `.markdown` extension are processed as markdown, provided that you have not specified a different [content format] using the `markup` field in front matter. +Files with the `.md` or `.markdown` extension are processed as Markdown, provided that you have not specified a different [content format] using the `markup` field in front matter. -To use a different renderer for markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your site configuration. +To use a different renderer for Markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your site configuration. defaultMarkdownHandler|Description :--|:-- @@ -33,41 +33,86 @@ defaultMarkdownHandler|Description `pandoc`|[Pandoc] `rst`|[reStructuredText] -To use Asciidoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy]. +To use AsciiDoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy]. {{% note %}} -Unless you need a unique capability provided by one of the alternate markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the [CommonMark] specification, and is compatible with [GitHub Flavored Markdown] (GFM). +Unless you need a unique capability provided by one of the alternate Markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the [CommonMark] specification, and is compatible with [GitHub Flavored Markdown] (GFM). [commonmark]: https://spec.commonmark.org/0.30/ [github flavored markdown]: https://github.github.com/gfm/ {{% /note %}} [asciidoc]: https://asciidoc.org/ -[content format]: /content-management/formats/#list-of-content-formats +[content format]: /content-management/formats/#formats [emacs org mode]: https://orgmode.org/ [goldmark]: https://github.com/yuin/goldmark/ [pandoc]: https://pandoc.org/ [restructuredtext]: https://docutils.sourceforge.io/rst.html -[security policy]: /about/security-model/#security-policy +[security policy]: /about/security/#security-policy ## Goldmark -This is the default configuration for the Goldmark markdown renderer: +This is the default configuration for the Goldmark Markdown renderer: {{< code-toggle config=markup.goldmark />}} -For details on the extensions, refer to the [Goldmark documentation](https://github.com/yuin/goldmark/#built-in-extensions). +### Goldmark extensions + +The extensions below, excluding Extras and Passthrough, are enabled by default. + +Extension|Documentation|Enabled +:--|:--|:-: +cjk|[Goldmark Extensions: CJK]|:heavy_check_mark: +definitionList|[PHP Markdown Extra: Definition lists]|:heavy_check_mark: +extras|[Hugo Goldmark Extensions: Extras]| +footnote|[PHP Markdown Extra: Footnotes]|:heavy_check_mark: +linkify|[GitHub Flavored Markdown: Autolinks]|:heavy_check_mark: +passthrough|[Hugo Goldmark Extensions: Passthrough]| +strikethrough|[GitHub Flavored Markdown: Strikethrough]|:heavy_check_mark: +table|[GitHub Flavored Markdown: Tables]|:heavy_check_mark: +taskList|[GitHub Flavored Markdown: Task list items]|:heavy_check_mark: +typographer|[Goldmark Extensions: Typographer]|:heavy_check_mark: + +[GitHub Flavored Markdown: Autolinks]: https://github.github.com/gfm/#autolinks-extension- +[GitHub Flavored Markdown: Strikethrough]: https://github.github.com/gfm/#strikethrough-extension- +[GitHub Flavored Markdown: Tables]: https://github.github.com/gfm/#tables-extension- +[GitHub Flavored Markdown: Task list items]: https://github.github.com/gfm/#task-list-items-extension- +[Goldmark Extensions: CJK]: https://github.com/yuin/goldmark?tab=readme-ov-file#cjk-extension +[Goldmark Extensions: Typographer]: https://github.com/yuin/goldmark?tab=readme-ov-file#typographer-extension +[Hugo Goldmark Extensions: Extras]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#extras-extension +[Hugo Goldmark Extensions: Passthrough]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#passthrough-extension +[PHP Markdown Extra: Definition lists]: https://michelf.ca/projects/php-markdown/extra/#def-list +[PHP Markdown Extra: Footnotes]: https://michelf.ca/projects/php-markdown/extra/#footnotes + +#### Extras extension + +{{< new-in 0.126.0 >}} + +Configure the extras extension to enable [inserted text], [mark text], [subscript], and [superscript] elements in Markdown. + +Element|Markdown|Rendered +:--|:--|:-- +Inserted text|`++foo++`|`<ins>foo</ins>` +Mark text|`==bar==`|`<mark>bar</mark>` +Subscript|`H~2~O`|`H<sub>2</sub>O` +Superscript|`1^st^`|`1<sup>st</sup>` + +[inserted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins +[mark text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark +[subscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub +[superscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup + +#### Passthrough extension + +{{< new-in 0.122.0 >}} -Some settings explained: +Enable the passthrough extension to include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax. See [mathematics in Markdown] for details. -hardWraps -: By default, Goldmark ignores newlines within a paragraph. Set to `true` to render newlines as `<br>` elements. +[mathematics in Markdown]: content-management/mathematics/ -unsafe -: By default, Goldmark does not render raw HTML and potentially dangerous links. If you have lots of inline HTML and/or JavaScript, you may need to turn this on. +#### Typographer extension -typographer -: The typographer extension replaces certain character combinations with HTML entities as specified below: +The Typographer extension replaces certain character combinations with HTML entities as specified below: Markdown|Replaced by|Description :--|:--|:-- @@ -82,104 +127,164 @@ Markdown|Replaced by|Description `”`|`”`|right double quote `’`|`’`|right single quote -attribute -: Enable custom attribute support for titles and blocks by adding attribute lists inside single curly brackets (`{.myclass class="class1 class2" }`) and placing it _after the Markdown element it decorates_, on the same line for titles and on a new line directly below for blocks. +### Goldmark settings explained -Hugo supports adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc. +Most of the Goldmark settings above are self-explanatory, but some require explanation. -A blockquote with a CSS class: +###### duplicateResourceFiles -```md -> foo -> bar -{.myclass} -``` +{{< new-in 0.123.0 >}} -There are some current limitations: For tables you can currently only apply it to the full table, and for lists the `ul`/`ol`-nodes only, e.g.: - -```md -* Fruit - * Apple - * Orange - * Banana - {.fruits} -* Dairy - * Milk - * Cheese - {.dairies} -{.list} -``` +(`bool`) If `true`, shared page resources on multilingual single-host sites will be duplicated for each language. See [multilingual page resources] for details. Default is `false`. -Note that attributes in [code fences](/content-management/syntax-highlighting/#highlighting-in-code-fences) must come after the opening tag, with any other highlighting processing instruction, e.g.: +[multilingual page resources]: /content-management/page-resources/#multilingual -````txt -```go {.myclass linenos=table,hl_lines=[8,"15-17"],linenostart=199} -// ... code -``` -```` +{{% note %}} +With multilingual single-host sites, setting this parameter to `false` will enable Hugo's [embedded link render hook] and [embedded image render hook]. This is the default configuration for multilingual single-host sites. + +[embedded image render hook]: /render-hooks/images/#default +[embedded link render hook]: /render-hooks/links/#default +{{% /note %}} + +###### parser.wrapStandAloneImageWithinParagraph + +(`bool`) If `true`, image elements without adjacent content will be wrapped within a `p` element when rendered. This is the default Markdown behavior. Set to `false` when using an [image render hook] to render standalone images as `figure` elements. Default is `true`. + +[image render hook]: /render-hooks/images/ + +###### parser.autoHeadingIDType + +(`string`) The strategy used to automatically generate heading `id` attributes, one of `github`, `github-ascii` or `blackfriday`. + +- `github` produces GitHub-compatible `id` attributes +- `github-ascii` drops any non-ASCII characters after accent normalization +- `blackfriday` produces `id` attributes compatible with the Blackfriday Markdown renderer -autoHeadingIDType ("github") -: The strategy used for creating auto IDs (anchor names). Available types are `github`, `github-ascii` and `blackfriday`. `github` produces GitHub-compatible IDs, `github-ascii` will drop any non-ASCII characters after accent normalization, and `blackfriday` will make the IDs compatible with Blackfriday, the default Markdown engine before Hugo 0.60. Note that if Goldmark is your default Markdown engine, this is also the strategy used in the [anchorize](/functions/urls/anchorize) template func. +This is also the strategy used by the [anchorize](/functions/urls/anchorize) template function. Default is `github`. -## Asciidoc +###### parser.attribute.block -This is the default configuration for the AsciiDoc markdown renderer: +(`bool`) If `true`, enables [Markdown attributes] for block elements. Default is `false`. + +[Markdown attributes]: /content-management/markdown-attributes/ + +###### parser.attribute.title + +(`bool`) If `true`, enables [Markdown attributes] for headings. Default is `true`. + +###### renderHooks.image.enableDefault + +{{< new-in 0.123.0 >}} + +(`bool`) If `true`, enables Hugo's [embedded image render hook]. Default is `false`. + +[embedded image render hook]: /render-hooks/images/#default + +{{% note %}} +The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. + +[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles +{{% /note %}} + +###### renderHooks.link.enableDefault + +{{< new-in 0.123.0 >}} + +(`bool`) If `true`, enables Hugo's [embedded link render hook]. Default is `false`. + +[embedded link render hook]: /render-hooks/links/#default + +{{% note %}} +The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. + +[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles +{{% /note %}} + +###### renderer.hardWraps + +(`bool`) If `true`, Goldmark replaces newline characters within a paragraph with `br` elements. Default is `false`. + +###### renderer.unsafe + +(`bool`) If `true`, Goldmark renders raw HTML mixed within the Markdown. This is unsafe unless the content is under your control. Default is `false`. + +## AsciiDoc + +This is the default configuration for the AsciiDoc renderer: {{< code-toggle config=markup.asciidocExt />}} -attributes -: (`map`) Variables to be referenced in your AsciiDoc file. This is a list of variable name/value maps. See Asciidoctor’s [attributes]. +### AsciiDoc settings explained + +###### attributes + +(`map`) A map of key-value pairs, each a document attributes,See Asciidoctor’s [attributes]. [attributes]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions -backend: -: (`string`) Don’t change this unless you know what you are doing. +###### backend + +(`string`) The backend output file format. Default is `html5`. -extensions -: (`[]string`) Possible extensions are `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, and `asciidoctor-question`. +###### extensions -failureLevel -: (`string`) The minimum logging level that triggers a non-zero exit code (failure). +(`string array`) An array of enabled extensions, one or more of `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, or `asciidoctor-question`. -noHeaderOrFooter -: (`bool`) 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. +{{% note %}} +To mitigate security risks, entries in the extension array may not contain forward slashes (`/`), backslashes (`\`), or periods. Due to this restriction, extensions must be in Ruby's `$LOAD_PATH`. +{{% /note %}} -preserveTOC -: (`bool`) By default, Hugo removes the table of contents generated by Asciidoctor and provides it through the built-in variable `.TableOfContents` 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. +###### failureLevel -safeMode -: (`string`) Safe mode level `unsafe`, `safe`, `server`, or `secure`. Don’t change this unless you know what you are doing. +(`string`) The minimum logging level that triggers a non-zero exit code (failure). Default is `fatal`. -sectionNumbers -: (`bool`) Auto-number section titles. +###### noHeaderOrFooter -trace -: (`bool`) Include backtrace information on errors. +(`bool`) If `true`, outputs an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Default is `true`. -verbose -: (`bool`) Verbosely print processing information and configuration file checks to stderr. +###### preserveTOC -workingFolderCurrent -: (`bool`) Sets the working directory to be the same as that of the AsciiDoc file being processed, so that [include] will work with relative paths. This setting uses the asciidoctor cli parameter --base-dir and attribute outdir=. For rendering diagrams with [asciidoctor-diagram], `workingFolderCurrent` must be set to `true`. +(`bool`) If `true`, preserves the table of contents (TOC) rendered by Asciidoctor. By default, to make the TOC compatible with existing themes, Hugo removes the TOC rendered by Asciidoctor. To render the TOC, use the [`TableOfContents`] method on a `Page` object in your templates. Default is `false`. -[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/ -[include]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files +[`TableOfContents`]: /methods/page/tableofcontents/ + +###### safeMode -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 the 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. +(`string`) The safe mode level, one of `unsafe`, `safe`, `server`, or `secure`. Default is `unsafe`. -Example of how to set extensions and attributes: +###### sectionNumbers -```yml +(`bool`) If `true`, numbers each section title. Default is `false`. + +###### trace + +(`bool`) If `true`, include backtrace information on errors. Default is `false`. + +###### verbose + +(`bool`)If `true`, verbosely prints processing information and configuration file checks to stderr. Default is `false`. + +###### workingFolderCurrent + +(`bool`) If `true`, sets the working directory to be the same as that of the AsciiDoc file being processed, allowing [includes] to work with relative paths. Set to `true` to render diagrams with the [asciidoctor-diagram] extension. Default is `false`. + +[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/ +[includes]: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#includes + +### AsciiDoc configuration example + +{{< code-toggle file=hugo >}} [markup.asciidocExt] extensions = ["asciidoctor-html5s", "asciidoctor-diagram"] workingFolderCurrent = true [markup.asciidocExt.attributes] my-base-url = "https://example.com/" my-attribute-name = "my value" -``` +{{< /code-toggle >}} + +### AsciiDoc troubleshooting -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 +Run `hugo --logLevel debug` to examine Hugo's call to the Asciidoctor executable: ```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 -] ... @@ -200,19 +305,18 @@ For CSS, see [Generate Syntax Highlighter CSS](/content-management/syntax-highli ## Table of contents +This is the default configuration for the table of contents, applicable to Goldmark and Asciidoctor: + {{< code-toggle config=markup.tableOfContents />}} -These settings only works for the Goldmark renderer: +###### startLevel -startLevel -: The heading level, values starting at 1 (`h1`), to start render the table of contents. +(`int`) Heading levels less than this value will be excluded from the table of contents. For example, to exclude `h1` elements from the table of contents, set this value to `2`. Default is `2`. -endLevel -: The heading level, inclusive, to stop render the table of contents. +###### endLevel -ordered -: If `true`, generates an ordered list instead of an unordered list. +(`int`) Heading levels greater than this value will be excluded from the table of contents. For example, to exclude `h4`, `h5`, and `h6` elements from the table of contents, set this value to `3`. Default is `3`. -## Render hooks +###### ordered -See [Markdown Render Hooks](/templates/render-hooks/). +(`bool`) If `true`, generates an ordered list instead of an unordered list. Default is `false`. diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md index 3ce0077ba..35c7d780e 100644 --- a/content/en/getting-started/configuration.md +++ b/content/en/getting-started/configuration.md @@ -73,15 +73,11 @@ my-project/ │ ├── menus.en.toml │ ├── menus.de.toml │ └── params.toml - ├── production/ - │ ├── hugo.toml - │ └── params.toml - └── staging/ - ├── hugo.toml + └── production/ └── params.toml ``` -The root configuration keys are `build`, `caches`, `cascade`, `deployment`, `frontmatter`, `imaging`, `languages`, `markup`, `mediatypes`, `menus`, `minify`, `module`, `outputformats`, `outputs`, `params`, `permalinks`, `privacy`, `related`, `security`, `server`, `services`, `sitemap`, and `taxonomies`. +The root configuration keys are `build`, `caches`, `cascade`, `deployment`, `frontmatter`, `imaging`, `languages`, `markup`, `mediatypes`, `menus`, `minify`, `module`, `outputformats`, `outputs`, `params`, `permalinks`, `privacy`, `related`, `security`, `segments`, `server`, `services`, `sitemap`, and `taxonomies`. ### Omit the root key @@ -226,25 +222,33 @@ See [Configure Build](#configure-build). ###### buildFuture -(`bool`) Include content with publishdate in the future. Default is `false`. +(`bool`) Include content with a future publication date. Default is `false`. ###### caches See [Configure File Caches](#configure-file-caches). +###### capitalizeListTitles + +{{< new-in 0.123.3 >}} + +(`bool`) Whether to capitalize automatic list titles. Applicable to section, taxonomy, and term pages. Default is `true`. You can change the capitalization style in your site configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. See [details]. + +[details]: /getting-started/configuration/#configure-title-case + ###### cascade -Pass down down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade). +Pass down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#cascade). {{% note %}} -For a website in a single language, define the `[[cascade]]` in [Front Matter](/content-management/front-matter#front-matter-cascade). For a multilingual website, define the `[[cascade]]` in [Site Config](../../getting-started/configuration/#cascade). +For a website in a single language, define the `[[cascade]]` in [Front Matter](/content-management/front-matter#cascade). For a multilingual website, define the `[[cascade]]` in [Site Config](/getting-started/configuration/#cascade). To remain consistent and prevent unexpected behavior, do not mix these strategies. {{% /note %}} ###### canonifyURLs -(`bool`) Enable to turn relative URLs into absolute. Default is `false`. See [details](/content-management/urls/#canonical-urls). +(`bool`) See [details](/content-management/urls/#canonical-urls) before enabling this feature. Default is `false`. ###### cleanDestinationDir @@ -324,8 +328,11 @@ See [image processing configuration](/content-management/image-processing/#imagi (`string`) A language tag as defined by [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646). This value is used to populate: -- The `<language>` element in the internal [RSS template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml) -- The `lang` attribute of the `<html>` element in the internal [alias template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/alias.html) +- The `<language>` element in the embedded [RSS template]({{% eturl rss %}}) +- The `lang` attribute of the `<html>` element in the embedded [alias template]({{% eturl alias %}}) +- The `og:locale` `meta` element in the embedded [Open Graph template]({{% eturl opengraph %}}) + +When present in the root of the configuration, this value is ignored if one or more language keys exists. Please specify this value independently for each language key. ###### languages @@ -369,7 +376,7 @@ Module configuration see [module configuration](/hugo-modules/configuration/). ###### outputFormats -See [Configure Output Formats](#configure-additional-output-formats). +See [custom output formats]. ###### paginate @@ -385,27 +392,33 @@ See [Content Management](/content-management/urls/#permalinks). ###### pluralizeListTitles -(`bool`) Pluralize titles in lists. Default is `true`. +(`bool`) Whether to pluralize automatic list titles. Applicable to section pages. Default is `true`. ###### publishDir (`string`) The directory to where Hugo will write the final static site (the HTML files etc.). Default is `public`. +###### refLinksErrorLevel + +(`string`) When using `ref` or `relref` to resolve page links and a link cannot be resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`). Default is `ERROR`. + +###### refLinksNotFoundURL + +(`string`) URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is. + ###### related See [Related Content](/content-management/related/#configure-related-content). ###### relativeURLs -(`bool`) Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. Default is `false`. See [details](/content-management/urls/#relative-urls). +(`bool`) See [details](/content-management/urls/#relative-urls) before enabling this feature. Default is `false`. -###### refLinksErrorLevel +###### renderSegments -(`string`) When using `ref` or `relref` to resolve page links and a link cannot be resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`). Default is `ERROR`. +{{< new-in 0.124.0 >}} -###### refLinksNotFoundURL - -(`string`) URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is. +(`string slice`) A list of segments to render. If not set, everything will be rendered. This is more commonly set in a CLI flag, e.g. `hugo --renderSegments segment1,segment2`. The segment names must match the names in the [segments](#configure-segments) configuration. ###### removePathAccents @@ -421,7 +434,11 @@ See [Menus](/content-management/menus/#define-automatically). ###### security -See [Security Policy](/about/security-model/#security-policy). +See [Security Policy](/about/security/#security-policy). + +###### segments + +See [Segments](#configure-segments). ###### sitemap @@ -429,7 +446,9 @@ Default [sitemap configuration](/templates/sitemap-template/#configuration). ###### summaryLength -(`int`) The length of text in words to show in a [`.Summary`](/content-management/summaries/#automatic-summary-splitting). Default is `70`. +(`int`) Applicable to automatic summaries, the approximate number of words to render when calling the [`Summary`] method on a `Page` object. Default is `70`. + +[`Summary`]: /methods/page/summary/ ###### taxonomies @@ -605,6 +624,39 @@ to = "/404.html" status = 404 {{< /code-toggle >}} +With a multilingual site, define the redirect for the default content language last: + +{{< code-toggle file=config/development/server >}} +defaultContentLanguage = 'en' +defaultContentLanguageInSubdir = false +[[redirects]] +from = '/fr/**' +to = '/fr/404.html' +status = 404 + +[[redirects]] # Default language must be last. +from = '/**' +to = '/404.html' +status = 404 +{{< /code-toggle >}} + +If you are serving the default content language from a subdirectory: + +{{< code-toggle file=config/development/server >}} +defaultContentLanguage = 'en' +defaultContentLanguageInSubdir = true +[[redirects]] +from = '/fr/**' +to = '/fr/404.html' +status = 404 + +[[redirects]] # Default language must be last. +from = '/**' +to = '/en/404.html' +status = 404 +{{< /code-toggle >}} + + ## Configure title case By default, Hugo follows the capitalization rules published in the [Associated Press Stylebook] when creating automatic section titles, and when transforming strings with the [`strings.Title`] function. @@ -626,15 +678,31 @@ firstupper none : Disable transformation of automatic section titles, and disable the transformation performed by the `strings.Title` function. This is useful if you would prefer to manually capitalize section titles as needed, and to bypass opinionated theme usage of the `strings.Title` function. -[`strings.Title`]: /functions/strings/title +[`strings.Title`]: /functions/strings/title/ [Associated Press Stylebook]: https://www.apstylebook.com/ [Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html [site configuration]: /getting-started/configuration/#configure-title-case ## Configuration environment variables +DART_SASS_BINARY +: (`string`) The absolute path to the Dart Sass executable. By default, Hugo searches for the executable in each of the paths in the `PATH` environment variable. + +HUGO_ENVIRONMENT +: (`string`) Overrides the default [environment], typically one of `development`, `staging`, or `production`. + +[environment]: /getting-started/glossary/#environment + +HUGO_FILE_LOG_FORMAT +: (`string`) A format string for the file path, line number, and column number displayed when reporting errors, or when calling the `Position` method from a shortcode or Markdown render hook. Valid tokens are `:file`, `:line`, and `:col`. Default is `:file::line::col`. + +{{< new-in 0.123.0 >}} + +HUGO_MEMORYLIMIT +: (`int`) The maximum amount of system memory, in gigabytes, that Hugo can use while rendering your site. Default is 25% of total system memory. + HUGO_NUMWORKERMULTIPLIER -: Can be set to increase or reduce the number of workers used in parallel processing in Hugo. If not set, the number of logical CPUs will be used. +: (`int`) The number of workers used in parallel processing. Default is the number of logical CPUs. ## Configure with environment variables @@ -726,10 +794,6 @@ The above will try first to extract the value for `.Date` from the file name, th `:git` : This is the Git author date for the last revision of this content file. This will only be set if `--enableGitInfo` is set or `enableGitInfo = true` is set in site configuration. -## Configure additional output formats - -Hugo v0.20 introduced the ability to render your content to multiple output formats (e.g., to JSON, AMP html, or CSV). See [Output Formats] for information on how to add these values to your Hugo project's configuration file. - ## Configure minify See the [tdewolff/minify] project page for details. @@ -769,7 +833,7 @@ dir This is the directory where Hugo by default will store its file caches. See [Configure File Caches](#configure-file-caches). -This can be set using the `cacheDir` config option or via the OS env variable `HUGO_CACHEDIR`. +This can be set using the `cacheDir` config option or via the OS environment variable `HUGO_CACHEDIR`. If this is not set, Hugo will use, in order of preference: @@ -779,10 +843,123 @@ If this is not set, Hugo will use, in order of preference: If you want to know the current value of `cacheDir`, you can run `hugo config`, e.g: `hugo config | grep cachedir`. -[`time`]: /functions/time/astime -[`.Site.Params`]: /variables/site/ -[directory structure]: /getting-started/directory-structure +[`time`]: /functions/time/astime/ +[`.Site.Params`]: /method/site/params/ +[directory structure]: /getting-started/directory-structure/ [lookup order]: /templates/lookup-order/ -[Output Formats]: /templates/output-formats/ +[custom output formats]: /templates/output-formats/ [templates]: /templates/ [static-files]: /content-management/static-files/ + + +## Configure HTTP cache + +{{< new-in 0.127.0 >}} + +Note that this configuration is currently only relevant when using the [resources.GetRemote] function. + +The caching in Hugo is layered: + +```goat {.w-40} + .-----------. +| dynacache | + '-----+-----' + | + v + .----------. +| HTTP cache | + '-----+----' + | + v + .----------. +| file cache | + '-----+----' +``` + +Dynacache +: A in memory LRU cache that gets evicted on changes, [Cache Buster](#configure-cache-busters) matches and in low memory situations. + +HTTP Cache +: Enables HTTP cache behavior (RFC 9111) for remote resources. This works best for resources with properly set up HTTP cache headers. The HTTP cache uses the [file cache] to store and serve cached resources. + +File Cache +: See [file cache]. + +The default HTTP cache disables everything: + +{{< code-toggle config=HTTPCache />}} + +caching +: Enabled RFC 9111 cache behavior _for_ a configured set of resources. Stale resources will be refreshed from the [file cache] even if their configured TTL isn't reached. + +polling +: Enables polling _for_ a set of resources. Note that you can enable polling for resources even if HTTP caching is disabled. This setting is only used when in watch mode (e.g. `hugo server`). When a changed resource is detected, that change triggers a rebuild of pages using that resource. + +[resources.GetRemote]: /functions/resources/getremote/ +[file cache]: #configure-file-caches + +## Configure segments + +{{< new-in 0.124.0 >}} + +{{% note %}} +The `segments` configuration is currently only used to configure partitioned rendering. +This feature is only about what gets rendered when, Hugo's entire object graph (sites and pages) is +always available. +{{% /note %}} + +* Each segment consists of zero or more `exclude` filters and zero or more `include` filters. +* Each filter consists of one or more field Glob matchers. +* Each filter in a section (`exclude` or `include`) is ORed together, each matcher in a filter is ANDed together. + +The fields that can be used in the filters are: + +path +: The logical page [path]. + +lang +: The [page language]. + +kind +: The [kind] of the page. + +output +: The [output format] of the page. + +It is recommended to put coarse grained filters (e.g. for language and output format) in the excludes section, e.g.: + + +{{< code-toggle file=hugo >}} +[segments.segment1] + [[segments.segment1.excludes]] + lang = "n*" + [[segments.segment1.excludes]] + lang = "en" + output = "rss" + [[segments.segment1.includes]] + kind = "{home,term,taxonomy}" + [[segments.segment1.includes]] + path = "{/docs,/docs/**}" +{{< /code-toggle >}} + +With the above you can render only the pages in `segment1` by configuring the [renderSegments](#rendersegments) or setting the `--renderSegments` flag: + +```bash +hugo --renderSegments segment1 +``` + +Multiple segments can be configured, and the `--renderSegments` flag can take a comma separated list of segments. + +Some use cases for this feature: + +* Splitting builds of big sites. +* Enable faster builds during development by only rendering a subset of the site. +* Partial rebuilds, e.g. render the home page and the "news section" every hour, render the entire site once a week. +* Render only e.g. the JSON output format to push to e.g. a search index. + +[path]: /methods/page/path/ +[page language]: /methods/page/language/ +[kind]: /getting-started/glossary/#page-kind +[output format]: /getting-started/glossary/#output-format +[type]: /getting-started/glossary/#content-type + diff --git a/content/en/getting-started/directory-structure.md b/content/en/getting-started/directory-structure.md index f91849375..2331d8838 100644 --- a/content/en/getting-started/directory-structure.md +++ b/content/en/getting-started/directory-structure.md @@ -78,38 +78,49 @@ my-site/ Each of the subdirectories contributes to the content, structure, behavior, or presentation of your site. -archetypes -: The `archetypes` directory contains templates for new content. See [details](/content-management/archetypes/). +###### archetypes -assets -: The `assets` directory contains global resources typically passed through an asset pipeline. This includes resources such as images, CSS, Sass, JavaScript, and TypeScript. See [details](/hugo-pipes/introduction/). +The `archetypes` directory contains templates for new content. See [details](/content-management/archetypes/). -config -: The `config` directory contains your site configuration, possibly split into multiple subdirectories and files. For projects with minimal configuration or projects that do not need to behave differently in different environments, a single configuration file named `hugo.toml` in the root of the project is sufficient. See [details](/getting-started/configuration/#configuration-directory). +###### assets -content -: The `content` directory contains the markup files (typically markdown) and page resources that comprise the content of your site. See [details](/content-management/organization/). +The `assets` directory contains global resources typically passed through an asset pipeline. This includes resources such as images, CSS, Sass, JavaScript, and TypeScript. See [details](/hugo-pipes/introduction/). -data -: The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/templates/data-templates/). +###### config -i18n -: The `i18n` directory contains translation tables for multilingual sites. See [details](/content-management/multilingual/). +The `config` directory contains your site configuration, possibly split into multiple subdirectories and files. For projects with minimal configuration or projects that do not need to behave differently in different environments, a single configuration file named `hugo.toml` in the root of the project is sufficient. See [details](/getting-started/configuration/#configuration-directory). -layouts -: The layouts directory contains templates to transform content, data, and resources into a complete website. See [details](/templates/). +###### content -public -: The `public` directory contains the published website, generated when you run the `hugo` command. Hugo recreates this directory and its content as needed. See [details](/getting-started/usage/#build-your-site). +The `content` directory contains the markup files (typically Markdown) and page resources that comprise the content of your site. See [details](/content-management/organization/). -resources -: The `resources` directory contains cached output from Hugo's asset pipelines, generated when you run the `hugo` or `hugo server` commands. By default this cache directory includes CSS and images. Hugo recreates this directory and its content as needed. +###### data -static -: The `static` directory contains files that will be copied to the public directory when you build your site. For example: `favicon.ico`, `robots.txt`, and files that verify site ownership. Before the introduction of [page bundles](/getting-started/glossary/#page-bundle) and [asset pipelines](/hugo-pipes/introduction/), the `static` directory was also used for images, CSS, and JavaScript. See [details](/content-management/static-files/). +The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/content-management/data-sources/). -themes -: The `themes` directory contains one or more [themes](/getting-started/glossary/#theme), each in its own subdirectory. +###### i18n + +The `i18n` directory contains translation tables for multilingual sites. See [details](/content-management/multilingual/). + +###### layouts + +The layouts directory contains templates to transform content, data, and resources into a complete website. See [details](/templates/). + +###### public + +The `public` directory contains the published website, generated when you run the `hugo` or `hugo server` commands. Hugo recreates this directory and its content as needed. See [details](/getting-started/usage/#build-your-site). + +###### resources + +The `resources` directory contains cached output from Hugo's asset pipelines, generated when you run the `hugo` or `hugo server` commands. By default this cache directory includes CSS and images. Hugo recreates this directory and its content as needed. + +###### static + +The `static` directory contains files that will be copied to the public directory when you build your site. For example: `favicon.ico`, `robots.txt`, and files that verify site ownership. Before the introduction of [page bundles](/getting-started/glossary/#page-bundle) and [asset pipelines](/hugo-pipes/introduction/), the `static` directory was also used for images, CSS, and JavaScript. + +###### themes + +The `themes` directory contains one or more [themes](/getting-started/glossary/#theme), each in its own subdirectory. ## Union file system @@ -150,7 +161,7 @@ target = 'content' {{% note %}} When you overlay one directory on top of another, you must mount both directories. -If you think you need a symbolic link in your project directory, use Hugo's union file system instead. +Hugo does not follow symbolic links. If you need the functionality provided by symbolic links, use Hugo's union file system instead. {{% /note %}} After mounting, the union file system has this structure: diff --git a/content/en/getting-started/external-learning-resources/build-websites-with-hugo.png b/content/en/getting-started/external-learning-resources/build-websites-with-hugo.png Binary files differnew file mode 100644 index 000000000..ebed7e89f --- /dev/null +++ b/content/en/getting-started/external-learning-resources/build-websites-with-hugo.png diff --git a/content/en/getting-started/external-learning-resources/hia.jpg b/content/en/getting-started/external-learning-resources/hia.jpg Binary files differdeleted file mode 100644 index 601947a70..000000000 --- a/content/en/getting-started/external-learning-resources/hia.jpg +++ /dev/null diff --git a/content/en/getting-started/external-learning-resources/hugo-in-action.png b/content/en/getting-started/external-learning-resources/hugo-in-action.png Binary files differnew file mode 100644 index 000000000..7bc5c9930 --- /dev/null +++ b/content/en/getting-started/external-learning-resources/hugo-in-action.png diff --git a/content/en/getting-started/external-learning-resources/index.md b/content/en/getting-started/external-learning-resources/index.md index 634439bc6..d30305c2e 100644 --- a/content/en/getting-started/external-learning-resources/index.md +++ b/content/en/getting-started/external-learning-resources/index.md @@ -1,6 +1,6 @@ --- title: External learning resources -description: A list of tutorials and books on Hugo. +description: Use these third-party resources to learn Hugo. categories: [getting started] keywords: [books, tutorials, learning, usage] menu: @@ -8,30 +8,83 @@ menu: parent: getting-started weight: 70 weight: 70 +toc: true --- ## Books ### Hugo In Action -[](https://www.manning.com/books/hugo-in-action) +Hugo in Action is a step-by-step guide to using Hugo to create static websites. Working with a complete example website and source code samples, you'll learn how to build and host a low-maintenance, high-performance site that will wow your users and stay stable without relying on a third-party server. -Hugo in Action is a step-by-step guide to using Hugo to create static websites. Working with a complete example website and source code samples, you’ll learn how to build and host a low-maintenance, high-performance site that will wow your users and stay stable without relying on a third-party server. +[{{< img src="hugo-in-action.png" alt="Book cover: Hugo in Action" filter="process" filterArgs="resize x350 webp">}}](https://www.manning.com/books/hugo-in-action/) + +Author: Atishay Jain\ +Publisher: [Manning Publications](https://www.manning.com/books/hugo-in-action/)\ +Publication date: March 2022\ +Length: 488 pages\ +ISBN: 9781617297007 -[Hugo In Action Home Page](https://www.manning.com/books/hugo-in-action) ### Build Websites with Hugo -[Build Websites with Hugo - Fast Web Development with Markdown (2020)](https://pragprog.com/titles/bhhugo/) by Brian P. Hogan. +In this book, you'll use Hugo to build a personal portfolio site that you can use to showcase your skills and thoughts to the world. You'll build the basic skeleton, develop a custom theme, and use content templates to generate new pages quickly. You'll use internal and external data sources to embed content into your site, and render some of your content in JSON and RSS. You'll add a blog section with posts and integrate Disqus with your site, and then make your site searchable. + +[{{< img src="build-websites-with-hugo.png" alt="Book cover: Build Websites with Hugo" filter="process" filterArgs="resize x350 webp">}}](https://pragprog.com/titles/bhhugo/build-websites-with-hugo/) + + +Author: Brian P. Hogan\ +Publisher: [Pragmatic Bookshelf](https://pragprog.com/titles/bhhugo/build-websites-with-hugo/)\ +Publication date: May 2020\ +Length: 154 pages\ +ISBN: 9781680507263 + +## Videos + +### Hugo Beginner Tutorial Series + +Welcome to this introduction to Hugo tutorial. The goal of this series is to take you from a lion cub with basic web design knowledge to creating your first Hugo website. In this series you’ll learn how to set up a Hugo site, the basics of usingHugo layouts, partials, and templating, set up a blog, and finally use data files. By the end of this series you’ll have the foundational knowledge to build your own Hugo sites. + +1. [Getting set up in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/) +1. [Layouts in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/layouts-in-hugo/) +1. [Hugo Partials](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/hugo-partials/) +1. [Hugo templating basics](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/hugo-templating-basics/) +1. [Blogging in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/blogging-in-hugo/) +1. [Using Data in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/using-data-in-hugo/) -## Beginner tutorials +Creator: Mike Neumegen\ +Affiliation: [CloudCannon](https://cloudcannon.com/)\ +Creation date: April 2022 -### Hugo tutorial by CloudCannon +#### Hugo Static Site Generator -[Step-by-step written tutorial](https://cloudcannon.com/community/learn/hugo-beginner-tutorial/) to teach you the basics of creating a Hugo site. +This course covers the basics of using the Hugo static site generator. Work your way through the articles and we'll teach you everything you need to know to create a professional and scalable website or blog! -## Video tutorials -* Mike Dane explains the various features of Hugo via dedicated tutorials on [YouTube](https://www.youtube.com/watch?list=PLLAZ4kZ9dFpOnyRlyS-liKL5ReHDcj4G3&v=qtIqKaDlqXo). +1. [Introduction](https://www.giraffeacademy.com/static-site-generators/hugo/) +1. [Windows Installation](https://www.giraffeacademy.com/static-site-generators/hugo/installing-hugo-on-windows/) +1. [Mac Installation](https://www.giraffeacademy.com/static-site-generators/hugo/installing-hugo-on-mac/) +1. [Creating A New Site](https://www.giraffeacademy.com/static-site-generators/hugo/hugo-directory-structure/) +1. [Installing & Using Themes](https://www.giraffeacademy.com/static-site-generators/hugo/installing-using-themes/) +1. [Content Organization](https://www.giraffeacademy.com/static-site-generators/hugo/content-organization/) +1. [Front Matter](https://www.giraffeacademy.com/static-site-generators/hugo/front-matter/) +1. [Archetypes](https://www.giraffeacademy.com/static-site-generators/hugo/archetypes/) +1. [Shortcodes](https://www.giraffeacademy.com/static-site-generators/hugo/archetypes/) +1. [Taxonomies](https://www.giraffeacademy.com/static-site-generators/hugo/taxonomies/) +1. [Template Basics](https://www.giraffeacademy.com/static-site-generators/hugo/introduction-to-templates/) +1. [List Page Templates](https://www.giraffeacademy.com/static-site-generators/hugo/list-page-templates/) +1. [Single Page Templates](https://www.giraffeacademy.com/static-site-generators/hugo/single-page-templates/) +1. [Home Page Templates](https://www.giraffeacademy.com/static-site-generators/hugo/home-page-templates/) +1. [Section Templates](https://www.giraffeacademy.com/static-site-generators/hugo/section-templates/) +1. [Block Templates](https://www.giraffeacademy.com/static-site-generators/hugo/block-templates/) +1. [Variables](https://www.giraffeacademy.com/static-site-generators/hugo/variables/) +1. [Functions](https://www.giraffeacademy.com/static-site-generators/hugo/functions/) +1. [Conditionals](https://www.giraffeacademy.com/static-site-generators/hugo/conditionals/) +1. [Data Templates](https://www.giraffeacademy.com/static-site-generators/hugo/data-templates/) +1. [Partial Templates](https://www.giraffeacademy.com/static-site-generators/hugo/partial-templates/) +1. [Shortcode Templates](https://www.giraffeacademy.com/static-site-generators/hugo/shortcode-templates/) +1. [Building & Hosting](https://www.giraffeacademy.com/static-site-generators/hugo/building-&-hosting/) -* [Introduction to building your first Hugo site](https://cloudcannon.com/community/learn/hugo-beginner-tutorial/) by Mike Neumegen. +Creator: Mike Dane\ +Affiliation: [Giraffe Academy](https://www.giraffeacademy.com/)\ +Creation date: September 2017 diff --git a/content/en/getting-started/glossary.md b/content/en/getting-started/glossary.md index d4c1d0e26..c86c3fc97 100644 --- a/content/en/getting-started/glossary.md +++ b/content/en/getting-started/glossary.md @@ -11,25 +11,28 @@ weight: 60 # Use level 6 headings for each term in the glossary. --- -[A](#action) -[B](#bool) -[C](#cache) -[D](#default-sort-order) -[E](#environment) -[F](#field) -[G](#global-resource) -[I](#identifier) -[K](#kind) -[L](#layout) -[M](#map) -[O](#object) -[P](#page-bundle) -[R](#regular-page) -[S](#scalar) -[T](#taxonomic-weight) -[U](#unmarshal) -[V](#variable) -[W](#walk) +[A](#action) +[B](#bool) +[C](#cache) +[D](#default-sort-order) +[E](#environment) +[F](#field) +[G](#global-resource) +[H](#headless-bundle) +[I](#identifier) +[K](#kind) +[L](#layout) +[M](#map) +[N](#node) +[O](#object) +[P](#page-bundle) +[R](#regular-page) +[S](#scalar) +[T](#taxonomic-weight) +[U](#unmarshal) +[V](#variable) +[W](#walk) +[Z](#zero-time) ###### action @@ -57,7 +60,7 @@ A data type with two possible values, either `true` or `false`. ###### branch bundle -A [page bundle](#page-bundle) with an _index.md file and zero or more [resources](#resource). Analogous to a physical branch, a branch bundle may have descendants including regular pages, [leaf bundles](/getting-started/glossary/#leaf-bundle), and other branch bundles. See [details](/content-management/page-bundles/). +A directory that contains an _index.md file and zero or more [resources](#resource). Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without _index.md files are also branch bundles. This includes the home page. See [details](/content-management/page-bundles/). ###### build @@ -75,13 +78,25 @@ A software component that stores data so that future requests for the same data Within a template, to connect one or more [identifiers](#identifier) with a dot. An identifier can represent a method, object, or field. For example, `.Site.Params.author.name` or `.Date.UTC.Hour`. +###### CJK + +A collective term for the Chinese, Japanese, and Korean languages. See [details](https://en.wikipedia.org/wiki/CJK_characters). + +###### CLI + +Command line interface. + ###### collection An [array](#array), [slice](#slice), or [map](#map). +###### content adapter + +A template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML. See [details](/content-management/content-adapters/). + ###### content format -A markup language for creating content. Typically markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText. See [details](/content-management/formats/). +A markup language for creating content. Typically Markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText. See [details](/content-management/formats/). ###### content type @@ -93,7 +108,7 @@ A template called with the `.Page.Render` method. See [details](/templates/ ###### context -Represented by a dot "." within a [template action](#template-action), context is the current location in a data structure. For example, while iterating over a [collection](#collection) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See [details](/templates/introduction/#the-dot). +Represented by a dot "." within a [template action](#template-action), context is the current location in a data structure. For example, while iterating over a [collection](#collection) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See [details](/templates/introduction/#context). ###### default sort order @@ -107,15 +122,15 @@ A member of a slice or array. Typically one of `development`, `staging`, or `production`, each environment may exhibit different behavior depending on configuration and template logic. For example, in a production environment you might minify and fingerprint CSS, but that probably doesn't make sense in a development environment. -When running the built-in development server with the `hugo server` command, the environment is set to `development`. When building your site with the `hugo` command, the environment is set to `production`. To override the environment value, use the `--environment` command line flag. +When running the built-in development server with the `hugo server` command, the environment is set to `development`. When building your site with the `hugo` command, the environment is set to `production`. To override the environment value, use the `--environment` command line flag or the `HUGO_ENVIRONMENT` environment variable. To determine the current environment within a template, use the [`hugo.Environment`] function. -[`hugo.Environment`]: /functions/hugo/environment +[`hugo.Environment`]: /functions/hugo/environment/ ###### field -A predefined key/value pair in front matter such as `date` or `title`. See also [parameter](#parameter). +A predefined key-value pair in front matter such as `date` or `title`. See also [parameter](#parameter). ###### flag @@ -146,10 +161,14 @@ Used within a [template action](#template-action), a function takes one or more A file within the assets directory, or within any directory [mounted](/hugo-modules/configuration/#module-configuration-mounts) to the assets directory. Capture one or more global resources using the [`resources.Get`], [`resources.GetMatch`], [`resources.Match`], or [`resources.ByType`] functions. -[`resources.Get`]: /functions/resources/get -[`resources.GetMatch`]: /functions/resources/getmatch -[`resources.Match`]: /functions/resources/match -[`resources.ByType`]: /functions/resources/byType +[`resources.Get`]: /functions/resources/get/ +[`resources.GetMatch`]: /functions/resources/getmatch/ +[`resources.Match`]: /functions/resources/match/ +[`resources.ByType`]: /functions/resources/byType/ + +###### headless bundle + +An unpublished leaf or branch bundle whose content and resources you can include in other pages. See [build options](/content-management/build-options/). ###### identifier @@ -187,7 +206,7 @@ See [template](#template). ###### leaf bundle -A [page bundle](#page-bundle) with an index.md file and zero or more [resources](#resource). Analogous to a physical leaf, a leaf bundle is at the end of a branch. Hugo ignores content (but not resources) beneath the leaf bundle. See [details](/content-management/page-bundles/). +A directory that contains an index.md file and zero or more [resources](#resource). Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants. See [details](/content-management/page-bundles/). ###### list page @@ -197,13 +216,19 @@ Any [page kind](#page-kind) that receives a page [collection](#collection) in [c Adaptation of a site to meet language and regional requirements. This includes translations, language-specific media, date and currency formats, etc. See [details](/content-management/multilingual/) and the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated l10n. +###### logical path + +{{< new-in 0.123.0 >}} + +A page or page resource identifier derived from the file path, excluding its extension and language identifier. This value is neither a file path nor a URL. Starting with a file path relative to the content directory, Hugo determines the logical path by stripping the file extension and language identifier, converting to lower case, then replacing spaces with hyphens. <!-- You may also set this value using the `path` front matter field. --> See [examples](/methods/page/path/#examples). + ###### map An unordered group of elements, each indexed by a unique key. See the [Go documentation](https://go.dev/ref/spec#Map_types) for details. -###### markdown attribute +###### Markdown attribute -A list of attributes, containing one or more key/value pairs, separated by spaces or commas, and wrapped by braces. Apply markdown attributes to images and block-level elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables. See [details](/getting-started/configuration-markup/#goldmark). +A list of attributes, containing one or more key-value pairs, separated by spaces or commas, and wrapped by braces. Apply Markdown attributes to images and block-level elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables. See [details](/getting-started/configuration-markup/#goldmark). ###### marshal @@ -217,6 +242,14 @@ Used within a [template action](#template-action) and associated with an [object Like a [theme](#theme), a module is a packaged combination of [archetypes](#archetype), assets, content, data, [templates](#template), translation tables, static files, or configuration settings. A module may serve as the basis for a new site, or to augment an existing site. See [details](/hugo-modules/). +###### node + +A class of [page kinds](#page-kind) including `home`, `section`, `taxonomy`, and `term`. + +###### noop + +An abbreviated form of "no operation", a _noop_ is a statement that does nothing. + ###### object A data structure with or without associated [methods](#method). @@ -225,8 +258,8 @@ A data structure with or without associated [methods](#method). Created by invoking the [`Alphabetical`] or [`ByCount`] method on a [taxonomy object](#taxonomy-object), which is a [map](#map), an ordered taxonomy is a [slice](#slice), where each element is an object that contains the [term](#term) and a slice of its [weighted pages](#weighted-page). -[`Alphabetical`]: /methods/taxonomy/alphabetical -[`ByCount`]: /methods/taxonomy/bycount +[`Alphabetical`]: /methods/taxonomy/alphabetical/ +[`ByCount`]: /methods/taxonomy/bycount/ ###### output format @@ -242,7 +275,7 @@ A slice of page objects. ###### page kind -A classification of pages, one of `home`, `page`, `section`, `taxonomy`, or `term`. See [details](/templates/section-templates/#page-kinds). +A classification of pages, one of `home`, `page`, `section`, `taxonomy`, or `term`. See [details](/methods/page/kind/). Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` page kinds, but these are only available during the rendering of each of these respective page's kind and therefore *not* available in any of the `Pages` collections. @@ -266,7 +299,7 @@ The process of [paginating](#paginate) a [section](#section) list. ###### parameter -Typically, a user-defined key/value pair at the site or page level, but may also refer to a configuration setting or an [argument](#argument). See also [field](#field). +Typically, a user-defined key-value pair at the site or page level, but may also refer to a configuration setting or an [argument](#argument). See also [field](#field). ###### partial @@ -300,7 +333,7 @@ The host-relative URL of a published resource or a rendered page. ###### render hook -A [template](#template) that overrides standard markdown rendering. See [details](/templates/render-hooks/). +A [template](#template) that overrides standard Markdown rendering. See [details](/render-hooks). ###### remote resource @@ -312,17 +345,24 @@ Any file consumed by the build process to augment or generate content, structure Hugo supports three types of resources: [global](#global-resource), [page](#page-resource), and [remote](#remote-resource) +###### resource type + +The main type of a resource's [media type]. Content files such as Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode have resource type `page`. Other resource types include `image`, `video`, etc. Retrieve the resource type using the [`ResourceType`] method on a `Resource` object. + +[media type]: /methods/resource/mediatype/ +[`ResourceType`]: /methods/resource/resourcetype/ + ###### scalar A single value, one of [string](#string), [integer](#integer), [floating point](#floating-point), or [boolean](#boolean). ###### scratch pad -Conceptually, a [map](#map) with [methods](#method) to set, get, update, and delete values. Attach the data structure to a `Page` object using the [`Scratch`] or [`Store`] methods, or created a locally scoped scratch pad using the [`newScratch`] function. +Conceptually, a [map](#map) with [methods](#method) to set, get, update, and delete values. Attach the data structure to a `Page` object using the [`Scratch`] or [`Store`] methods, or create a locally scoped scratch pad using the [`newScratch`] function. -[`Scratch`]: /methods/page/scratch -[`Store`]: /methods/page/store -[`newScratch`]: /functions/collections/newscratch +[`Scratch`]: /methods/page/scratch/ +[`Store`]: /methods/page/store/ +[`newScratch`]: /functions/collections/newscratch/ ###### section @@ -334,7 +374,7 @@ Content with the "section" [page kind](#page-kind). Typically a listing of [regu ###### shortcode -A [template](#template) called from within markdown, taking zero or more [arguments](#argument). See [details](/content-management/shortcodes/). +A [template](#template) called from within Markdown, taking zero or more [arguments](#argument). See [details](/content-management/shortcodes/). ###### slice @@ -344,6 +384,14 @@ A numbered sequence of elements. Unlike Go's [array](#array) data type, slices a A sequence of bytes. For example, `"What is 6 times 7?"` . +###### string literal (interpreted) + +Interpreted string literals are character sequences between double quotes, as in "foo". Within the quotes, any character may appear except a newline and an unescaped double quote. The text between the quotes forms the value of the literal, with backslash escapes interpreted. See [details](https://go.dev/ref/spec#String_literals). + +###### string literal (raw) + +Raw string literals are character sequences between backticks, as in \`bar\`. Within the backticks, any character may appear except a backtick. Backslashes have no special meaning and the string may contain newlines. Carriage return characters ('\r') inside raw string literals are discarded from the raw string value. See [details](https://go.dev/ref/spec#String_literals). + ###### taxonomic weight Defined in front matter and unique to each taxonomy, this [weight](#weight) determines the sort order of page collections contained within a [taxonomy object](#taxonomy-object). See [details](/templates/taxonomy-templates/#assign-weight). @@ -394,7 +442,7 @@ To transform a serialized object into a data structure. For example, transformin ###### variable -A user-defined [identifier](#identifier) prefaced with a `$` symbol, representing a value of any data type, initialized or assigned within a [template action](#template-action). For example, `$foo` and `$bar` are variables. +A user-defined [identifier](#identifier) prepended with a `$` symbol, representing a value of any data type, initialized or assigned within a [template action](#template-action). For example, `$foo` and `$bar` are variables. ###### walk @@ -407,3 +455,7 @@ Used to position an element within a collection sorted by weight. Assign weights ###### weighted page Contained within a [taxonomy object](#taxonomy-object), a weighted page is a [map](#map) with two elements: a `Page` object, and its [taxonomic weight](#taxonomic-weight) as defined in front matter. Access the elements using the `Page` and `Weight` keys. + +###### zero time + +The _zero time_ is January 1, 0001, 00:00:00 UTC. Formatted per [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) the _zero time_ is 0001-01-01T00:00:00-00:00. diff --git a/content/en/getting-started/quick-start.md b/content/en/getting-started/quick-start.md index a6c54b54c..6e67cb73b 100644 --- a/content/en/getting-started/quick-start.md +++ b/content/en/getting-started/quick-start.md @@ -110,7 +110,7 @@ Press `Ctrl + C` to stop Hugo's development server. Add a new page to your site. ```text -hugo new content posts/my-first-post.md +hugo new content content/posts/my-first-post.md ``` Hugo created the file in the `content/posts` directory. Open the file with your editor. @@ -125,7 +125,7 @@ draft = true Notice the `draft` value in the [front matter] is `true`. By default, Hugo does not publish draft content when you build the site. Learn more about [draft, future, and expired content]. -Add some [markdown] to the body of the post, but do not change the `draft` value. +Add some [Markdown] to the body of the post, but do not change the `draft` value. [markdown]: https://commonmark.org/help/ @@ -151,8 +151,10 @@ hugo server -D View your site at the URL displayed in your terminal. Keep the development server running as you continue to add and change content. +When satisfied with your new content, set the front matter `draft` parameter to `false`. + {{% note %}} -Hugo's rendering engine conforms to the CommonMark [specification] for markdown. The CommonMark organization provides a useful [live testing tool] powered by the reference implementation. +Hugo's rendering engine conforms to the CommonMark [specification] for Markdown. The CommonMark organization provides a useful [live testing tool] powered by the reference implementation. [live testing tool]: https://spec.commonmark.org/dingus/ [specification]: https://spec.commonmark.org/ @@ -216,13 +218,13 @@ Hugo's [forum] is an active community of users and developers who answer questio For other resources to help you learn Hugo, including books and video tutorials, see the [external learning resources](/getting-started/external-learning-resources/) page. [Ananke]: https://github.com/theNewDynamic/gohugo-theme-ananke -[directory structure]: /getting-started/directory-structure +[directory structure]: /getting-started/directory-structure/ [draft, future, and expired content]: /getting-started/usage/#draft-future-and-expired-content [draft, future, or expired content]: /getting-started/usage/#draft-future-and-expired-content [external learning resources]:/getting-started/external-learning-resources/ [forum]: https://discourse.gohugo.io/ [forum]: https://discourse.gohugo.io/ -[front matter]: /content-management/front-matter +[front matter]: /content-management/front-matter/ [Git submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules [hosting and deployment]: /hosting-and-deployment/ [Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git diff --git a/content/en/getting-started/usage.md b/content/en/getting-started/usage.md index 268aed2e4..b19920907 100644 --- a/content/en/getting-started/usage.md +++ b/content/en/getting-started/usage.md @@ -23,7 +23,7 @@ hugo version You should see something like: ```text -hugo v0.122.0-b9a03bd59d5f71a529acb3e33f995e0ef332b3aa+extended linux/amd64 BuildDate=2024-01-26T15:54:24Z VendorInfo=gohugoio +hugo v0.123.0-3c8a4713908e48e6523f058ca126710397aa4ed5+extended linux/amd64 BuildDate=2024-02-19T16:32:38Z VendorInfo=gohugoio ``` ## Display available commands @@ -65,6 +65,16 @@ Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [ - The `publishDate` is in the future - The `expiryDate` is in the past +{{< new-in 0.123.0 >}} + +{{% note %}} +Hugo publishes descendants of draft, future, and expired [node] pages. To prevent publication of these descendants, use the [`cascade`] front matter field to cascade [build options] to the descendant pages. + +[build options]: /content-management/build-options/ +[`cascade`]: /content-management/front-matter/#cascade-field +[node]: /getting-started/glossary/#node +{{% /note %}} + You can override the default behavior when running `hugo` or `hugo server` with command line flags: ```sh @@ -130,7 +140,7 @@ public/ ├── categories/ │ ├── index.html │ └── index.xml <-- RSS feed for this section -├── post/ +├── posts/ │ ├── my-first-post/ │ │ └── index.html │ ├── index.html |
