mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-18 21:11:19 +02:00
@@ -1,20 +0,0 @@
|
||||
---
|
||||
title: Getting started
|
||||
linkTitle: Overview
|
||||
description: Quick start and guides for installing Hugo on your preferred operating system.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
identifier: getting-started-overview
|
||||
parent: getting-started
|
||||
weight: 10
|
||||
weight: 10
|
||||
aliases: [/overview/introduction/]
|
||||
---
|
||||
|
||||
If this is your first time using Hugo and you've [already installed Hugo on your machine][installed], we recommend the [quick start]. You can also use [external learning resources] to learn Hugo.
|
||||
|
||||
[installed]: /installation/
|
||||
[quick start]: /getting-started/quick-start/
|
||||
[external learning resources]: /getting-started/external-learning-resources/
|
@@ -1,218 +0,0 @@
|
||||
---
|
||||
title: Configure markup
|
||||
description: Configure rendering of markup to HTML.
|
||||
categories: [getting started,fundamentals]
|
||||
keywords: [configuration,highlighting]
|
||||
menu:
|
||||
docs:
|
||||
parent: getting-started
|
||||
weight: 50
|
||||
weight: 50
|
||||
slug: configuration-markup
|
||||
toc: true
|
||||
---
|
||||
|
||||
## Default handler
|
||||
|
||||
By default, 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.
|
||||
|
||||
To use a different renderer for markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your site configuration.
|
||||
|
||||
defaultMarkdownHandler|Description
|
||||
:--|:--
|
||||
`asciidocext`|[AsciiDoc]
|
||||
`goldmark`|[Goldmark]
|
||||
`org`|[Emacs Org Mode]
|
||||
`pandoc`|[Pandoc]
|
||||
`rst`|[reStructuredText]
|
||||
|
||||
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).
|
||||
|
||||
[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
|
||||
[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
|
||||
|
||||
## Goldmark
|
||||
|
||||
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).
|
||||
|
||||
Some settings explained:
|
||||
|
||||
hardWraps
|
||||
: By default, Goldmark ignores newlines within a paragraph. Set to `true` to render newlines as `<br>` elements.
|
||||
|
||||
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
|
||||
: The typographer extension replaces certain character combinations with HTML entities as specified below:
|
||||
|
||||
Markdown|Replaced by|Description
|
||||
:--|:--|:--
|
||||
`...`|`…`|horizontal ellipsis
|
||||
`'`|`’`|apostrophe
|
||||
`--`|`–`|en dash
|
||||
`---`|`—`|em dash
|
||||
`«`|`«`|left angle quote
|
||||
`“`|`“`|left double quote
|
||||
`‘`|`‘`|left single quote
|
||||
`»`|`»`|right angle quote
|
||||
`”`|`”`|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.
|
||||
|
||||
Hugo supports adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc.
|
||||
|
||||
A blockquote with a CSS class:
|
||||
|
||||
```md
|
||||
> foo
|
||||
> bar
|
||||
{.myclass}
|
||||
```
|
||||
|
||||
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}
|
||||
```
|
||||
|
||||
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.:
|
||||
|
||||
````txt
|
||||
```go {.myclass linenos=table,hl_lines=[8,"15-17"],linenostart=199}
|
||||
// ... code
|
||||
```
|
||||
````
|
||||
|
||||
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.
|
||||
|
||||
## Asciidoc
|
||||
|
||||
This is the default configuration for the AsciiDoc markdown 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].
|
||||
|
||||
[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.
|
||||
|
||||
extensions
|
||||
: (`[]string`) Possible extensions are `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, and `asciidoctor-question`.
|
||||
|
||||
failureLevel
|
||||
: (`string`) The minimum logging level that triggers a non-zero exit code (failure).
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
safeMode
|
||||
: (`string`) Safe mode level `unsafe`, `safe`, `server`, or `secure`. Don’t change this unless you know what you are doing.
|
||||
|
||||
sectionNumbers
|
||||
: (`bool`) Auto-number section titles.
|
||||
|
||||
trace
|
||||
: (`bool`) Include backtrace information on errors.
|
||||
|
||||
verbose
|
||||
: (`bool`) Verbosely print processing information and configuration file checks to stderr.
|
||||
|
||||
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`.
|
||||
|
||||
[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/
|
||||
[include]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files
|
||||
|
||||
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.
|
||||
|
||||
Example of how to set extensions and attributes:
|
||||
|
||||
```yml
|
||||
[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
|
||||
|
||||
```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 -] ...
|
||||
```
|
||||
|
||||
## Highlight
|
||||
|
||||
This is the default `highlight` configuration. Note that some of these settings can be set per code block, see [Syntax Highlighting](/content-management/syntax-highlighting/).
|
||||
|
||||
{{< code-toggle config=markup.highlight />}}
|
||||
|
||||
For `style`, see these galleries:
|
||||
|
||||
* [Short snippets](https://xyproto.github.io/splash/docs/all.html)
|
||||
* [Long snippets](https://xyproto.github.io/splash/docs/longer/all.html)
|
||||
|
||||
For CSS, see [Generate Syntax Highlighter CSS](/content-management/syntax-highlighting/#generate-syntax-highlighter-css).
|
||||
|
||||
## Table of contents
|
||||
|
||||
{{< code-toggle config=markup.tableOfContents />}}
|
||||
|
||||
These settings only works for the Goldmark renderer:
|
||||
|
||||
startLevel
|
||||
: The heading level, values starting at 1 (`h1`), to start render the table of contents.
|
||||
|
||||
endLevel
|
||||
: The heading level, inclusive, to stop render the table of contents.
|
||||
|
||||
ordered
|
||||
: If `true`, generates an ordered list instead of an unordered list.
|
||||
|
||||
## Render hooks
|
||||
|
||||
See [Markdown Render Hooks](/templates/render-hooks/).
|
@@ -1,788 +0,0 @@
|
||||
---
|
||||
title: Configure Hugo
|
||||
linkTitle: Configuration
|
||||
description: How to configure your Hugo site.
|
||||
categories: [getting started,fundamentals]
|
||||
keywords: [configuration,toml,yaml,json]
|
||||
menu:
|
||||
docs:
|
||||
parent: getting-started
|
||||
weight: 40
|
||||
weight: 40
|
||||
toc: true
|
||||
aliases: [/overview/source-directory/,/overview/configuration/]
|
||||
---
|
||||
|
||||
## Configuration file
|
||||
|
||||
Create a site configuration file in the root of your project directory, naming it `hugo.toml`, `hugo.yaml`, or `hugo.json`, with that order of precedence.
|
||||
|
||||
```text
|
||||
my-project/
|
||||
└── hugo.toml
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
With v0.109.0 and earlier the basename of the site configuration file was `config` instead of `hugo`. You can use either, but should transition to the new naming convention when practical.
|
||||
{{% /note %}}
|
||||
|
||||
A simple example:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
baseURL = 'https://example.org/'
|
||||
languageCode = 'en-us'
|
||||
title = 'ABC Widgets, Inc.'
|
||||
[params]
|
||||
subtitle = 'The Best Widgets on Earth'
|
||||
[params.contact]
|
||||
email = 'info@example.org'
|
||||
phone = '+1 202-555-1212'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To use a different configuration file when building your site, use the `--config` flag:
|
||||
|
||||
```sh
|
||||
hugo --config other.toml
|
||||
```
|
||||
|
||||
Combine two or more configuration files, with left-to-right precedence:
|
||||
|
||||
```sh
|
||||
hugo --config a.toml,b.yaml,c.json
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
See the specifications for each file format: [TOML], [YAML], and [JSON].
|
||||
|
||||
[TOML]: https://toml.io/en/latest
|
||||
[YAML]: https://yaml.org/spec/
|
||||
[JSON]: https://datatracker.ietf.org/doc/html/rfc7159
|
||||
{{% /note %}}
|
||||
|
||||
## Configuration directory
|
||||
|
||||
Instead of a single site configuration file, split your configuration by [environment], root configuration key, and language. For example:
|
||||
|
||||
[environment]: /getting-started/glossary/#environment
|
||||
|
||||
```text
|
||||
my-project/
|
||||
└── config/
|
||||
├── _default/
|
||||
│ ├── hugo.toml
|
||||
│ ├── menus.en.toml
|
||||
│ ├── menus.de.toml
|
||||
│ └── params.toml
|
||||
├── production/
|
||||
│ ├── hugo.toml
|
||||
│ └── params.toml
|
||||
└── staging/
|
||||
├── hugo.toml
|
||||
└── 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`.
|
||||
|
||||
### Omit the root key
|
||||
|
||||
When splitting the configuration by root key, omit the root key in the given file. For example, these are equivalent:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[params]
|
||||
foo = 'bar'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
{{< code-toggle file=params >}}
|
||||
foo = 'bar'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
### Recursive parsing
|
||||
|
||||
Hugo parses the `config` directory recursively, allowing you to organize the files into subdirectories. For example:
|
||||
|
||||
```text
|
||||
my-project/
|
||||
└── config/
|
||||
└── _default/
|
||||
├── navigation/
|
||||
│ ├── menus.de.toml
|
||||
│ └── menus.en.toml
|
||||
└── hugo.toml
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```text
|
||||
my-project/
|
||||
└── config/
|
||||
├── _default/
|
||||
│ ├── hugo.toml
|
||||
│ ├── menus.en.toml
|
||||
│ ├── menus.de.toml
|
||||
│ └── params.toml
|
||||
├── production/
|
||||
│ ├── hugo.toml
|
||||
│ └── params.toml
|
||||
└── staging/
|
||||
├── hugo.toml
|
||||
└── params.toml
|
||||
```
|
||||
|
||||
Considering the structure above, when running `hugo --environment staging`, Hugo will use every setting from `config/_default` and merge `staging`'s on top of those.
|
||||
|
||||
Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify a [Google tag ID] in your site configuration:
|
||||
|
||||
[Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en
|
||||
|
||||
{{< code-toggle file=hugo copy=false >}}
|
||||
[services.googleAnalytics]
|
||||
ID = 'G-XXXXXXXXX'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Now consider the following scenario:
|
||||
|
||||
1. You don't want to load the analytics code when running `hugo server`.
|
||||
2. You want to use different Google tag IDs for your production and staging environments. For example:
|
||||
|
||||
- `G-PPPPPPPPP` for production
|
||||
- `G-SSSSSSSSS` for staging
|
||||
|
||||
To satisfy these requirements, configure your site as follows:
|
||||
|
||||
1. `config/_default/hugo.toml`
|
||||
|
||||
Exclude the `services.googleAnalytics` section. This will prevent loading of the analytics code when you run `hugo server`.
|
||||
|
||||
By default, Hugo sets its `environment` to `development` when running `hugo server`. In the absence of a `config/development` directory, Hugo uses the `config/_default` directory.
|
||||
|
||||
2. `config/production/hugo.toml`
|
||||
|
||||
Include this section only:
|
||||
|
||||
{{< code-toggle file=hugo copy=false >}}
|
||||
[services.googleAnalytics]
|
||||
ID = 'G-PPPPPPPPP'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
You do not need to include other parameters in this file. Include only those parameters that are specific to your production environment. Hugo will merge these parameters with the default configuration.
|
||||
|
||||
By default, Hugo sets its `environment` to `production` when running `hugo`. The analytics code will use the `G-PPPPPPPPP` tag ID.
|
||||
|
||||
3. `config/staging/hugo.toml`
|
||||
|
||||
Include this section only:
|
||||
|
||||
{{< code-toggle file=hugo copy=false >}}
|
||||
[services.googleAnalytics]
|
||||
ID = 'G-SSSSSSSSS'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
You do not need to include other parameters in this file. Include only those parameters that are specific to your staging environment. Hugo will merge these parameters with the default configuration.
|
||||
|
||||
To build your staging site, run `hugo --environment staging`. The analytics code will use the `G-SSSSSSSSS` tag ID.
|
||||
|
||||
## Merge configuration from themes
|
||||
|
||||
The configuration value for `_merge` can be one of:
|
||||
|
||||
none
|
||||
: No merge.
|
||||
|
||||
shallow
|
||||
: Only add values for new keys.
|
||||
|
||||
deep
|
||||
: Add values for new keys, merge existing.
|
||||
|
||||
Note that you don't need to be so verbose as in the default setup below; a `_merge` value higher up will be inherited if not set.
|
||||
|
||||
{{< code-toggle file=hugo dataKey="config_helpers.mergeStrategy" skipHeader=true />}}
|
||||
|
||||
## All configuration settings
|
||||
|
||||
###### archetypeDir
|
||||
|
||||
(`string`) The directory where Hugo finds archetype files (content templates). Default is `archetypes`. {{% module-mounts-note %}}
|
||||
|
||||
###### assetDir
|
||||
|
||||
(`string`) The directory where Hugo finds asset files used in [Hugo Pipes](/hugo-pipes/). Default is `assets`. {{% module-mounts-note %}}
|
||||
|
||||
###### baseURL
|
||||
|
||||
(`string`) The absolute URL (protocol, host, path, and trailing slash) of your published site (e.g., `https://www.example.org/docs/`).
|
||||
|
||||
###### build
|
||||
|
||||
See [Configure Build](#configure-build).
|
||||
|
||||
###### buildDrafts
|
||||
|
||||
(`bool`) Include drafts when building. Default is `false`.
|
||||
|
||||
###### buildExpired
|
||||
|
||||
(`bool`) Include content already expired. Default is `false`.
|
||||
|
||||
###### buildFuture
|
||||
|
||||
(`bool`) Include content with publishdate in the future. Default is `false`.
|
||||
|
||||
###### caches
|
||||
|
||||
See [Configure File Caches](#configure-file-caches).
|
||||
|
||||
###### 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).
|
||||
|
||||
{{% 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).
|
||||
|
||||
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).
|
||||
|
||||
###### cleanDestinationDir
|
||||
|
||||
(`bool`) When building, removes files from destination not found in static directories. Default is `false`.
|
||||
|
||||
###### contentDir
|
||||
|
||||
(`string`) The directory from where Hugo reads content files. Default is `content`. {{% module-mounts-note %}}
|
||||
|
||||
###### copyright
|
||||
|
||||
(`string`) Copyright notice for your site, typically displayed in the footer.
|
||||
|
||||
###### dataDir
|
||||
|
||||
(`string`) The directory from where Hugo reads data files. Default is `data`. {{% module-mounts-note %}}
|
||||
|
||||
###### defaultContentLanguage
|
||||
|
||||
(`string`) Content without language indicator will default to this language. Default is `en`.
|
||||
|
||||
###### defaultContentLanguageInSubdir
|
||||
|
||||
(`bool`) Render the default content language in subdir, e.g. `content/en/`. The site root `/` will then redirect to `/en/`. Default is `false`.
|
||||
|
||||
###### disableAliases
|
||||
|
||||
(`bool`) Will disable generation of alias redirects. Note that even if `disableAliases` is set, the aliases themselves are preserved on the page. The motivation with this is to be able to generate 301 redirects in an `.htaccess`, a Netlify `_redirects` file or similar using a custom output format. Default is `false`.
|
||||
|
||||
###### disableHugoGeneratorInject
|
||||
|
||||
(`bool`) Hugo will, by default, inject a generator meta tag in the HTML head on the _home page only_. You can turn it off, but we would really appreciate if you don't, as this is a good way to watch Hugo's popularity on the rise. Default is `false`.
|
||||
|
||||
###### disableKinds
|
||||
|
||||
(`string slice`) Disable rendering of the specified page [kinds], any of `404`, `home`, `page`, `robotstxt`, `rss`, `section`, `sitemap`, `taxonomy`, or `term`.
|
||||
|
||||
[kinds]: /getting-started/glossary/#page-kind
|
||||
|
||||
###### disableLiveReload
|
||||
|
||||
(`bool`) Disable automatic live reloading of browser window. Default is `false`.
|
||||
|
||||
###### disablePathToLower
|
||||
|
||||
(`bool`) Do not convert the url/path to lowercase. Default is `false`.
|
||||
|
||||
###### enableEmoji
|
||||
|
||||
(`bool`) Enable Emoji emoticons support for page content; see the [emoji shortcode quick reference guide](/quick-reference/emojis/). Default is `false`.
|
||||
|
||||
###### enableGitInfo
|
||||
|
||||
(`bool`) Enable `.GitInfo` object for each page (if the Hugo site is versioned by Git). This will then update the `Lastmod` parameter for each page using the last git commit date for that content file. Default is `false`.
|
||||
|
||||
###### enableMissingTranslationPlaceholders
|
||||
|
||||
(`bool`) Show a placeholder instead of the default value or an empty string if a translation is missing. Default is `false`.
|
||||
|
||||
###### enableRobotsTXT
|
||||
|
||||
(`bool`) Enable generation of `robots.txt` file. Default is `false`.
|
||||
|
||||
###### frontmatter
|
||||
|
||||
See [Front matter Configuration](#configure-front-matter).
|
||||
|
||||
###### hasCJKLanguage
|
||||
|
||||
(`bool`) If true, auto-detect Chinese/Japanese/Korean Languages in the content. This will make `.Summary` and `.WordCount` behave correctly for CJK languages. Default is `false`.
|
||||
|
||||
###### imaging
|
||||
|
||||
See [image processing configuration](/content-management/image-processing/#imaging-configuration).
|
||||
|
||||
###### languageCode
|
||||
|
||||
(`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)
|
||||
|
||||
###### languages
|
||||
|
||||
See [Configure Languages](/content-management/multilingual/#configure-languages).
|
||||
|
||||
###### disableLanguages
|
||||
|
||||
See [Disable a Language](/content-management/multilingual/#disable-a-language)
|
||||
|
||||
###### markup
|
||||
|
||||
See [Configure Markup](/getting-started/configuration-markup).
|
||||
|
||||
###### mediaTypes
|
||||
|
||||
See [Configure Media Types](/templates/output-formats/#media-types).
|
||||
|
||||
###### menus
|
||||
|
||||
See [Menus](/content-management/menus/#define-in-site-configuration).
|
||||
|
||||
###### minify
|
||||
|
||||
See [Configure Minify](#configure-minify).
|
||||
|
||||
###### module
|
||||
|
||||
Module configuration see [module configuration](/hugo-modules/configuration/).
|
||||
|
||||
###### newContentEditor
|
||||
|
||||
(`string`) The editor to use when creating new content.
|
||||
|
||||
###### noChmod
|
||||
|
||||
(`bool`) Don't sync permission mode of files. Default is `false`.
|
||||
|
||||
###### noTimes
|
||||
|
||||
(`bool`) Don't sync modification time of files. Default is `false`.
|
||||
|
||||
###### outputFormats
|
||||
|
||||
See [Configure Output Formats](#configure-additional-output-formats).
|
||||
|
||||
###### paginate
|
||||
|
||||
(`int`) Default number of elements per page in [pagination](/templates/pagination/). Default is `10`.
|
||||
|
||||
###### paginatePath
|
||||
|
||||
(`string`) The path element used during pagination (`https://example.org/page/2`). Default is `page`.
|
||||
|
||||
###### permalinks
|
||||
|
||||
See [Content Management](/content-management/urls/#permalinks).
|
||||
|
||||
###### pluralizeListTitles
|
||||
|
||||
(`bool`) Pluralize titles in lists. Default is `true`.
|
||||
|
||||
###### publishDir
|
||||
|
||||
(`string`) The directory to where Hugo will write the final static site (the HTML files etc.). Default is `public`.
|
||||
|
||||
###### 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).
|
||||
|
||||
###### 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.
|
||||
|
||||
###### removePathAccents
|
||||
|
||||
(`bool`) Removes [non-spacing marks](https://www.compart.com/en/unicode/category/Mn) from [composite characters](https://en.wikipedia.org/wiki/Precomposed_character) in content paths. Default is `false`.
|
||||
|
||||
```text
|
||||
content/post/hügó.md → https://example.org/post/hugo/
|
||||
```
|
||||
|
||||
###### sectionPagesMenu
|
||||
|
||||
See [Menus](/content-management/menus/#define-automatically).
|
||||
|
||||
###### security
|
||||
|
||||
See [Security Policy](/about/security-model/#security-policy).
|
||||
|
||||
###### sitemap
|
||||
|
||||
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`.
|
||||
|
||||
###### taxonomies
|
||||
|
||||
See [Configure Taxonomies](/content-management/taxonomies#configure-taxonomies).
|
||||
|
||||
###### theme
|
||||
|
||||
See [module configuration](/hugo-modules/configuration/#module-configuration-imports) for how to import a theme.
|
||||
|
||||
###### themesDir
|
||||
|
||||
(`string`) The directory where Hugo reads the themes from. Default is `themes`.
|
||||
|
||||
###### timeout
|
||||
|
||||
(`string`) Timeout for generating page contents, specified as a [duration](https://pkg.go.dev/time#Duration) or in seconds. *Note:* this is used to bail out of recursive content generation. You might need to raise this limit if your pages are slow to generate (e.g., because they require large image processing or depend on remote contents). Default is `30s`.
|
||||
|
||||
###### timeZone
|
||||
|
||||
(`string`) The time zone (or location), e.g. `Europe/Oslo`, used to parse front matter dates without such information and in the [`time`] function. The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
|
||||
|
||||
###### title
|
||||
|
||||
(`string`) Site title.
|
||||
|
||||
###### titleCaseStyle
|
||||
|
||||
(`string`) Default is `ap`. See [Configure Title Case](#configure-title-case).
|
||||
|
||||
###### uglyURLs
|
||||
|
||||
(`bool`) When enabled, creates URL of the form `/filename.html` instead of `/filename/`. Default is `false`.
|
||||
|
||||
###### watch
|
||||
|
||||
(`bool`) Watch filesystem for changes and recreate as needed. Default is `false`.
|
||||
|
||||
{{% note %}}
|
||||
If you are developing your site on a \*nix machine, here is a handy shortcut for finding a configuration option from the command line:
|
||||
```txt
|
||||
cd ~/sites/yourhugosite
|
||||
hugo config | grep emoji
|
||||
```
|
||||
|
||||
which shows output like
|
||||
|
||||
```txt
|
||||
enableemoji: true
|
||||
```
|
||||
{{% /note %}}
|
||||
|
||||
## Configure build
|
||||
|
||||
The `build` configuration section contains global build-related configuration options.
|
||||
|
||||
{{< code-toggle config=build />}}
|
||||
|
||||
buildStats {{< new-in 0.115.1 >}}
|
||||
: When enabled, creates a `hugo_stats.json` file in the root of your project. This file contains arrays of the `class` attributes, `id` attributes, and tags of every HTML element within your published site. Use this file as data source when [removing unused CSS] from your site. This process is also known as pruning, purging, or tree shaking.
|
||||
|
||||
[removing unused CSS]: /hugo-pipes/postprocess/#css-purging-with-postcss
|
||||
|
||||
Exclude `class` attributes, `id` attributes, or tags from `hugo_stats.json` with the `disableClasses`, `disableIDs`, and `disableTags` keys.
|
||||
|
||||
{{% note %}}
|
||||
With v0.115.0 and earlier this feature was enabled by setting `writeStats` to `true`. Although still functional, the `writeStats` key will be deprecated in a future release.
|
||||
|
||||
Given that CSS purging is typically limited to production builds, place the `buildStats` object below [config/production].
|
||||
|
||||
[config/production]: /getting-started/configuration/#configuration-directory
|
||||
|
||||
Built for speed, there may be "false positive" detections (e.g., HTML elements that are not HTML elements) while parsing the published site. These "false positives" are infrequent and inconsequential.
|
||||
{{% /note %}}
|
||||
|
||||
Due to the nature of partial server builds, new HTML entities are added while the server is running, but old values will not be removed until you restart the server or run a regular `hugo` build.
|
||||
|
||||
cachebusters
|
||||
: See [Configure Cache Busters](#configure-cache-busters)
|
||||
|
||||
noJSConfigInAssets
|
||||
: Turn off writing a `jsconfig.json` into your `/assets` folder with mapping of imports from running [js.Build](/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written.
|
||||
|
||||
useResourceCacheWhen
|
||||
: When to use the cached resources in `/resources/_gen` for PostCSS and ToCSS. Valid values are `never`, `always` and `fallback`. The last value means that the cache will be tried if PostCSS/extended version is not available.
|
||||
|
||||
## Configure cache busters
|
||||
|
||||
{{< new-in 0.112.0 >}}
|
||||
|
||||
The `build.cachebusters` configuration option was added to support development using Tailwind 3.x's JIT compiler where a `build` configuration may look like this:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[build]
|
||||
[build.buildStats]
|
||||
enable = true
|
||||
[[build.cachebusters]]
|
||||
source = "assets/watching/hugo_stats\\.json"
|
||||
target = "styles\\.css"
|
||||
[[build.cachebusters]]
|
||||
source = "(postcss|tailwind)\\.config\\.js"
|
||||
target = "css"
|
||||
[[build.cachebusters]]
|
||||
source = "assets/.*\\.(js|ts|jsx|tsx)"
|
||||
target = "js"
|
||||
[[build.cachebusters]]
|
||||
source = "assets/.*\\.(.*)$"
|
||||
target = "$1"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
When `buildStats` {{< new-in 0.115.1 >}} is enabled, Hugo writes a `hugo_stats.json` file on each build with HTML classes etc. that's used in the rendered output. Changes to this file will trigger a rebuild of the `styles.css` file. You also need to add `hugo_stats.json` to Hugo's server watcher. See [Hugo Starter Tailwind Basic](https://github.com/bep/hugo-starter-tailwind-basic) for a running example.
|
||||
|
||||
source
|
||||
: A regexp matching file(s) relative to one of the virtual component directories in Hugo, typically `assets/...`.
|
||||
|
||||
target
|
||||
: A regexp matching the keys in the resource cache that should be expired when `source` changes. You can use the matching regexp groups from `source` in the expression, e.g. `$1`.
|
||||
|
||||
## Configure server
|
||||
|
||||
This is only relevant when running `hugo server`, and it allows to set HTTP headers during development, which allows you to test out your Content Security Policy and similar. The configuration format matches [Netlify's](https://docs.netlify.com/routing/headers/#syntax-for-the-netlify-configuration-file) with slightly more powerful [Glob matching](https://github.com/gobwas/glob):
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[server]
|
||||
[[server.headers]]
|
||||
for = "/**"
|
||||
|
||||
[server.headers.values]
|
||||
X-Frame-Options = "DENY"
|
||||
X-XSS-Protection = "1; mode=block"
|
||||
X-Content-Type-Options = "nosniff"
|
||||
Referrer-Policy = "strict-origin-when-cross-origin"
|
||||
Content-Security-Policy = "script-src localhost:1313"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Since this is "development only", it may make sense to put it below the `development` environment:
|
||||
|
||||
{{< code-toggle file=config/development/server >}}
|
||||
[[headers]]
|
||||
for = "/**"
|
||||
|
||||
[headers.values]
|
||||
X-Frame-Options = "DENY"
|
||||
X-XSS-Protection = "1; mode=block"
|
||||
X-Content-Type-Options = "nosniff"
|
||||
Referrer-Policy = "strict-origin-when-cross-origin"
|
||||
Content-Security-Policy = "script-src localhost:1313"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
You can also specify simple redirects rules for the server. The syntax is again similar to Netlify's.
|
||||
|
||||
Note that a `status` code of 200 will trigger a [URL rewrite](https://docs.netlify.com/routing/redirects/rewrites-proxies/), which is what you want in SPA situations, e.g:
|
||||
|
||||
{{< code-toggle file=config/development/server >}}
|
||||
[[redirects]]
|
||||
from = "/myspa/**"
|
||||
to = "/myspa/"
|
||||
status = 200
|
||||
force = false
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Setting `force=true` will make a redirect even if there is existing content in the path. Note that before Hugo 0.76 `force` was the default behavior, but this is inline with how Netlify does it.
|
||||
|
||||
## 404 server error page {#_404-server-error-page}
|
||||
|
||||
{{< new-in 0.103.0 >}}
|
||||
|
||||
Hugo will, by default, render all 404 errors when running `hugo server` with the `404.html` template. Note that if you have already added one or more redirects to your [server configuration](#configure-server), you need to add the 404 redirect explicitly, e.g:
|
||||
|
||||
{{< code-toggle file=config/development/server >}}
|
||||
[[redirects]]
|
||||
from = "/**"
|
||||
to = "/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.
|
||||
|
||||
Change this behavior by setting `titleCaseStyle` in your site configuration to any of the values below:
|
||||
|
||||
ap
|
||||
: Use the capitalization rules published in the [Associated Press Stylebook].
|
||||
|
||||
chicago
|
||||
: Use the capitalization rules published in the [Chicago Manual of Style].
|
||||
|
||||
go
|
||||
: Capitalize the first letter of every word.
|
||||
|
||||
firstupper
|
||||
: Capitalize the first letter of the first word.
|
||||
|
||||
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
|
||||
[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
|
||||
|
||||
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.
|
||||
|
||||
## Configure with environment variables
|
||||
|
||||
In addition to the 3 configuration options already mentioned, configuration key-values can be defined through operating system environment variables.
|
||||
|
||||
For example, the following command will effectively set a website's title on Unix-like systems:
|
||||
|
||||
```txt
|
||||
$ env HUGO_TITLE="Some Title" hugo
|
||||
```
|
||||
|
||||
This is really useful if you use a service such as Netlify to deploy your site. Look at the Hugo docs [Netlify configuration file](https://github.com/gohugoio/hugoDocs/blob/master/netlify.toml) for an example.
|
||||
|
||||
{{% note %}}
|
||||
Names must be prefixed with `HUGO_` and the configuration key must be set in uppercase when setting operating system environment variables.
|
||||
|
||||
To set configuration parameters, prefix the name with `HUGO_PARAMS_`
|
||||
{{% /note %}}
|
||||
|
||||
If you are using snake_cased variable names, the above will not work. Hugo determines the delimiter to use by the first character after `HUGO`. This allows you to define environment variables on the form `HUGOxPARAMSxAPI_KEY=abcdefgh`, using any [allowed](https://stackoverflow.com/questions/2821043/allowed-characters-in-linux-environment-variable-names#:~:text=So%20names%20may%20contain%20any,not%20begin%20with%20a%20digit.) delimiter.
|
||||
|
||||
## Ignore content and data files when rendering
|
||||
|
||||
{{% note %}}
|
||||
This works, but we recommend you use the newer and more powerful [includeFiles and excludeFiles](/hugo-modules/configuration/#module-configuration-mounts) mount options.
|
||||
{{% /note %}}
|
||||
|
||||
To exclude specific files from the `content`, `data`, and `i18n` directories when rendering your site, set `ignoreFiles` to one or more regular expressions to match against the absolute file path.
|
||||
|
||||
To ignore files ending with `.foo` or `.boo`:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
ignoreFiles = ['\.foo$', '\.boo$']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To ignore a file using the absolute file path:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
ignoreFiles = ['^/home/user/project/content/test\.md$']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Configure front matter
|
||||
|
||||
### Configure dates
|
||||
|
||||
Dates are important in Hugo, and you can configure how Hugo assigns dates to your content pages. You do this by adding a `frontmatter` section to your `hugo.toml`.
|
||||
|
||||
The default configuration is:
|
||||
|
||||
{{< code-toggle config=frontmatter />}}
|
||||
|
||||
If you, as an example, have a non-standard date parameter in some of your content, you can override the setting for `date`:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[frontmatter]
|
||||
date = ["myDate", ":default"]
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The `:default` is a shortcut to the default settings. The above will set `.Date` to the date value in `myDate` if present, if not we will look in `date`,`publishDate`, `lastmod` and pick the first valid date.
|
||||
|
||||
In the list to the right, values starting with ":" are date handlers with a special meaning (see below). The others are just names of date parameters (case insensitive) in your front matter configuration. Also note that Hugo have some built-in aliases to the above: `lastmod` => `modified`, `publishDate` => `pubdate`, `published` and `expiryDate` => `unpublishdate`. With that, as an example, using `pubDate` as a date in front matter, will, by default, be assigned to `.PublishDate`.
|
||||
|
||||
The special date handlers are:
|
||||
|
||||
`:fileModTime`
|
||||
: Fetches the date from the content file's last modification timestamp.
|
||||
|
||||
An example:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[frontmatter]
|
||||
lastmod = ["lastmod", ":fileModTime", ":default"]
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The above will try first to extract the value for `.Lastmod` starting with the `lastmod` front matter parameter, then the content file's modification timestamp. The last, `:default` should not be needed here, but Hugo will finally look for a valid date in `:git`, `date` and then `publishDate`.
|
||||
|
||||
`:filename`
|
||||
: Fetches the date from the content file's file name. For example, `2018-02-22-mypage.md` will extract the date `2018-02-22`. Also, if `slug` is not set, `mypage` will be used as the value for `.Slug`.
|
||||
|
||||
An example:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[frontmatter]
|
||||
date = [":filename", ":default"]
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The above will try first to extract the value for `.Date` from the file name, then it will look in front matter parameters `date`, `publishDate` and lastly `lastmod`.
|
||||
|
||||
`: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.
|
||||
|
||||
[tdewolff/minify]: https://github.com/tdewolff/minify
|
||||
|
||||
Default configuration:
|
||||
|
||||
{{< code-toggle config=minify />}}
|
||||
|
||||
## Configure file caches
|
||||
|
||||
Since Hugo 0.52 you can configure more than just the `cacheDir`. This is the default configuration:
|
||||
|
||||
{{< code-toggle config=caches />}}
|
||||
|
||||
You can override any of these cache settings in your own `hugo.toml`.
|
||||
|
||||
### The keywords explained
|
||||
|
||||
cacheDir
|
||||
: (`string`) See [Configure cacheDir](#configure-cachedir).
|
||||
|
||||
project
|
||||
: (`string`) The base directory name of the current Hugo project. This means that, in its default setting, every project will have separated file caches, which means that when you do `hugo --gc` you will not touch files related to other Hugo projects running on the same PC.
|
||||
|
||||
resourceDir
|
||||
: (`string`) This is the value of the `resourceDir` configuration option.
|
||||
|
||||
maxAge
|
||||
: (`string`) This is the duration before a cache entry will be evicted, -1 means forever and 0 effectively turns that particular cache off. Uses Go's `time.Duration`, so valid values are `"10s"` (10 seconds), `"10m"` (10 minutes) and `"10h"` (10 hours).
|
||||
|
||||
dir
|
||||
: (`string`) The absolute path to where the files for this cache will be stored. Allowed starting placeholders are `:cacheDir` and `:resourceDir` (see above).
|
||||
|
||||
## Configure cacheDir
|
||||
|
||||
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`.
|
||||
|
||||
If this is not set, Hugo will use, in order of preference:
|
||||
|
||||
1. If running on Netlify: `/opt/build/cache/hugo_cache/`. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other CI vendors, please read their documentation. For an CircleCI example, see [this configuration](https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml).
|
||||
1. In a `hugo_cache` directory below the OS user cache directory as defined by Go's [os.UserCacheDir](https://pkg.go.dev/os#UserCacheDir). On Unix systems, this is `$XDG_CACHE_HOME` as specified by [basedir-spec-latest](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) if non-empty, else `$HOME/.cache`. On MacOS, this is `$HOME/Library/Caches`. On Windows, this is`%LocalAppData%`. On Plan 9, this is `$home/lib/cache`. {{< new-in 0.116.0 >}}
|
||||
1. In a `hugo_cache_$USER` directory below the OS temp dir.
|
||||
|
||||
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
|
||||
[lookup order]: /templates/lookup-order/
|
||||
[Output Formats]: /templates/output-formats/
|
||||
[templates]: /templates/
|
||||
[static-files]: /content-management/static-files/
|
@@ -1,212 +0,0 @@
|
||||
---
|
||||
title: Directory structure
|
||||
description: Each Hugo project is a directory, with subdirectories that contribute to the content, structure, behavior, and presentation of your site.
|
||||
categories: [getting started,fundamentals]
|
||||
keywords: [source, organization, directories]
|
||||
menu:
|
||||
docs:
|
||||
parent: getting-started
|
||||
weight: 30
|
||||
weight: 30
|
||||
toc: true
|
||||
aliases: [/overview/source-directory/]
|
||||
---
|
||||
|
||||
## Site skeleton
|
||||
|
||||
Hugo generates a project skeleton when you create a new site. For example, this command:
|
||||
|
||||
```sh
|
||||
hugo new site my-site
|
||||
```
|
||||
|
||||
Creates this directory structure:
|
||||
|
||||
```txt
|
||||
my-site/
|
||||
├── archetypes/
|
||||
│ └── default.md
|
||||
├── assets/
|
||||
├── content/
|
||||
├── data/
|
||||
├── i18n/
|
||||
├── layouts/
|
||||
├── static/
|
||||
├── themes/
|
||||
└── hugo.toml <-- site configuration
|
||||
```
|
||||
|
||||
Depending on requirements, you may wish to organize your site configuration into subdirectories:
|
||||
|
||||
```txt
|
||||
my-site/
|
||||
├── archetypes/
|
||||
│ └── default.md
|
||||
├── assets/
|
||||
├── config/ <-- site configuration
|
||||
│ └── _default/
|
||||
│ └── hugo.toml
|
||||
├── content/
|
||||
├── data/
|
||||
├── i18n/
|
||||
├── layouts/
|
||||
├── static/
|
||||
└── themes/
|
||||
```
|
||||
|
||||
When you build your site, Hugo creates a `public` directory, and typically a `resources` directory as well:
|
||||
|
||||
```txt
|
||||
my-site/
|
||||
├── archetypes/
|
||||
│ └── default.md
|
||||
├── assets/
|
||||
├── config/
|
||||
│ └── _default/
|
||||
│ └── hugo.toml
|
||||
├── content/
|
||||
├── data/
|
||||
├── i18n/
|
||||
├── layouts/
|
||||
├── public/ <-- created when you build your site
|
||||
├── resources/ <-- created when you build your site
|
||||
├── static/
|
||||
└── themes/
|
||||
```
|
||||
|
||||
## Directories
|
||||
|
||||
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/).
|
||||
|
||||
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/).
|
||||
|
||||
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).
|
||||
|
||||
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/).
|
||||
|
||||
data
|
||||
: The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/templates/data-templates/).
|
||||
|
||||
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` command. 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. See [details](/content-management/static-files/).
|
||||
|
||||
themes
|
||||
: The `themes` directory contains one or more [themes](/getting-started/glossary/#theme), each in its own subdirectory.
|
||||
|
||||
## Union file system
|
||||
|
||||
Hugo creates a union file system, allowing you to mount two or more directories to the same location. For example, let's say your home directory contains a Hugo project in one directory, and shared content in another:
|
||||
|
||||
```text
|
||||
home/
|
||||
└── user/
|
||||
├── my-site/
|
||||
│ ├── content/
|
||||
│ │ ├── books/
|
||||
│ │ │ ├── _index.md
|
||||
│ │ │ ├── book-1.md
|
||||
│ │ │ └── book-2.md
|
||||
│ │ └── _index.md
|
||||
│ ├── themes/
|
||||
│ │ └── my-theme/
|
||||
│ └── hugo.toml
|
||||
└── shared-content/
|
||||
└── films/
|
||||
├── _index.md
|
||||
├── film-1.md
|
||||
└── film-2.md
|
||||
```
|
||||
|
||||
You can include the shared content when you build your site using mounts. In your site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[module.mounts]]
|
||||
source = 'content'
|
||||
target = 'content'
|
||||
|
||||
[[module.mounts]]
|
||||
source = '/home/user/shared-content'
|
||||
target = 'content'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
{{% 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.
|
||||
{{% /note %}}
|
||||
|
||||
After mounting, the union file system has this structure:
|
||||
|
||||
```text
|
||||
home/
|
||||
└── user/
|
||||
└── my-site/
|
||||
├── content/
|
||||
│ ├── books/
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── book-1.md
|
||||
│ │ └── book-2.md
|
||||
│ ├── films/
|
||||
│ │ ├── _index.md
|
||||
│ │ ├── film-1.md
|
||||
│ │ └── film-2.md
|
||||
│ └── _index.md
|
||||
├── themes/
|
||||
│ └── my-theme/
|
||||
└── hugo.toml
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
When two or more files have the same path, the order of precedence follows the order of the mounts. For example, if the shared content directory contains `books/book-1.md`, it will be ignored because the project's content directory was mounted first.
|
||||
{{% /note %}}
|
||||
|
||||
You can mount directories to `archetypes`, `assets`, `content`, `data`, `i18n`, `layouts`, and `static`. See [details](/hugo-modules/configuration/#module-configuration-mounts).
|
||||
|
||||
You can also mount directories from Git repositories using Hugo Modules. See [details](/hugo-modules/).
|
||||
|
||||
## Theme skeleton
|
||||
|
||||
Hugo generates a functional theme skeleton when you create a new theme. For example, this command:
|
||||
|
||||
```text
|
||||
hugo new theme my-theme
|
||||
```
|
||||
|
||||
Creates this directory structure (subdirectories not shown):
|
||||
|
||||
```text
|
||||
my-theme/
|
||||
├── archetypes/
|
||||
├── assets/
|
||||
├── content/
|
||||
├── data/
|
||||
├── i18n/
|
||||
├── layouts/
|
||||
├── static/
|
||||
├── LICENSE
|
||||
├── README.md
|
||||
├── hugo.toml
|
||||
└── theme.toml
|
||||
```
|
||||
|
||||
Using the union file system described above, Hugo mounts each of these directories to the corresponding location in the project. When two files have the same path, the file in the project directory takes precedence. This allows you, for example, to override a theme's template by placing a copy in the same location within the project directory.
|
||||
|
||||
If you are simultaneously using components from two or more themes or modules, and there's a path collision, the first mount takes precedence.
|
Binary file not shown.
Before Width: | Height: | Size: 65 KiB |
@@ -1,37 +0,0 @@
|
||||
---
|
||||
title: External learning resources
|
||||
description: A list of tutorials and books on Hugo.
|
||||
categories: [getting started]
|
||||
keywords: [books, tutorials, learning, usage]
|
||||
menu:
|
||||
docs:
|
||||
parent: getting-started
|
||||
weight: 70
|
||||
weight: 70
|
||||
---
|
||||
|
||||
## 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 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.
|
||||
|
||||
## Beginner tutorials
|
||||
|
||||
### Hugo tutorial by CloudCannon
|
||||
|
||||
[Step-by-step written tutorial](https://cloudcannon.com/community/learn/hugo-beginner-tutorial/) to teach you the basics of creating a Hugo site.
|
||||
|
||||
## 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).
|
||||
|
||||
* [Introduction to building your first Hugo site](https://cloudcannon.com/community/learn/hugo-beginner-tutorial/) by Mike Neumegen.
|
@@ -1,389 +0,0 @@
|
||||
---
|
||||
title: Glossary of terms
|
||||
description: Terms commonly used throughout the documentation.
|
||||
categories: [getting started]
|
||||
keywords: [glossary]
|
||||
menu:
|
||||
docs:
|
||||
parent: getting-started
|
||||
weight: 60
|
||||
weight: 60
|
||||
# Use level 6 headings for each term in the glossary.
|
||||
---
|
||||
|
||||
###### action
|
||||
|
||||
See [template action](#template-action).
|
||||
|
||||
###### archetype
|
||||
|
||||
A template for new content. See [details](/content-management/archetypes/).
|
||||
|
||||
###### argument
|
||||
|
||||
A [scalar](#scalar), [array](#array), [slice](#slice), [map](#map), or [object](#object) passed to a [function](#function), [method](#method), or [shortcode](#shortcode).
|
||||
|
||||
###### array
|
||||
|
||||
A numbered sequence of elements. Unlike Go's [slice](#slice) data type, an array has a fixed length. [Elements](#element) within an array can be [scalars](#scalar), slices, [maps](#map), pages, or other arrays. See the [Go documentation](https://go.dev/ref/spec#Array_types) for details.
|
||||
|
||||
###### bool
|
||||
|
||||
See [boolean](#boolean).
|
||||
|
||||
###### boolean
|
||||
|
||||
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/).
|
||||
|
||||
###### build
|
||||
|
||||
To generate a static site that includes HTML files and assets such as images, CSS, and JavaScript. The build process includes rendering and resource transformations.
|
||||
|
||||
###### bundle
|
||||
|
||||
See [page bundle](#page-bundle).
|
||||
|
||||
###### cache
|
||||
|
||||
A software component that stores data so that future requests for the same data are faster.
|
||||
|
||||
###### chain
|
||||
|
||||
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`.
|
||||
|
||||
###### collection
|
||||
|
||||
An [array](#array), [slice](#slice), or [map](#map).
|
||||
|
||||
###### 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/).
|
||||
|
||||
###### content type
|
||||
|
||||
A classification of content inferred from the top-level directory name or the `type` set in [front matter](#front-matter). Pages in the root of the content directory, including the home page, are of type "page". Accessed via `.Page.Type` in [templates](#template). See [details](/content-management/types/).
|
||||
|
||||
###### content view
|
||||
|
||||
A template called with the `.Page.Render` method. See [details](/templates/views/).
|
||||
|
||||
###### 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).
|
||||
|
||||
###### default sort order
|
||||
|
||||
The default sort order for page collections. Hugo sorts by [weight](#weight), then by date (descending), then by link title, and then by file path.
|
||||
|
||||
###### element
|
||||
|
||||
A member of a slice or array.
|
||||
|
||||
###### environment
|
||||
|
||||
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.
|
||||
|
||||
To determine the current environment within a template, use the [`hugo.Environment`] function.
|
||||
|
||||
[`hugo.Environment`]: /functions/hugo/environment
|
||||
|
||||
###### field
|
||||
|
||||
A predefined key/value pair in front matter such as `date` or `title`. See also [parameter](#parameter).
|
||||
|
||||
|
||||
###### flag
|
||||
|
||||
An option passed to a command-line program, beginning with one or two hyphens. See [details](/commands/hugo/).
|
||||
|
||||
###### float
|
||||
|
||||
See [floating point](#floating-point).
|
||||
|
||||
###### floating point
|
||||
|
||||
A numeric data type with a fractional component. For example, `3.14159`.
|
||||
|
||||
###### fragment
|
||||
|
||||
The final segment of a URL, beginning with a hash (`#`) mark, that references an `id` attribute of an HTML element on the page.
|
||||
|
||||
###### front matter
|
||||
|
||||
Metadata at the beginning of each content page, separated from the content by format-specific delimiters. See [details](/content-management/front-matter/).
|
||||
|
||||
###### function
|
||||
|
||||
Used within a [template action](#template-action), a function takes one or more [arguments](#argument) and returns a value. Unlike [methods](#method), functions are not associated with an [object](#object). See [details](/functions/).
|
||||
|
||||
###### global resource
|
||||
|
||||
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
|
||||
|
||||
###### identifier
|
||||
|
||||
A string that represents a variable, method, object, or field. It must conform to Go's [language specification](https://go.dev/ref/spec#Identifiers), beginning with a letter or underscore, followed by zero or more letters, digits, or underscores.
|
||||
|
||||
###### int
|
||||
|
||||
See [integer](#integer).
|
||||
|
||||
###### integer
|
||||
|
||||
A numeric data type without a fractional component. For example, `42`.
|
||||
|
||||
###### internationalization
|
||||
|
||||
Software design and development efforts that enable [localization](#localization). See the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated i18n.
|
||||
|
||||
###### interval
|
||||
|
||||
An [interval](https://en.wikipedia.org/wiki/Interval_(mathematics)) is a range of numbers between two endpoints: closed, open, or half-open.
|
||||
|
||||
- A _closed_ interval, denoted by brackets, includes its endpoints. For example, [0, 1] is the interval where `0 <= x <= 1`.
|
||||
|
||||
- An _open_ interval, denoted by parentheses, excludes its endpoints. For example, (0, 1) is the interval where `0 < x < 1`.
|
||||
|
||||
- A _half-open_ interval includes only one of its endpoints. For example, (0, 1] is the _left-open_ interval where `0 < x <= 1`, while [0, 1) is the _right-open_ interval where `0 <= x < 1`.
|
||||
|
||||
###### kind
|
||||
|
||||
See [page kind](#page-kind).
|
||||
|
||||
###### layout
|
||||
|
||||
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/).
|
||||
|
||||
###### list page
|
||||
|
||||
Any [page kind](#page-kind) that receives a page [collection](#collection) in [context](#context). This includes the home page, [section pages](#section-page), [taxonomy pages](#taxonomy-page), and [term pages](#term-page).
|
||||
|
||||
###### localization
|
||||
|
||||
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.
|
||||
|
||||
###### 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
|
||||
|
||||
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
|
||||
|
||||
To transform a data structure into a serialized object. For example, transforming a [map](#map) into a JSON string. See [unmarshal](#unmarshal).
|
||||
|
||||
###### method
|
||||
|
||||
Used within a [template action](#template-action) and associated with an [object](#object), a method takes zero or more [arguments](#argument) and either returns a value or performs an action. For example, `.IsHome` is a method on the `.Page` object which returns `true` if the current page is the home page. See also [function](#function).
|
||||
|
||||
###### module
|
||||
|
||||
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/).
|
||||
|
||||
###### object
|
||||
|
||||
A data structure with or without associated [methods](#method).
|
||||
|
||||
###### ordered taxonomy
|
||||
|
||||
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
|
||||
|
||||
###### output format
|
||||
|
||||
{{% include "methods/page/_common/output-format-definition.md" %}}
|
||||
|
||||
###### page bundle
|
||||
|
||||
A directory that encapsulates both content and associated [resources](#resource). There are two types of page bundles: [leaf bundles](#leaf-bundle) and [branch bundles](#branch-bundle). See [details](/content-management/page-bundles/).
|
||||
|
||||
###### page collection
|
||||
|
||||
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).
|
||||
|
||||
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.
|
||||
|
||||
###### page resource
|
||||
|
||||
A file within a [page bundle](#page-bundle). Capture one or more page resources using any of the [`Resources`] methods on a `Page` object.
|
||||
|
||||
[`Resources`]: /methods/page/resources/#methods
|
||||
|
||||
###### pager
|
||||
|
||||
Created during [pagination](#pagination), a pager contains a subset of a section list, and navigation links to other pagers.
|
||||
|
||||
###### paginate
|
||||
|
||||
To split a [section](#section) list into two or more [pagers](#pager) See [details](/templates/pagination/).
|
||||
|
||||
###### pagination
|
||||
|
||||
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).
|
||||
|
||||
###### partial
|
||||
|
||||
A [template](#template) called from any other template including [shortcodes](#shortcode), [render hooks](#render-hook), and other partials. A partial either renders something or returns something. A partial can also call itself, for example, to [walk](#walk) a data structure.
|
||||
|
||||
###### permalink
|
||||
|
||||
The absolute URL of a published resource or a rendered page, including scheme and host.
|
||||
|
||||
###### pipe
|
||||
|
||||
See [pipeline](#pipeline).
|
||||
|
||||
###### pipeline
|
||||
|
||||
Within a [template action](#template-action), a pipeline is a possibly chained sequence of values, [function](#function) calls, or [method](#method) calls. Functions and methods in the pipeline may take multiple [arguments](#argument).
|
||||
|
||||
A pipeline may be *chained* by separating a sequence of commands with pipeline characters "|". In a chained pipeline, the result of each command is passed as the last argument to the following command. The output of the final command in the pipeline is the value of the pipeline. See the [Go documentation](https://pkg.go.dev/text/template#hdr-Pipelines) for details.
|
||||
|
||||
###### publish
|
||||
|
||||
See [build](#build).
|
||||
|
||||
###### regular page
|
||||
|
||||
Content with the "page" [page kind](#page-kind). See also [section page](#section-page).
|
||||
|
||||
###### relative permalink
|
||||
|
||||
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/).
|
||||
|
||||
###### remote resource
|
||||
|
||||
A file on a remote server, accessible via HTTP or HTTPS with the [`resources.GetRemote`](/functions/resources/getremote) function.
|
||||
|
||||
###### resource
|
||||
|
||||
Any file consumed by the build process to augment or generate content, structure, behavior, or presentation. For example: images, videos, content snippets, CSS, Sass, JavaScript, and data.
|
||||
|
||||
Hugo supports three types of resources: [global](#global-resource), [page](#page-resource), and [remote](#remote-resource)
|
||||
|
||||
###### 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.
|
||||
|
||||
[`Scratch`]: /methods/page/scratch
|
||||
[`Store`]: /methods/page/store
|
||||
[`newScratch`]: /functions/collections/newscratch
|
||||
|
||||
###### section
|
||||
|
||||
A top-level content directory, or any content directory with an _index.md file. A content directory with an _index.md file is also known as a [branch bundle](/getting-started/glossary/#branch-bundle). Section templates receive one or more page [collections](#collection) in [context](#context). See [details](/content-management/sections/).
|
||||
|
||||
###### section page
|
||||
|
||||
Content with the "section" [page kind](#page-kind). Typically a listing of [regular pages](#regular-page) and/or [section pages](#section-page) within the current [section](#section). See also [regular page](#regular-page).
|
||||
|
||||
###### shortcode
|
||||
|
||||
A [template](#template) called from within markdown, taking zero or more [arguments](#argument). See [details](/content-management/shortcodes/).
|
||||
|
||||
###### slice
|
||||
|
||||
A numbered sequence of elements. Unlike Go's [array](#array) data type, slices are dynamically sized. [Elements](#element) within a slice can be [scalars](#scalar), [arrays](#array), [maps](#map), pages, or other slices. See the [Go documentation](https://go.dev/ref/spec#Slice_types) for details.
|
||||
|
||||
###### string
|
||||
|
||||
A sequence of bytes. For example, `"What is 6 times 7?"` .
|
||||
|
||||
###### 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).
|
||||
|
||||
###### taxonomy
|
||||
|
||||
A group of related [terms](#term) used to classify content. For example, a "colors" taxonomy might include the terms "red", "green", and "blue". See [details](/content-management/taxonomies/).
|
||||
|
||||
###### taxonomy object
|
||||
|
||||
A [map](#map) of [terms](#term) and the [weighted pages](#weighted-page) associated with each term.
|
||||
|
||||
###### taxonomy page
|
||||
|
||||
Content with the "taxonomy" [page kind](#page-kind). Typically a listing of [terms](#term) within a given [taxonomy](#taxonomy).
|
||||
|
||||
###### template
|
||||
|
||||
A file with [template actions](#template-action), located within the layouts directory of a project, theme, or module. See [details](/templates/).
|
||||
|
||||
###### template action
|
||||
|
||||
A data evaluation or control structure within a [template](#template), delimited by "{{" and "}}". See the [Go documentation](https://pkg.go.dev/text/template#hdr-Actions) for details.
|
||||
|
||||
###### term
|
||||
|
||||
A member of a [taxonomy](#taxonomy), used to classify content. See [details](/content-management/taxonomies/).
|
||||
|
||||
###### term page
|
||||
|
||||
Content with the "term" [page kind](#page-kind). Typically a listing of [regular pages](#regular-page) and [section pages](#section-page) with a given [term](#term).
|
||||
|
||||
###### theme
|
||||
|
||||
A packaged combination of [archetypes](#archetype), assets, content, data, [templates](#template), translation tables, static files, or configuration settings. A theme may serve as the basis for a new site, or to augment an existing site. See also [module](#module).
|
||||
|
||||
###### token
|
||||
|
||||
An identifier within a format string, beginning with a colon and replaced with a value when rendered. For example, use tokens in format strings for both [permalinks](/content-management/urls/#permalinks) and [dates](/functions/time/format/#localization).
|
||||
|
||||
###### type
|
||||
|
||||
See [content type](#content-type).
|
||||
|
||||
###### unmarshal
|
||||
|
||||
To transform a serialized object into a data structure. For example, transforming a JSON file into a [map](#map) that you can access within a template. See [marshal](#marshal).
|
||||
|
||||
###### 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.
|
||||
|
||||
###### walk
|
||||
|
||||
To recursively traverse a nested data structure. For example, rendering a multilevel menu.
|
||||
|
||||
###### weight
|
||||
|
||||
Used to position an element within a collection sorted by weight. Assign weights using non-zero integers. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted elements are placed at the end of the collection. Weights are typically assigned to pages, menu entries, languages, and output formats.
|
||||
|
||||
###### 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.
|
@@ -1,232 +0,0 @@
|
||||
---
|
||||
title: Quick start
|
||||
description: Learn to create a Hugo site in minutes.
|
||||
categories: [getting started]
|
||||
keywords: [quick start,usage]
|
||||
menu:
|
||||
docs:
|
||||
parent: getting-started
|
||||
weight: 20
|
||||
weight: 20
|
||||
toc: true
|
||||
aliases: [/quickstart/,/overview/quickstart/]
|
||||
minVersion: v0.112.0
|
||||
---
|
||||
|
||||
In this tutorial you will:
|
||||
|
||||
1. Create a site
|
||||
2. Add content
|
||||
3. Configure the site
|
||||
4. Publish the site
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you begin this tutorial you must:
|
||||
|
||||
1. [Install Hugo] (extended edition, {{% param "minVersion" %}} or later)
|
||||
1. [Install Git]
|
||||
|
||||
You must also be comfortable working from the command line.
|
||||
|
||||
## Create a site
|
||||
|
||||
### Commands
|
||||
|
||||
{{% note %}}
|
||||
**If you are a Windows user:**
|
||||
|
||||
- Do not use the Command Prompt
|
||||
- Do not use Windows PowerShell
|
||||
- Run these commands from [PowerShell] or a Linux terminal such as WSL or Git Bash
|
||||
|
||||
PowerShell and Windows PowerShell [are different applications].
|
||||
|
||||
[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows
|
||||
[are different applications]: https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell?view=powershell-7.3
|
||||
{{% /note %}}
|
||||
|
||||
Verify that you have installed Hugo {{% param "minVersion" %}} or later.
|
||||
|
||||
```text
|
||||
hugo version
|
||||
```
|
||||
|
||||
Run these commands to create a Hugo site with the [Ananke] theme. The next section provides an explanation of each command.
|
||||
|
||||
```text
|
||||
hugo new site quickstart
|
||||
cd quickstart
|
||||
git init
|
||||
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
|
||||
echo "theme = 'ananke'" >> hugo.toml
|
||||
hugo server
|
||||
```
|
||||
|
||||
View your site at the URL displayed in your terminal. Press `Ctrl + C` to stop Hugo's development server.
|
||||
|
||||
### Explanation of commands
|
||||
|
||||
Create the [directory structure] for your project in the `quickstart` directory.
|
||||
|
||||
```text
|
||||
hugo new site quickstart
|
||||
```
|
||||
|
||||
Change the current directory to the root of your project.
|
||||
|
||||
```text
|
||||
cd quickstart
|
||||
```
|
||||
|
||||
Initialize an empty Git repository in the current directory.
|
||||
|
||||
```text
|
||||
git init
|
||||
```
|
||||
|
||||
Clone the [Ananke] theme into the `themes` directory, adding it to your project as a [Git submodule].
|
||||
|
||||
```text
|
||||
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
|
||||
```
|
||||
|
||||
Append a line to the site configuration file, indicating the current theme.
|
||||
|
||||
```text
|
||||
echo "theme = 'ananke'" >> hugo.toml
|
||||
```
|
||||
|
||||
Start Hugo's development server to view the site.
|
||||
|
||||
```text
|
||||
hugo server
|
||||
```
|
||||
|
||||
Press `Ctrl + C` to stop Hugo's development server.
|
||||
|
||||
## Add content
|
||||
|
||||
Add a new page to your site.
|
||||
|
||||
```text
|
||||
hugo new content posts/my-first-post.md
|
||||
```
|
||||
|
||||
Hugo created the file in the `content/posts` directory. Open the file with your editor.
|
||||
|
||||
```text
|
||||
+++
|
||||
title = 'My First Post'
|
||||
date = 2024-01-14T07:07:07+01:00
|
||||
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.
|
||||
|
||||
[markdown]: https://commonmark.org/help/
|
||||
|
||||
```text
|
||||
+++
|
||||
title = 'My First Post'
|
||||
date = 2024-01-14T07:07:07+01:00
|
||||
draft = true
|
||||
+++
|
||||
## Introduction
|
||||
|
||||
This is **bold** text, and this is *emphasized* text.
|
||||
|
||||
Visit the [Hugo](https://gohugo.io) website!
|
||||
```
|
||||
|
||||
Save the file, then start Hugo’s development server to view the site. You can run either of the following commands to include draft content.
|
||||
|
||||
```text
|
||||
hugo server --buildDrafts
|
||||
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.
|
||||
|
||||
{{% 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.
|
||||
|
||||
[live testing tool]: https://spec.commonmark.org/dingus/
|
||||
[specification]: https://spec.commonmark.org/
|
||||
{{% /note %}}
|
||||
|
||||
## Configure the site
|
||||
|
||||
With your editor, open the [site configuration] file (`hugo.toml`) in the root of your project.
|
||||
|
||||
```text
|
||||
baseURL = 'https://example.org/'
|
||||
languageCode = 'en-us'
|
||||
title = 'My New Hugo Site'
|
||||
theme = 'ananke'
|
||||
```
|
||||
|
||||
Make the following changes:
|
||||
|
||||
1. Set the `baseURL` for your production site. This value must begin with the protocol and end with a slash, as shown above.
|
||||
|
||||
2. Set the `languageCode` to your language and region.
|
||||
|
||||
3. Set the `title` for your production site.
|
||||
|
||||
Start Hugo's development server to see your changes, remembering to include draft content.
|
||||
|
||||
```text
|
||||
hugo server -D
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Most theme authors provide configuration guidelines and options. Make sure to visit your theme's repository or documentation site for details.
|
||||
|
||||
[The New Dynamic], authors of the Ananke theme, provide [documentation] for configuration and usage. They also provide a [demonstration site].
|
||||
|
||||
[demonstration site]: https://gohugo-ananke-theme-demo.netlify.app/
|
||||
[documentation]: https://github.com/theNewDynamic/gohugo-theme-ananke#readme
|
||||
[The New Dynamic]: https://www.thenewdynamic.com/
|
||||
{{% /note %}}
|
||||
|
||||
## Publish the site
|
||||
|
||||
In this step you will _publish_ your site, but you will not _deploy_ it.
|
||||
|
||||
When you _publish_ your site, Hugo creates the entire static site in the `public` directory in the root of your project. This includes the HTML files, and assets such as images, CSS files, and JavaScript files.
|
||||
|
||||
When you publish your site, you typically do _not_ want to include [draft, future, or expired content]. The command is simple.
|
||||
|
||||
```text
|
||||
hugo
|
||||
```
|
||||
|
||||
To learn how to _deploy_ your site, see the [hosting and deployment] section.
|
||||
|
||||
## Ask for help
|
||||
|
||||
Hugo's [forum] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question.
|
||||
|
||||
## Other resources
|
||||
|
||||
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
|
||||
[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
|
||||
[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
|
||||
[Install Hugo]: /installation/
|
||||
[Requesting Help]: https://discourse.gohugo.io/t/requesting-help/9132
|
||||
[Requesting Help]: https://discourse.gohugo.io/t/requesting-help/9132
|
||||
[site configuration]: /getting-started/configuration/
|
@@ -1,169 +0,0 @@
|
||||
---
|
||||
title: Basic usage
|
||||
description: Hugo's command line interface (CLI) is fully featured but simple to use, even for those with limited experience working from the command line.
|
||||
categories: [getting started]
|
||||
keywords: [usage,livereload,command,flags]
|
||||
menu:
|
||||
docs:
|
||||
parent: getting-started
|
||||
weight: 30
|
||||
weight: 30
|
||||
toc: true
|
||||
aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/]
|
||||
---
|
||||
|
||||
## Test your installation
|
||||
|
||||
After [installing] Hugo, test your installation by running:
|
||||
|
||||
```sh
|
||||
hugo version
|
||||
```
|
||||
|
||||
You should see something like:
|
||||
|
||||
```text
|
||||
hugo v0.105.0-0e3b42b4a9bdeb4d866210819fc6ddcf51582ffa+extended linux/amd64 BuildDate=2022-10-28T12:29:05Z VendorInfo=snap:0.105.0
|
||||
```
|
||||
|
||||
## Display available commands
|
||||
|
||||
To see a list of the available commands and flags:
|
||||
|
||||
```sh
|
||||
hugo help
|
||||
```
|
||||
|
||||
To get help with a subcommand, use the `--help` flag. For example:
|
||||
|
||||
```sh
|
||||
hugo server --help
|
||||
```
|
||||
|
||||
## Build your site
|
||||
|
||||
To build your site, `cd` into your project directory and run:
|
||||
|
||||
```sh
|
||||
hugo
|
||||
```
|
||||
|
||||
The [`hugo`] command builds your site, publishing the files to the `public` directory. To publish your site to a different directory, use the [`--destination`] flag or set [`publishDir`] in your site configuration.
|
||||
|
||||
{{% note %}}
|
||||
Hugo does not clear the `public` directory before building your site. Existing files are overwritten, but not deleted. This behavior is intentional to prevent the inadvertent removal of files that you may have added to the `public` directory after the build.
|
||||
|
||||
Depending on your needs, you may wish to manually clear the contents of the public directory before every build.
|
||||
{{% /note %}}
|
||||
|
||||
## Draft, future, and expired content
|
||||
|
||||
Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [front matter] of your content. By default, Hugo will not publish content when:
|
||||
|
||||
- The `draft` value is `true`
|
||||
- The `date` is in the future
|
||||
- The `publishDate` is in the future
|
||||
- The `expiryDate` is in the past
|
||||
|
||||
You can override the default behavior when running `hugo` or `hugo server` with command line flags:
|
||||
|
||||
```sh
|
||||
hugo --buildDrafts # or -D
|
||||
hugo --buildExpired # or -E
|
||||
hugo --buildFuture # or -F
|
||||
```
|
||||
|
||||
Although you can also set these values in your site configuration, it can lead to unwanted results unless all content authors are aware of, and understand, the settings.
|
||||
|
||||
{{% note %}}
|
||||
As noted above, Hugo does not clear the `public` directory before building your site. Depending on the _current_ evaluation of the four conditions above, after the build your `public` directory may contain extraneous files from a previous build.
|
||||
|
||||
A common practice is to manually clear the contents of the `public` directory before each build to remove draft, expired, and future content.
|
||||
{{% /note %}}
|
||||
|
||||
## Develop and test your site
|
||||
|
||||
To view your site while developing layouts or creating content, `cd` into your project directory and run:
|
||||
|
||||
```sh
|
||||
hugo server
|
||||
```
|
||||
|
||||
The [`hugo server`] command builds your site into memory, and serves your pages using a minimal HTTP server. When you run `hugo server` it will display the URL of your local site:
|
||||
|
||||
```text
|
||||
Web Server is available at http://localhost:1313/
|
||||
```
|
||||
|
||||
While the server is running, it watches your project directory for changes to assets, configuration, content, data, layouts, translations, and static files. When it detects a change, the server rebuilds your site and refreshes your browser using [LiveReload].
|
||||
|
||||
Most Hugo builds are so fast that you may not notice the change unless you are looking directly at your browser.
|
||||
|
||||
### LiveReload
|
||||
|
||||
While the server is running, Hugo injects JavaScript into the generated HTML pages. The LiveReload script creates a connection from the browser to the server via web sockets. You do not need to install any software or browser plugins, nor is any configuration required.
|
||||
|
||||
### Automatic redirection
|
||||
|
||||
When editing content, if you want your browser to automatically redirect to the page you last modified, run:
|
||||
|
||||
```sh
|
||||
hugo server --navigateToChanged
|
||||
```
|
||||
|
||||
## Deploy your site
|
||||
|
||||
{{% note %}}
|
||||
As noted above, Hugo does not clear the public directory before building your site. Manually clear the contents of the public directory before each build to remove draft, expired, and future content.
|
||||
{{% /note %}}
|
||||
|
||||
When you are ready to deploy your site, run:
|
||||
|
||||
```sh
|
||||
hugo
|
||||
```
|
||||
|
||||
This builds your site, publishing the files to the public directory. The directory structure will look something like this:
|
||||
|
||||
```text
|
||||
public/
|
||||
├── categories/
|
||||
│ ├── index.html
|
||||
│ └── index.xml <-- RSS feed for this section
|
||||
├── post/
|
||||
│ ├── my-first-post/
|
||||
│ │ └── index.html
|
||||
│ ├── index.html
|
||||
│ └── index.xml <-- RSS feed for this section
|
||||
├── tags/
|
||||
│ ├── index.html
|
||||
│ └── index.xml <-- RSS feed for this section
|
||||
├── index.html
|
||||
├── index.xml <-- RSS feed for the site
|
||||
└── sitemap.xml
|
||||
```
|
||||
|
||||
In a simple hosting environment, where you typically `ftp`, `rsync`, or `scp` your files to the root of a virtual host, the contents of the `public` directory are all that you need.
|
||||
|
||||
Most of our users deploy their sites using a CI/CD workflow, where a push[^1] to their GitHub or GitLab repository triggers a build and deployment. Popular providers include [AWS Amplify], [CloudCannon], [Cloudflare Pages], [GitHub Pages], [GitLab Pages], and [Netlify].
|
||||
|
||||
Learn more in the [hosting and deployment] section.
|
||||
|
||||
[^1]: The Git repository contains the entire project directory, typically excluding the public directory because the site is built _after_ the push.
|
||||
|
||||
[`--destination`]: /commands/hugo/#options
|
||||
[`hugo server`]: /commands/hugo_server/
|
||||
[`hugo`]: /commands/hugo/
|
||||
[`publishDir`]: /getting-started/configuration/#publishdir
|
||||
[AWS Amplify]: https://aws.amazon.com/amplify/
|
||||
[CloudCannon]: https://cloudcannon.com/
|
||||
[Cloudflare Pages]: https://pages.cloudflare.com/
|
||||
[commands]: /commands/
|
||||
[front matter]: /content-management/front-matter/
|
||||
[GitHub Pages]: https://pages.github.com/
|
||||
[GitLab Pages]: https://docs.gitlab.com/ee/user/project/pages/
|
||||
[hosting and deployment]: /hosting-and-deployment/
|
||||
[hosting]: /hosting-and-deployment/
|
||||
[installing]: /installation/
|
||||
[LiveReload]: https://github.com/livereload/livereload-js
|
||||
[Netlify]: https://www.netlify.com/
|
Reference in New Issue
Block a user