Squashed 'docs/' changes from 785e375f..49809a03

49809a03 Merge commit '20a631b4964fc0ab9137cce1e41774cbc17de044'
20a631b4 Squashed 'themes/gohugoioTheme/' changes from b8202f539..dafc91ff1
8b58f565 Re-generate CLI docs
4653a724 Add Netlify deployment badge
2d6246bc Remove some deprecated site variables
e6777153 Improve Algolia Search Display Styling
1570999f Add missing "." in front of gitlab-ci.yaml example
b922ae7d This adds documentation to the new configDir/Environment logic from .53 (#729)
7cff379f Correctly escape multi-word taxonomy terms in example
2dfeeda4 fix typo by removing stray paren
0870bd9a Fix typo in `paginate` description
91e8be85 Fixes https://github.com/gohugoio/hugo/issues/5609
c1db65ec Make the dummy URL more obvious
b4589ff0 Fix a link
b73dcb9a Consistently use "posts" as section name in examples
7a56abbc Format definitions
a9c6fd9b Minor clarification over the last commit
5c86bdc8 Add alternative instructions for Quick Start for non-git users
dafe7ee9 Add Visual Studio Code plug-ins
110ed19e Update HUGO_VERSION
2abd031a Update page.md
b332f7b9 Update page.md
f5a8c9d4 Update static-files.md
6d0c155c Add note about relative protocol URLs
a13751ac Theme Warning: Remove note about unquoted URLs
4c8f7d68 Incorporate feedback
6f2b9cf0 Update Creating Themes Warning
40d88d98 Fix ToC example to use binary true/false
4a11f3f1 Fix typo
2dbfc0a4 Fix a typo in taxonomies
d63790ef Do not mark UndocumentedFeature issues as stale
d7aff095 Regenerate docs.json
71c0826f Update transform.Unmarshal.md

git-subtree-dir: docs
git-subtree-split: 49809a038b2691637bab7f3f2e385dde654a88b8
This commit is contained in:
Bjørn Erik Pedersen 2019-02-01 09:01:04 +01:00
parent 978856e2ad
commit 5e078383a7
79 changed files with 6251 additions and 391 deletions

1
.github/stale.yml vendored
View file

@ -6,6 +6,7 @@ daysUntilClose: 30
exemptLabels:
- Keep
- Security
- UndocumentedFeature
# Label to use when marking an issue as stale
staleLabel: Stale
# Comment to post when marking an issue as stale. Set to `false` to disable

View file

@ -1,3 +1,5 @@
[![Netlify Status](https://api.netlify.com/api/v1/badges/e0dbbfc7-34f1-4393-a679-c16e80162705/deploy-status)](https://app.netlify.com/sites/gohugoio/deploys)
# Hugo Docs
Documentation site for [Hugo](https://github.com/gohugoio/hugo), the very fast and flexible static site generator built with love in Go.

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo"
slug: hugo
url: /commands/hugo/
@ -55,7 +55,7 @@ hugo [flags]
--stepAnalysis display memory and timing of different steps of the program
--templateMetrics display metrics about template executions
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
-t, --theme string theme to use (located in /themes/THEMENAME/)
-t, --theme strings themes to use (located in /themes/THEMENAME/)
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
@ -75,4 +75,4 @@ hugo [flags]
* [hugo server](/commands/hugo_server/) - A high performance webserver
* [hugo version](/commands/hugo_version/) - Print the version number of Hugo
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,72 +0,0 @@
---
date: 2018-12-12
title: "hugo benchmark"
slug: hugo_benchmark
url: /commands/hugo_benchmark/
---
## hugo benchmark
Benchmark Hugo by building a site a number of times.
### Synopsis
Hugo can build a site many times over and analyze the running process
creating a benchmark.
```
hugo benchmark [flags]
```
### Options
```
-b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/
-D, --buildDrafts include content marked as draft
-E, --buildExpired include expired content
-F, --buildFuture include content with publishdate in the future
--cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
--cleanDestinationDir remove files from destination not found in static directories
-c, --contentDir string filesystem path to content directory
-n, --count int number of times to build the site (default 13)
--cpuprofile string path/filename for the CPU profile file
-d, --destination string filesystem path to write files to
--disableKinds strings disable different kind of pages (home, RSS etc.)
--enableGitInfo add Git revision, date and author info to the pages
-e, --environment string build environment
--forceSyncStatic copy all files when static is changed.
--gc enable to run some cleanup tasks (remove unused cache files) after the build
-h, --help help for benchmark
--i18n-warnings print missing translations
--ignoreCache ignores the cache directory
-l, --layoutDir string filesystem path to layout directory
--memprofile string path/filename for the memory profile file
--minify minify any supported output format (HTML, XML etc.)
--noChmod don't sync permission mode of files
--noTimes don't sync modification time of files
--renderToMemory render to memory (only useful for benchmark testing)
-s, --source string filesystem path to read files relative from
--stepAnalysis display memory and timing of different steps of the program
--templateMetrics display metrics about template executions
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
-t, --theme string theme to use (located in /themes/THEMENAME/)
--themesDir string filesystem path to themes directory
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 12-Dec-2018

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo check"
slug: hugo_check
url: /commands/hugo_check/
@ -36,4 +36,4 @@ Contains some verification checks
* [hugo](/commands/hugo/) - hugo builds your site
* [hugo check ulimit](/commands/hugo_check_ulimit/) - Check system ulimit settings
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo check ulimit"
slug: hugo_check_ulimit
url: /commands/hugo_check_ulimit/
@ -40,4 +40,4 @@ hugo check ulimit [flags]
* [hugo check](/commands/hugo_check/) - Contains some verification checks
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo config"
slug: hugo_config
url: /commands/hugo_config/
@ -40,4 +40,4 @@ hugo config [flags]
* [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo convert"
slug: hugo_convert
url: /commands/hugo_convert/
@ -43,4 +43,4 @@ See convert's subcommands toJSON, toTOML and toYAML for more information.
* [hugo convert toTOML](/commands/hugo_convert_totoml/) - Convert front matter to TOML
* [hugo convert toYAML](/commands/hugo_convert_toyaml/) - Convert front matter to YAML
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo convert toJSON"
slug: hugo_convert_toJSON
url: /commands/hugo_convert_tojson/
@ -43,4 +43,4 @@ hugo convert toJSON [flags]
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo convert toTOML"
slug: hugo_convert_toTOML
url: /commands/hugo_convert_totoml/
@ -43,4 +43,4 @@ hugo convert toTOML [flags]
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo convert toYAML"
slug: hugo_convert_toYAML
url: /commands/hugo_convert_toyaml/
@ -43,4 +43,4 @@ hugo convert toYAML [flags]
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo env"
slug: hugo_env
url: /commands/hugo_env/
@ -39,4 +39,4 @@ hugo env [flags]
* [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo gen"
slug: hugo_gen
url: /commands/hugo_gen/
@ -39,4 +39,4 @@ A collection of several useful generators.
* [hugo gen doc](/commands/hugo_gen_doc/) - Generate Markdown documentation for the Hugo CLI.
* [hugo gen man](/commands/hugo_gen_man/) - Generate man pages for the Hugo CLI
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo gen autocomplete"
slug: hugo_gen_autocomplete
url: /commands/hugo_gen_autocomplete/
@ -57,4 +57,4 @@ hugo gen autocomplete [flags]
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo gen chromastyles"
slug: hugo_gen_chromastyles
url: /commands/hugo_gen_chromastyles/
@ -44,4 +44,4 @@ hugo gen chromastyles [flags]
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo gen doc"
slug: hugo_gen_doc
url: /commands/hugo_gen_doc/
@ -46,4 +46,4 @@ hugo gen doc [flags]
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo gen man"
slug: hugo_gen_man
url: /commands/hugo_gen_man/
@ -42,4 +42,4 @@ hugo gen man [flags]
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo import"
slug: hugo_import
url: /commands/hugo_import/
@ -38,4 +38,4 @@ Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_p
* [hugo](/commands/hugo/) - hugo builds your site
* [hugo import jekyll](/commands/hugo_import_jekyll/) - hugo import from Jekyll
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo import jekyll"
slug: hugo_import_jekyll
url: /commands/hugo_import_jekyll/
@ -42,4 +42,4 @@ hugo import jekyll [flags]
* [hugo import](/commands/hugo_import/) - Import your site from others.
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo list"
slug: hugo_list
url: /commands/hugo_list/
@ -41,4 +41,4 @@ List requires a subcommand, e.g. `hugo list drafts`.
* [hugo list expired](/commands/hugo_list_expired/) - List all posts already expired
* [hugo list future](/commands/hugo_list_future/) - List all posts dated in the future
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo list drafts"
slug: hugo_list_drafts
url: /commands/hugo_list_drafts/
@ -40,4 +40,4 @@ hugo list drafts [flags]
* [hugo list](/commands/hugo_list/) - Listing out various types of content
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo list expired"
slug: hugo_list_expired
url: /commands/hugo_list_expired/
@ -41,4 +41,4 @@ hugo list expired [flags]
* [hugo list](/commands/hugo_list/) - Listing out various types of content
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo list future"
slug: hugo_list_future
url: /commands/hugo_list_future/
@ -41,4 +41,4 @@ hugo list future [flags]
* [hugo list](/commands/hugo_list/) - Listing out various types of content
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo new"
slug: hugo_new
url: /commands/hugo_new/
@ -52,7 +52,7 @@ hugo new [path] [flags]
--stepAnalysis display memory and timing of different steps of the program
--templateMetrics display metrics about template executions
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
-t, --theme string theme to use (located in /themes/THEMENAME/)
-t, --theme strings themes to use (located in /themes/THEMENAME/)
--themesDir string filesystem path to themes directory
```
@ -75,4 +75,4 @@ hugo new [path] [flags]
* [hugo new site](/commands/hugo_new_site/) - Create a new site (skeleton)
* [hugo new theme](/commands/hugo_new_theme/) - Create a new theme
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo new site"
slug: hugo_new_site
url: /commands/hugo_new_site/
@ -44,4 +44,4 @@ hugo new site [path] [flags]
* [hugo new](/commands/hugo_new/) - Create new content for your site
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo new theme"
slug: hugo_new_theme
url: /commands/hugo_new_theme/
@ -43,4 +43,4 @@ hugo new theme [name] [flags]
* [hugo new](/commands/hugo_new/) - Create new content for your site
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo server"
slug: hugo_server
url: /commands/hugo_server/
@ -66,7 +66,7 @@ hugo server [flags]
--stepAnalysis display memory and timing of different steps of the program
--templateMetrics display metrics about template executions
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
-t, --theme string theme to use (located in /themes/THEMENAME/)
-t, --theme strings themes to use (located in /themes/THEMENAME/)
--themesDir string filesystem path to themes directory
-w, --watch watch filesystem for changes and recreate as needed (default true)
```
@ -88,4 +88,4 @@ hugo server [flags]
* [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -1,5 +1,5 @@
---
date: 2018-12-23
date: 2019-01-30
title: "hugo version"
slug: hugo_version
url: /commands/hugo_version/
@ -39,4 +39,4 @@ hugo version [flags]
* [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 23-Dec-2018
###### Auto generated by spf13/cobra on 30-Jan-2019

View file

@ -85,10 +85,10 @@ archetypes
```
```bash
hugo new --kind post-bundle post/my-post
hugo new --kind post-bundle posts/my-post
```
Will create a new folder in `/content/post/my-post` with the same set of files as in the `post-bundle` archetypes folder. All content files (`index.md` etc.) can contain template logic, and will receive the correct `.Site` for the content's language.
Will create a new folder in `/content/posts/my-post` with the same set of files as in the `post-bundle` archetypes folder. All content files (`index.md` etc.) can contain template logic, and will receive the correct `.Site` for the content's language.

View file

@ -35,7 +35,7 @@ The single parameter to `ref` is a string with a content `documentname` (e.g., `
**Paths without a leading `/` will first be tried resolved relative to the current page.**
You will get an error if you document could not be uniquely resolved. The error behaviour can be configured, see below.
You will get an error if your document could not be uniquely resolved. The error behaviour can be configured, see below.
### Link to another language version

View file

@ -111,7 +111,7 @@ The following order is used to determine an Identifier:
This means that `.Title` will be used unless `.LinkTitle` is present, etc. In practice, `.Name` and `.Identifier` are only used to structure relationships and therefore never displayed.
In this example, the top level of the menu is defined in your [site `config` file][config]). All content entries are attached to one of these entries via the `.Parent` field.
In this example, the top level of the menu is defined in your [site `config` file][config]. All content entries are attached to one of these entries via the `.Parent` field.
## Render Menus

View file

@ -47,11 +47,11 @@ Without any additional configuration, the following will just work:
└── content
└── about
| └── _index.md // <- https://example.com/about/
├── post
| ├── firstpost.md // <- https://example.com/post/firstpost/
├── posts
| ├── firstpost.md // <- https://example.com/posts/firstpost/
| ├── happy
| | └── ness.md // <- https://example.com/post/happy/ness/
| └── secondpost.md // <- https://example.com/post/secondpost/
| | └── ness.md // <- https://example.com/posts/happy/ness/
| └── secondpost.md // <- https://example.com/posts/secondpost/
└── quote
├── first.md // <- https://example.com/quote/first/
└── second.md // <- https://example.com/quote/second/

View file

@ -23,7 +23,7 @@ Name
: Default value is the filename (relative to the owning page). Can be set in front matter.
Title
: Default blank. Can be set in front matter.
: Default value is the same as `.Name`. Can be set in front matter.
Permalink
: The absolute URL to the resource. Resources of type `page` will have no value.

View file

@ -14,7 +14,7 @@ toc: true
---
By default, the `static/` directory in the site project is used for
all **static files** (e.g. stylesheets, JavaScript, images).
all **static files** (e.g. stylesheets, JavaScript, images). The static files are served on the site root path (eg. if you have the file `static/image.png` you can access it using `http://{server-url}/image.png`, to include it in a document you can use `![Example image](/image.png) )`.
Hugo can be configured to look into a different directory, or even
**multiple directories** for such static files by configuring the

View file

@ -86,7 +86,7 @@ Moonrise Kingdom <- Value
Hugo natively supports taxonomies.
Without adding a single line to your [site config][config] file, Hugo will automatically create taxonomies for `tags` and `categories`. That would be same as manually [configuring your taxonomies](#configuring-taxonomies) as below:
Without adding a single line to your [site config][config] file, Hugo will automatically create taxonomies for `tags` and `categories`. That would be the same as manually [configuring your taxonomies](#configuring-taxonomies) as below:
{{< code-toggle copy="false" >}}
[taxonomies]

View file

@ -74,7 +74,7 @@ The following is an example of a very basic [single page template][]:
The following is a [partial template][partials] that adds slightly more logic for page-level control over your table of contents. It assumes you are using a `toc` field in your content's [front matter][] that, unless specifically set to `false`, will add a TOC to any page with a `.WordCount` (see [Page Variables][pagevars]) greater than 400. This example also demonstrates how to use [conditionals][] in your templating:
{{< code file="layouts/partials/toc.html" download="toc.html" >}}
{{ if and (gt .WordCount 400 ) (ne .Params.toc "false") }}
{{ if and (gt .WordCount 400 ) (.Params.toc) }}
<aside>
<header>
<h2>{{.Title}}</h2>

View file

@ -27,16 +27,16 @@ The `permalinks` option in your [site configuration][config] allows you to adjus
These examples use the default values for `publishDir` and `contentDir`; i.e., `public` and `content`, respectively. You can override the default values in your [site's `config` file](/getting-started/configuration/).
{{% /note %}}
For example, if one of your [sections][] is called `post` and you want to adjust the canonical path to be hierarchical based on the year, month, and post title, you could set up the following configurations in YAML and TOML, respectively.
For example, if one of your [sections][] is called `posts` and you want to adjust the canonical path to be hierarchical based on the year, month, and post title, you could set up the following configurations in YAML and TOML, respectively.
### Permalinks Configuration Example
{{< code-toggle file="config" copy="false" >}}
permalinks:
post: /:year/:month/:title/
posts: /:year/:month/:title/
{{< /code-toggle >}}
Only the content under `post/` will have the new URL structure. For example, the file `content/post/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `https://example.com/2017/02/sample-entry/`.
Only the content under `posts/` will have the new URL structure. For example, the file `content/posts/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `https://example.com/2017/02/sample-entry/`.
You can also configure permalinks of taxonomies with the same syntax, by using the plural form of the taxonomy instead of the section. You will probably only want to use the configuration values `:slug` or `:title`.
@ -199,11 +199,11 @@ See [Content Organization][contentorg] for more details on paths.
└── content
└── about
| └── _index.md // <- https://example.com/about/
├── post
| ├── firstpost.md // <- https://example.com/post/firstpost/
├── posts
| ├── firstpost.md // <- https://example.com/posts/firstpost/
| ├── happy
| | └── ness.md // <- https://example.com/post/happy/ness/
| └── secondpost.md // <- https://example.com/post/secondpost/
| | └── ness.md // <- https://example.com/posts/happy/ness/
| └── secondpost.md // <- https://example.com/posts/secondpost/
└── quote
├── first.md // <- https://example.com/quote/first/
└── second.md // <- https://example.com/quote/second/
@ -216,11 +216,11 @@ Here's the same organization run with `hugo --uglyURLs`:
└── content
└── about
| └── _index.md // <- https://example.com/about.html
├── post
| ├── firstpost.md // <- https://example.com/post/firstpost.html
├── posts
| ├── firstpost.md // <- https://example.com/posts/firstpost.html
| ├── happy
| | └── ness.md // <- https://example.com/post/happy/ness.html
| └── secondpost.md // <- https://example.com/post/secondpost.html
| | └── ness.md // <- https://example.com/posts/happy/ness.html
| └── secondpost.md // <- https://example.com/posts/secondpost.html
└── quote
├── first.md // <- https://example.com/quote/first.html
└── second.md // <- https://example.com/quote/second.html
@ -265,7 +265,7 @@ By default, all relative URLs are left unchanged by Hugo, which can be problemat
Setting `relativeURLs` to `true` in your [site configuration][config] will cause Hugo to rewrite all relative URLs to be relative to the current content.
For example, if your `/post/first/` page contains a link to `/about/`, Hugo will rewrite the URL to `../../about/`.
For example, if your `/posts/first/` page contains a link to `/about/`, Hugo will rewrite the URL to `../../about/`.
[config]: /getting-started/configuration/
[contentorg]: /content-management/organization/

View file

@ -192,7 +192,7 @@ The output of this example will render to the Hugo docs as follows:
The `output` shortcode is almost identical to the `code` shortcode but only takes and requires `file`. The purpose of `output` is to show *rendered* HTML and therefore almost always follows another basic code block *or* and instance of the `code` shortcode:
```
{{%/* output file="post/my-first-post/index.html" */%}}
{{%/* output file="posts/my-first-post/index.html" */%}}
<h1>This is my First Hugo Blog Post</h1>
<p>I am excited to be using Hugo.</p>
{{%/* /output */%}}
@ -200,7 +200,7 @@ The `output` shortcode is almost identical to the `code` shortcode but only take
The preceding `output` example will render as follows to the Hugo docs:
{{< output file="post/my-first-post/index.html" >}}
{{< output file="posts/my-first-post/index.html" >}}
<h1>This is my First Hugo Blog Post</h1>
<p>I am excited to be using Hugo.</p>
{{< /output >}} -->

View file

@ -59,25 +59,25 @@ However, it is not possible to provide the output of a range to the [`delimit` f
If you have `post-tag-list.html` and `post-tag-link.html` as [partials][], you *could* use the following snippets, respectively:
{{< code file="layouts/partial/post-tag-list.html" copy="false" >}}
{{< code file="layouts/partials/post-tag-list.html" copy="false" >}}
{{ with .Params.tags }}
<div class="tags-list">
Tags:
{{ $len := len . }}
{{ if eq $len 1 }}
{{ partial "post/tag/link" (index . 0) }}
{{ partial "post-tag-link" (index . 0) }}
{{ else }}
{{ $last := sub $len 1 }}
{{ range first $last . }}
{{ partial "post/tag/link" . }},
{{ partial "post-tag-link" . }},
{{ end }}
{{ partial "post/tag/link" (index . $last) }}
{{ partial "post-tag-link" (index . $last) }}
{{ end }}
</div>
{{ end }}
{{< /code >}}
{{< code file="layouts/partial/post-tag-link.html" copy="false" >}}
{{< code file="layouts/partials/post-tag-link.html" copy="false" >}}
<a class="post-tag post-tag-{{ . | urlize }}" href="/tags/{{ . | urlize }}">{{ . }}</a>
{{< /code >}}

View file

@ -19,11 +19,36 @@ deprecated: false
aliases: []
---
`first` works in a similar manner to the [`limit` keyword in
SQL][limitkeyword]. It reduces the array to only the `first N`
elements. It takes the array and number of elements as input.
```
`first` takes two arguments:
1. `number of elements`
2. `array` *or* `slice of maps or structs`
{{< code file="layout/_default/section.html" >}}
{{ range first 10 .Pages }}
{{ .Render "summary" }}
{{ end }}
```
{{< /code >}}
*Note: Exclusive to `first`, LIMIT can be '0' to return an empty array.*
## `first` and `where` Together
Using `first` and [`where`][wherefunction] together can be very
powerful. Below snippet gets a list of posts only from [**main
sections**][mainsections], sorts it by the `title` parameter, and then
ranges through only the first 5 posts in that list:
{{< code file="first-and-where-together.html" >}}
{{ range first 5 (where site.RegularPages "Type" "in" site.Params.mainSections).ByTitle }}
{{ .Content }}
{{ end }}
{{< /code >}}
[limitkeyword]: https://www.techonthenet.com/sql/select_limit.php
[wherefunction]: /functions/where/
[mainsections]: /functions/where/#mainsections

View file

@ -43,10 +43,11 @@ You may want to append a class to a heading according to the length of the strin
## `len` Example 2: Counting Pages with `where`
The following templating uses [`where`][] in conjunction with `len` to figure out the total number of content pages in a `posts` [section][]:
The following templating uses [`where`][] in conjunction with `len` to
figure out the total number of content pages in a `posts` [section][]:
{{< code file="how-many-posts.html" >}}
{{ $posts := (where .Site.RegularPages "Section" "==" "post") }}
{{ $posts := (where .Site.RegularPages "Section" "==" "posts") }}
{{ $postCount := len $posts }}
{{< /code >}}

View file

@ -12,8 +12,7 @@ hugoversion: "0.53"
aliases: []
---
The function accept either a `Resource` created in [Hugo Pipes](/hugo-pipes/) or via [Page Bundles](content-management/page-bundles/), or simply a string. The two examples below will produce the same map:
The function accept either a `Resource` created in [Hugo Pipes](/hugo-pipes/) or via [Page Bundles](/content-management/page-bundles/), or simply a string. The two examples below will produce the same map:
```go-html-template
{{ $greetings := "hello = \"Hello Hugo\"" | transform.Unmarshal }}`
@ -36,15 +35,13 @@ The above prints `Hello Hugo`.
Unmarshal with CSV as input has some options you can set:
delimiter
: The delimiter used, default is `,`
: The delimiter used, default is `,`.
comment
: The comment character ued in the CSV. If set, lines beginning with the comment character without preceding whitespace are ignored.:
: The comment character used in the CSV. If set, lines beginning with the comment character without preceding whitespace are ignored.:
Example:
```go-html-template
{{ $csv := "a;b;c" | transform.Unmarshal (dict "delimiter" ";") }}
```

View file

@ -20,10 +20,14 @@ toc: true
needsexample: true
---
`where` filters an array to only the elements containing a matching value for a given field.
`where` filters an array to only the elements containing a matching
value for a given field.
It works in a similar manner to the [`where` keyword in
SQL][wherekeyword].
```go-html-template
{{ range where .Pages "Section" "post" }}
{{ range where .Pages "Section" "foo" }}
{{ .Content }}
{{ end }}
```
@ -45,7 +49,7 @@ series: golang
It can also be used with the logical operators `!=`, `>=`, `in`, etc. Without an operator, `where` compares a given field with a matching value equivalent to `=`.
```go-html-template
{{ range where .Pages "Section" "!=" "post" }}
{{ range where .Pages "Section" "!=" "foo" }}
{{ .Content }}
{{ end }}
```
@ -101,10 +105,14 @@ You can also put the returned value of the `where` clauses into a variable:
## Use `where` with `first`
The following grabs the first five content files in `post` using the [default ordering](/templates/lists/) for lists (i.e., `weight => date`):
Using `first` and [`where`][wherefunction] together can be very
powerful. Below snippet gets a list of posts only from [**main
sections**](#mainsections), sorts it using the [default
ordering](/templates/lists/) for lists (i.e., `weight => date`), and
then ranges through only the first 5 posts in that list:
{{< code file="where-with-first.html" >}}
{{ range first 5 (where .Pages "Section" "post") }}
{{< code file="first-and-where-together.html" >}}
{{ range first 5 (where site.RegularPages "Type" "in" site.Params.mainSections) }}
{{ .Content }}
{{ end }}
{{< /code >}}
@ -134,16 +142,21 @@ Only the following operators are available for `nil`
{{ end }}
```
## Portable `where` filters
## Portable `where` filters -- `site.Params.mainSections` {#mainsections}
This is especially important for themes, but to list the most relevant pages on the front page or similar, you can use `.Site.Params.mainSections` list.
**This is especially important for themes.**
This will, by default, list pages from the _section with the most pages_.
To list the most relevant pages on the front page or similar, you
should use the `site.Params.mainSections` list instead of comparing
section names to hard-coded values like `"posts"` or `"post"`.
```go-html-template
{{ $pages := where .Site.RegularPages "Type" "in" .Site.Params.mainSections }}
{{ $pages := where site.RegularPages "Type" "in" site.Params.mainSections }}
```
If the user has not set this config parameter in their site config, it
will default to the _section with the most pages_.
The user can override the default in `config.toml`:
```toml
@ -152,3 +165,4 @@ mainSections = ["blog", "docs"]
```
[intersect]: /functions/intersect/
[wherekeyword]: https://www.techonthenet.com/sql/where.php

View file

@ -27,7 +27,7 @@ baseURL: "https://yoursite.example.com/"
title: "My Hugo Site"
footnoteReturnLinkContents: "↩"
permalinks:
post: /:year/:month/:title/
posts: /:year/:month/:title/
params:
Subtitle: "Hugo is Absurdly Fast!"
AuthorName: "Jon Doe"

View file

@ -18,6 +18,9 @@ aliases: [/overview/source-directory/,/overview/configuration/]
toc: true
---
## Configuration File
Hugo uses the `config.toml`, `config.yaml`, or `config.json` (if found in the
site root) as the default site config file.
@ -35,6 +38,37 @@ hugo --config a.toml,b.toml,c.toml
Multiple site config files can be specified as a comma-separated string to the `--config` switch.
{{% /note %}}
TODO: distinct config.toml and others (the root object files)
## Configuration Directory
In addition to using a single site config file, one can use the `configDir` directory (default to `config/`) to maintain easier organization and environment specific settings.
- Each file represents a configuration root object, such as `Params`, `Menus`, `Languages` etc...
- Each directory holds a group of files containing settings unique to an environment.
- Files can be localized to become language specific.
```
config
├── _default
│ ├── config.toml
│ ├── languages.toml
│ ├── menus.en.toml
│ ├── menus.zh.toml
│ └── params.toml
├── staging
│ ├── config.toml
│ └── params.toml
└── production
├── config.toml
└── params.toml
```
Considering the structure above, when running `hugo --environment staging`, Hugo will use every settings from `config/_default` and merge `staging`'s on top of those.
{{% note %}}
Default environments are __development__ with `hugo serve` and __production__ with `hugo`.
{{%/ note %}}
## All Configuration Settings
The following is the full list of Hugo-defined variables with their default
@ -163,7 +197,7 @@ noTimes (false)
: Don't sync modification time of files.
paginate (10)
: Default number of pages per page in [pagination](/templates/pagination/).
: Default number of elements per page in [pagination](/templates/pagination/).
paginatePath ("page")
: The path element used during pagination (https://example.com/page/2).
@ -280,7 +314,7 @@ baseURL: "https://yoursite.example.com/"
title: "My Hugo Site"
footnoteReturnLinkContents: "↩"
permalinks:
post: /:year/:month/:title/
posts: /:year/:month/:title/
params:
Subtitle: "Hugo is Absurdly Fast!"
AuthorName: "Jon Doe"
@ -434,12 +468,11 @@ You can override any of these cache setting in your own `config.toml`.
### The keywords explained
:cacheDir
`:cacheDir`
: This is the value of the `cacheDir` config option if set (can also be set via OS env variable `HUGO_CACHEDIR`). It will fall back to `/opt/build/cache/hugo_cache/` on Netlify, or a `hugo_cache` directory below the OS temp dir for the others. 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).
`:project`
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.
: 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`
: This is the value of the `resourceDir` config option.

View file

@ -28,7 +28,7 @@ Running the `hugo new site` generator from the command line will create a direct
.
├── archetypes
├── assets
├── config.toml
├── config
├── content
├── data
├── layouts
@ -48,8 +48,12 @@ By default, Hugo will create new content files with at least `date`, `title` (in
[`assets`][]
: Stores all the files which need be processed by [Hugo Pipes]({{< ref "/hugo-pipes" >}}). Only the files whose `.Permalink` or `.RelPermalink` are used will be published to the `public` directory.
[`config.toml`](/getting-started/configuration/)
: Every Hugo project should have a configuration file in TOML, YAML, or JSON format at the root. Many sites may need little to no configuration, but Hugo ships with a large number of [configuration directives][] for more granular directions on how you want Hugo to build your website.
[`config`](/getting-started/configuration/)
: Hugo ships with a large number of [configuration directives](https://gohugo.io/getting-started/configuration/#all-variables-yaml).
The [config directory](/getting-started/configuration/#configuration-directory) is where those directives are stored as JSON, YAML, or TOML files. Every root setting object can stand as its own file and structured by environments.
Projects with minimal settings and no need for environment awareness can use a single `config.toml` file at its root.
Many sites may need little to no configuration, but Hugo ships with a large number of [configuration directives][] for more granular directions on how you want Hugo to build your website.
[`content`][]
: All content for your website will live inside this directory. Each top-level folder in Hugo is considered a [content section][]. For example, if your site has three main sections---`blog`, `articles`, and `tutorials`---you will have three directories at `content/blog`, `content/articles`, and `content/tutorials`. Hugo uses sections to assign default [content types][].

View file

@ -21,7 +21,7 @@ toc: true
{{% note %}}
This quick start uses `macOS` in the examples. For instructions about how to install Hugo on other operating systems, see [install](/getting-started/installing).
You also need [Git installed](https://git-scm.com/downloads) to run this tutorial.
It is recommended to have [Git installed](https://git-scm.com/downloads) to run this tutorial.
{{% /note %}}
@ -62,9 +62,18 @@ The above will create a new Hugo site in a folder named `quickstart`.
See [themes.gohugo.io](https://themes.gohugo.io/) for a list of themes to consider. This quickstart uses the beautiful [Ananke theme](https://themes.gohugo.io/gohugo-theme-ananke/).
```bash
cd quickstart;\
git init;\
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke;\
cd quickstart
# Download the theme
git init
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke
# Note for non-git users:
# - If you do not have git installed, you can download the archive of the latest
# version of this theme from:
# https://github.com/budparr/gohugo-theme-ananke/archive/master.zip
# - Extract that .zip file to get a "gohugo-theme-ananke-master" directory.
# - Rename that directory to "ananke", and move it into the "themes/" directory.
# End of note for non-git users.
# Edit your config.toml configuration file
# and add the Ananke theme.
@ -81,7 +90,12 @@ hugo new posts/my-first-post.md
```
Edit the newly created content file if you want. Now, start the Hugo server with [drafts](/getting-started/usage/#draft-future-and-expired-content) enabled:
Edit the newly created content file if you want.
## Step 5: Start the Hugo server
Now, start the Hugo server with [drafts](/getting-started/usage/#draft-future-and-expired-content) enabled:
```
▶ hugo server -D
@ -108,8 +122,7 @@ Press Ctrl+C to stop
**Navigate to your new site at [http://localhost:1313/](http://localhost:1313/).**
## Step 5: Customize the Theme
## Step 6: Customize the Theme
Your new site already looks great, but you will want to tweak it a little before you release it to the public.

View file

@ -125,8 +125,8 @@ cours-versailles/index.html
exercices/index.html
exercices/index.xml
exercices/barycentre-et-carres-des-distances/index.html
post/
post/index.html
posts/
posts/index.html
sujets/index.html
sujets/index.xml
sujets/2016-09_supelec-jp/index.html

View file

@ -120,7 +120,7 @@ aero apikey
### Step 3: Edit and Commit Code
```
hugo new post/good-to-great.md
hugo new posts/good-to-great.md
hugo server --buildDrafts -t liquorice #Check that all looks good
# commit and push code to master branch

View file

@ -37,7 +37,7 @@ cd your-hugo-site
In the root directory of your Hugo site, create a `.gitlab-ci.yml` file. The `.gitlab-ci.yml` configures the GitLab CI on how to build your page. Simply add the content below.
{{< code file="gitlab-ci.yml" >}}
{{< code file=".gitlab-ci.yml" >}}
image: monachus/hugo
variables:

View file

@ -67,14 +67,14 @@ For production:
```
[context.production.environment]
HUGO_VERSION = "0.36"
HUGO_VERSION = "0.53"
```
For testing:
```
[context.deploy-preview.environment]
HUGO_VERSION = "0.36"
HUGO_VERSION = "0.53"
```
The Netlify configuration file can be a little hard to understand and get right for the different environment, and you may get some inspiration and tips from this site's `netlify.toml`:

View file

@ -42,18 +42,18 @@ Variables are denoted by capitalized text set within `<>`. Note that Hugo's defa
### Example Base Template Lookup Order
As an example, let's assume your site is using a theme called "mytheme" when rendering the section list for a `post` section. Hugo picks `layout/section/post.html` as the template for [rendering the section][]. The `{{define}}` block in this template tells Hugo that the template is an extension of a base template.
As an example, let's assume your site is using a theme called "mytheme" when rendering the section list for a `posts` section. Hugo picks `layout/section/posts.html` as the template for [rendering the section][]. The `{{define}}` block in this template tells Hugo that the template is an extension of a base template.
Here is the lookup order for the `post` base template:
Here is the lookup order for the `posts` base template:
1. `/layouts/section/post-baseof.html`
2. `/themes/mytheme/layouts/section/post-baseof.html`
3. `/layouts/post/baseof.html`
4. `/themes/mytheme/layouts/post/baseof.html`
1. `/layouts/section/posts-baseof.html`
2. `/themes/mytheme/layouts/section/posts-baseof.html`
3. `/layouts/posts/baseof.html`
4. `/themes/mytheme/layouts/posts/baseof.html`
5. `/layouts/section/baseof.html`
6. `/themes/mytheme/layouts/section/baseof.html`
7. `/layouts/_default/post-baseof.html`
8. `/themes/mytheme/layouts/_default/post-baseof.html`
7. `/layouts/_default/posts-baseof.html`
8. `/themes/mytheme/layouts/_default/posts-baseof.html`
9. `/layouts/_default/baseof.html`
10. `/themes/mytheme/layouts/_default/baseof.html`

View file

@ -184,7 +184,7 @@ For `getCSV`, the one-character-long separator must be placed in the first posit
</tr>
</thead>
<tbody>
{{ $url := "http://a-big-corp.com/finance/employee-salaries.csv" }}
{{ $url := "https://example.com/finance/employee-salaries.csv" }}
{{ $sep := "," }}
{{ range $i, $r := getCSV $sep $url }}
<tr>

View file

@ -63,7 +63,7 @@ The following is an example of a typical Hugo project directory's content:
.
...
├── content
| ├── post
| ├── posts
| | ├── _index.md
| | ├── post-01.md
| | └── post-02.md
@ -73,9 +73,9 @@ The following is an example of a typical Hugo project directory's content:
...
```
Using the above example, let's assume you have the following in `content/post/_index.md`:
Using the above example, let's assume you have the following in `content/posts/_index.md`:
{{< code file="content/post/_index.md" >}}
{{< code file="content/posts/_index.md" >}}
---
title: My Go Journey
date: 2017-03-23
@ -100,7 +100,7 @@ You can now access this `_index.md`'s' content in your list template:
{{.Content}}
</article>
<ul>
<!-- Ranges through content/post/*.md -->
<!-- Ranges through content/posts/*.md -->
{{ range .Pages }}
<li>
<a href="{{.Permalink}}">{{.Date.Format "2006-01-02"}} | {{.Title}}</a>
@ -113,7 +113,7 @@ You can now access this `_index.md`'s' content in your list template:
This above will output the following HTML:
{{< code file="example.com/post/index.html" copy="false" >}}
{{< code file="example.com/posts/index.html" copy="false" >}}
<!--top of your baseof code-->
<main>
<article>
@ -124,8 +124,8 @@ This above will output the following HTML:
<p>Follow my journey through this new blog.</p>
</article>
<ul>
<li><a href="/post/post-01/">Post 1</a></li>
<li><a href="/post/post-02/">Post 2</a></li>
<li><a href="/posts/post-01/">Post 1</a></li>
<li><a href="/posts/post-02/">Post 2</a></li>
</ul>
</main>
<!--bottom of your baseof-->
@ -164,14 +164,14 @@ The default behavior of Hugo is to pluralize list titles; hence the inflection o
This list template has been modified slightly from a template originally used in [spf13.com](http://spf13.com/). It makes use of [partial templates][partials] for the chrome of the rendered page rather than using a [base template][base] The examples that follow also use the [content view templates][views] `li.html` or `summary.html`.
{{< code file="layouts/section/post.html" >}}
{{< code file="layouts/section/posts.html" >}}
{{ partial "header.html" . }}
{{ partial "subheader.html" . }}
<main>
<div>
<h1>{{ .Title }}</h1>
<ul>
<!-- Renders the li.html content view for each content/post/*.md -->
<!-- Renders the li.html content view for each content/posts/*.md -->
{{ range .Pages }}
{{ .Render "li"}}
{{ end }}
@ -524,49 +524,14 @@ Here is the ordering for the example that follows:
{{ end }}
{{< /code >}}
## Filter and Limiting Lists
## Filtering and Limiting Lists {#filtering-and-limiting-lists}
Sometimes you only want to list a subset of the available content. A common is to only display “Posts” on blog's homepage. You can accomplish this with the `where` function.
Sometimes you only want to list a subset of the available content. A
common is to only display posts from [**main sections**][mainsections]
on the blog's homepage.
### `where`
`where` works in a similar manner to the [`where` keyword in SQL][wherekeyword]. It selects all elements of the array or slice that match the provided field and value. `where` takes three arguments:
1. `array` *or* `slice of maps or structs`
2. `key` *or* `field name`
3. `match value`
{{< code file="layouts/_default/index.html" >}}
{{ range where .Pages "Section" "post" }}
{{ .Content }}
{{ end }}
{{< /code >}}
You can see more examples in the [functions documentation for `where`][wherefunction].
### `first`
`first` works in a similar manner to the [`limit` keyword in SQL][limitkeyword]. It reduces the array to only the `first N` elements. It takes the array and number of elements as input. `first` takes two arguments:
1. `array` *or* `slice of maps or structs`
2. `number of elements`
{{< code file="layout/_default/section.html" >}}
{{ range first 10 .Pages }}
{{ .Render "summary" }}
{{ end }}
{{< /code >}}
### `first` and `where` Together
Using `first` and `where` together can be very powerful:
{{< code file="first-and-where-together.html" >}}
<!-- Orders the content inside the "posts" section by the "title" field and then ranges through only the first 5 posts -->
{{ range first 5 (where .Pages "Section" "post").ByTitle }}
{{ .Content }}
{{ end }}
{{< /code >}}
See the documentation on [`where` function][wherefunction] and
[`first` function][firstfunction] for further details.
[base]: /templates/base/
[bepsays]: http://bepsays.com/en/2016/12/19/hugo-018/
@ -576,7 +541,6 @@ Using `first` and `where` together can be very powerful:
[getpage]: /functions/getpage/
[homepage]: /templates/homepage/
[homepage]: /templates/homepage/
[limitkeyword]: https://www.techonthenet.com/sql/select_limit.php
[mentalmodel]: http://webstyleguide.com/wsg3/3-information-architecture/3-site-structure.html
[pagevars]: /variables/page/
[partials]: /templates/partials/
@ -590,4 +554,5 @@ Using `first` and `where` together can be very powerful:
[taxvars]: /variables/taxonomy/
[views]: /templates/views/
[wherefunction]: /functions/where/
[wherekeyword]: https://www.techonthenet.com/sql/where.php
[firstfunction]: /functions/first/
[mainsections]: /functions/where/#mainsections

View file

@ -336,44 +336,9 @@ within each group is ordered alphabetically by title.
## Filter and Limiting Lists
Sometimes you only want to list a subset of the available content. A common request is to only display “Posts” on the homepage. You can accomplish this with the `where` function.
### `where`
`where` works in a similar manner to the `where` keyword in SQL. It selects all elements of the array or slice that match the provided field and value. `where` takes three arguments:
1. `array` or a `slice of maps or structs`
2. `key` or `field name`
3. `match value`
{{< code file="layouts/_default/index.html" >}}
{{ range where .Pages "Section" "post" }}
{{ .Content }}
{{ end }}
{{< /code >}}
### `first`
`first` works in a similar manner to the [`limit` keyword in SQL][limitkeyword]. It reduces the array to only the `first N` elements. It takes the array and number of elements as input. `first` takes two arguments:
1. `array` or `slice of maps or structs`
2. `number of elements`
{{< code file="layout/_default/section.html" >}}
{{ range first 10 .Pages }}
{{ .Render "summary" }}
{{ end }}
{{< /code >}}
### `first` and `where` Together
Using `first` and `where` together can be very powerful:
{{< code file="first-and-where-together.html" >}}
{{ range first 5 (where .Pages "Section" "post") }}
{{ .Content }}
{{ end }}
{{< /code >}}
See the [_Lists/Filtering and Limiting Lists_
section][filteringandlimitinglists] for details.
[views]: /templates/views/
[filteringandlimitinglists]: /templates/lists/#filtering-and-limiting-lists

View file

@ -50,7 +50,7 @@ For a given **Page**, it's one of the options above. The `.Paginator` is static
The global page size setting (`Paginate`) can be overridden by providing a positive integer as the last argument. The examples below will give five items per page:
* `{{ range (.Paginator 5).Pages }}`
* `{{ $paginator := .Paginate (where .Pages "Type" "post") 5 }}`
* `{{ $paginator := .Paginate (where .Pages "Type" "posts") 5 }}`
It is also possible to use the `GroupBy` functions in combination with pagination:
@ -75,7 +75,7 @@ If you use any filters or ordering functions to create your `.Paginator` *and* y
The following example shows how to create `.Paginator` before its used:
```
{{ $paginator := .Paginate (where .Pages "Type" "post") }}
{{ $paginator := .Paginate (where .Pages "Type" "posts") }}
{{ template "_internal/pagination.html" . }}
{{ range $paginator.Pages }}
{{ .Title }}

View file

@ -26,11 +26,11 @@ See [Template Lookup](/templates/lookup-order/).
Content pages are of the type `page` and will therefore have all the [page variables][pagevars] and [site variables][] available to use in their templates.
### `post/single.html`
### `posts/single.html`
This single page template makes use of Hugo [base templates][], the [`.Format` function][] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`][] is also used to check whether the taxonomies are set in the front matter.
{{< code file="layouts/post/single.html" download="single.html" >}}
{{< code file="layouts/posts/single.html" download="single.html" >}}
{{ define "main" }}
<section id="main">
<h1 id="title">{{ .Title }}</h1>

View file

@ -238,7 +238,7 @@ Because we are leveraging the front matter system to define taxonomies for conte
<ul id="{{ $taxo }}">
{{ range .Param $taxo }}
{{ $name := . }}
{{ with $.Site.GetPage (printf "/%s/%s" $taxo $name) }}
{{ with $.Site.GetPage (printf "/%s/%s" $taxo ($name | urlize)) }}
<li><a href="{{ .Permalink }}">{{ $name }}</a></li>
{{ end }}
{{ end }}

View file

@ -27,11 +27,11 @@ The following are common use cases for content views:
## Create a Content View
To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `post` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view.
To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `posts` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view.
```
▾ layouts/
▾ post/
▾ posts/
li.html
single.html
summary.html

View file

@ -20,7 +20,10 @@ wip: true
---
{{% warning "Use Absolute Links" %}}
If you're creating a theme with plans to share it on the [Hugo Themes website](https://themes.gohugo.io/) please note that your theme's demo will be available in a sub-directory of website and for the theme's assets to load properly you will need to create absolute paths in the templates by using either the [absURL](/functions/absurl) function or `.Permalink`. Also make sure not to use a forward slash `/` in the beginning of a `PATH`, because Hugo will turn it into a relative URL and the `absURL` function will have no effect.
If you're creating a theme with plans to share it on the [Hugo Themes website](https://themes.gohugo.io/) please note the following:
- If using inline styles you will need to use absolute URLs, for the linked assets to be served properly, e.g. `<div style="background: url('{{ "images/background.jpg" | absURL }}')">`
- Make sure not to use a forward slash `/` in the beginning of a `URL`, because it will point to the host root. Your theme's demo will be available in a subdirectory of the Hugo website and in this scenario Hugo will not generate the correct `URL` for theme assets.
- If using external CSS and JS from a CDN, make sure to load these assets over `https`. Please do not use relative protocol URLs in your theme's templates.
{{% /warning %}}
Hugo can initialize a new blank theme directory within your existing `themes` using the `hugo new` command:

View file

@ -27,6 +27,8 @@ The Hugo community uses a wide range of preferred tools and has developed plug-i
## Visual Studio Code
* [Hugofy](https://marketplace.visualstudio.com/items?itemName=akmittal.hugofy). Hugofy is a plugin for Visual Studio Code to "make life easier" when developing with Hugo. The source code can be found [here](https://github.com/akmittal/hugofy-vscode).
* [Hugo Helper](https://marketplace.visualstudio.com/items?itemName=rusnasonov.vscode-hugo). Hugo Helper is a plugin for Visual Studio Code that has some useful commands for Hugo. The source code can be found [here](https://github.com/rusnasonov/vscode-hugo).
* [Hugo Language and Syntax Support](https://marketplace.visualstudio.com/items?itemName=budparr.language-hugo-vscode). Hugo Language and Syntax Support is a Visual Studio Code plugin for Hugo syntax highlighting and snippets. The source code can be found [here](https://github.com/budparr/language-hugo-vscode).
## Emacs

View file

@ -58,17 +58,17 @@ Template Metrics:
---------- -------- -------- ----- --------
6.419663ms 583.605µs 994.374µs 11 _internal/_default/rss.xml
4.718511ms 1.572837ms 3.880742ms 3 indexes/category.html
4.642666ms 2.321333ms 3.282842ms 2 post/single.html
4.642666ms 2.321333ms 3.282842ms 2 posts/single.html
4.364445ms 396.767µs 2.451372ms 11 partials/header.html
2.346069ms 586.517µs 903.343µs 4 indexes/tag.html
2.330919ms 211.901µs 2.281342ms 11 partials/header.includes.html
1.238976ms 103.248µs 446.084µs 12 post/li.html
1.238976ms 103.248µs 446.084µs 12 posts/li.html
972.16µs 972.16µs 972.16µs 1 _internal/_default/sitemap.xml
953.597µs 953.597µs 953.597µs 1 index.html
822.263µs 822.263µs 822.263µs 1 indexes/post.html
567.498µs 51.59µs 112.205µs 11 partials/navbar.html
348.22µs 31.656µs 88.249µs 11 partials/meta.html
346.782µs 173.391µs 276.176µs 2 post/summary.html
346.782µs 173.391µs 276.176µs 2 posts/summary.html
235.184µs 21.38µs 124.383µs 11 partials/footer.copyright.html
132.003µs 12µs 117.999µs 11 partials/menu.html
72.547µs 6.595µs 63.764µs 11 partials/footer.html

View file

@ -27,12 +27,17 @@ It contains the following fields:
.Hugo.Version
: the current version of the Hugo binary you are using e.g. `0.13-DEV`<br>
.Hugo.Environment
: the current running environment as defined through the `--environment` cli tag.
.Hugo.CommitHash
: the git commit hash of the current Hugo binary e.g. `0e8bed9ccffba0df554728b46c5bbf6d78ae5247`
.Hugo.BuildDate
: the compile date of the current Hugo binary formatted with RFC 3339 e.g. `2002-10-02T10:00:00-05:00`<br>
{{% note "Use the Hugo Generator Tag" %}}
We highly recommend using `.Hugo.Generator` in your website's `<head>`. `.Hugo.Generator` is included by default in all themes hosted on [themes.gohugo.io](http://themes.gohugo.io). The generator tag allows the Hugo team to track the usage and popularity of Hugo.
{{% /note %}}

View file

@ -78,9 +78,6 @@ See [`.Scratch`](/functions/scratch/) for page-scoped, writable variables.
.Kind
: the page's *kind*. Possible return values are `page`, `home`, `section`, `taxonomy`, or `taxonomyTerm`. Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` 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.
.Lang
: language taken from the language extension notation.
.Language
: a language object that points to the language's definition in the site
`config`.
@ -178,10 +175,7 @@ http://remarkjs.com)
: a boolean, `true` if the `.Summary` is truncated. Useful for showing a "Read more..." link only when necessary. See [Summaries](/content-management/summaries/) for more information.
.Type
: the [content type](/content-management/types/) of the content (e.g., `post`).
.URL
: the URL for the page relative to the web root. Note that a `url` set directly in front matter overrides the default relative URL for the rendered page.
: the [content type](/content-management/types/) of the content (e.g., `posts`).
.UniqueID
: the MD5-checksum of the content file's path.

View file

@ -88,15 +88,9 @@ The following is a list of site-level (aka "global") variables. Many of these va
.Site.Pages
: array of all content ordered by Date with the newest first. This array contains only the pages in the current language. See [`.Site.Pages`](#site-pages).
.Site.Permalinks
: a string to override the default [permalink](/content-management/urls/) format as defined in the site configuration.
.Site.RegularPages
: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`. See [`.Site.Pages`](#site-pages).
.Site.RSSLink
: the URL for the site RSS.
.Site.Sections
: top-level directories of the site.

View file

@ -42,18 +42,18 @@ Variables are denoted by capitalized text set within `<>`. Note that Hugo's defa
### Example Base Template Lookup Order
As an example, let's assume your site is using a theme called "mytheme" when rendering the section list for a `post` section. Hugo picks `layout/section/post.html` as the template for [rendering the section][]. The `{{define}}` block in this template tells Hugo that the template is an extension of a base template.
As an example, let's assume your site is using a theme called "mytheme" when rendering the section list for a `posts` section. Hugo picks `layout/section/posts.html` as the template for [rendering the section][]. The `{{define}}` block in this template tells Hugo that the template is an extension of a base template.
Here is the lookup order for the `post` base template:
Here is the lookup order for the `posts` base template:
1. `/layouts/section/post-baseof.html`
2. `/themes/mytheme/layouts/section/post-baseof.html`
3. `/layouts/post/baseof.html`
4. `/themes/mytheme/layouts/post/baseof.html`
1. `/layouts/section/posts-baseof.html`
2. `/themes/mytheme/layouts/section/posts-baseof.html`
3. `/layouts/posts/baseof.html`
4. `/themes/mytheme/layouts/posts/baseof.html`
5. `/layouts/section/baseof.html`
6. `/themes/mytheme/layouts/section/baseof.html`
7. `/layouts/_default/post-baseof.html`
8. `/themes/mytheme/layouts/_default/post-baseof.html`
7. `/layouts/_default/posts-baseof.html`
8. `/themes/mytheme/layouts/_default/posts-baseof.html`
9. `/layouts/_default/baseof.html`
10. `/themes/mytheme/layouts/_default/baseof.html`

View file

@ -1324,6 +1324,16 @@
"xml"
]
},
{
"type": "application/toml",
"string": "application/toml",
"mainType": "application",
"subType": "toml",
"delimiter": ".",
"suffixes": [
"toml"
]
},
{
"type": "application/xml",
"string": "application/xml",
@ -1334,6 +1344,17 @@
"xml"
]
},
{
"type": "application/yaml",
"string": "application/yaml",
"mainType": "application",
"subType": "yaml",
"delimiter": ".",
"suffixes": [
"yaml",
"yml"
]
},
{
"type": "image/svg+xml",
"string": "image/svg+xml",
@ -2271,6 +2292,21 @@
],
"Examples": []
},
"Complement": {
"Description": "Complement gives the elements in the last element of seqs that are not in\nany of the others.\nAll elements of seqs must be slices or arrays of comparable types.\n\nThe reasoning behind this rather clumsy API is so we can do this in the templates:\n {{ $c := .Pages | complement $last4 }}",
"Args": [
"seqs"
],
"Aliases": [
"complement"
],
"Examples": [
[
"{{ slice \"a\" \"b\" \"c\" \"d\" \"e\" \"f\" | complement (slice \"b\" \"c\") (slice \"d\" \"e\") }}",
"[a f]"
]
]
},
"Delimit": {
"Description": "Delimit takes a given sequence and returns a delimited HTML string.\nIf last is passed to the function, it will be used as the final delimiter.",
"Args": [
@ -2496,6 +2532,22 @@
],
"Examples": []
},
"SymDiff": {
"Description": "SymDiff returns the symmetric difference of s1 and s2.\nArguments must be either a slice or an array of comparable types.",
"Args": [
"s2",
"s1"
],
"Aliases": [
"symdiff"
],
"Examples": [
[
"{{ slice 1 2 3 | symdiff (slice 3 4) }}",
"[1 2 4]"
]
]
},
"Union": {
"Description": "Union returns the union of the given sets, l1 and l2. l1 and\nl2 must be of the same type and may be either arrays or slices.\nIf l1 and l2 aren't of the same type then l1 will be returned.\nIf either l1 or l2 is nil then the non-nil list will be returned.",
"Args": [
@ -2650,7 +2702,7 @@
]
},
"Jsonify": {
"Description": "Jsonify encodes a given object to JSON, returning pretty printed output.",
"Description": "Jsonify encodes a given object to JSON.",
"Args": [
"v"
],
@ -2660,7 +2712,7 @@
"Examples": [
[
"{{ (slice \"A\" \"B\" \"C\") | jsonify }}",
"[\n \"A\",\n \"B\",\n \"C\"\n]"
"[\"A\",\"B\",\"C\"]"
]
]
}
@ -2729,6 +2781,20 @@
]
}
},
"hugo": {
"Generator": {
"Description": "",
"Args": null,
"Aliases": null,
"Examples": null
},
"Version": {
"Description": "",
"Args": null,
"Aliases": null,
"Examples": null
}
},
"images": {
"Config": {
"Description": "Config returns the image.Config for the specified path relative to the\nworking directory.",
@ -3325,6 +3391,26 @@
]
}
},
"site": {
"Hugo": {
"Description": "",
"Args": null,
"Aliases": null,
"Examples": null
},
"IsServer": {
"Description": "",
"Args": null,
"Aliases": null,
"Examples": null
},
"Language": {
"Description": "",
"Args": null,
"Aliases": null,
"Examples": null
}
},
"strings": {
"Chomp": {
"Description": "Chomp returns a copy of s with all trailing newline characters removed.",
@ -3889,6 +3975,25 @@
"{\n \"title\": \"Hello World\"\n}\n"
]
]
},
"Unmarshal": {
"Description": "Unmarshal unmarshals the data given, which can be either a string\nor a Resource. Supported formats are JSON, TOML, YAML, and CSV.\nYou can optionally provide an options map as the first argument.",
"Args": [
"args"
],
"Aliases": [
"unmarshal"
],
"Examples": [
[
"{{ \"hello = \\\"Hello World\\\"\" | transform.Unmarshal }}",
"map[hello:Hello World]"
],
[
"{{ \"hello = \\\"Hello World\\\"\" | resources.FromString \"data/greetings.toml\" | transform.Unmarshal }}",
"map[hello:Hello World]"
]
]
}
},
"urls": {

File diff suppressed because one or more lines are too long

View file

@ -1 +1 @@
{"Target":"output/css/app.min.e14b2e3b63f7e91f44cc63646938762f24be62093e9f883960605b30789b7337.css","MediaType":"text/css","Data":{"Integrity":"sha256-4UsuO2P36R9EzGNkaTh2LyS+Ygk+n4g5YGBbMHibczc="}}
{"Target":"output/css/app.min.7b23725c013f7650fd9e3f14b7f6b0bc02f71e14088ecd41bbe57661163fbcbb.css","MediaType":"text/css","Data":{"Integrity":"sha256-eyNyXAE/dlD9nj8Ut/awvAL3HhQIjs1Bu+V2YRY/vLs="}}

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

View file

@ -2,8 +2,12 @@
<html class="no-js" lang="{{ with $.Site.LanguageCode }}{{ . }}{{ else }}en-us{{ end }}">
<head>
<meta charset="utf-8">
{{/* https://www.zachleat.com/web/preload/ */}}
<link rel="preload" href="{{ "files/muli-latin-200.woff2" | absURL }}" as="font" type="font/woff2" crossorigin>
<link rel="preload" href="{{ "files/muli-latin-400.woff2" | absURL }}" as="font" type="font/woff2" crossorigin>
<link rel="preload" href="{{ "files/muli-latin-800.woff2" | absURL }}" as="font" type="font/woff2" crossorigin>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
{{/* NOTE: the Site's title, and if there is a page title, that is set too */}}
<title>{{ block "title" . }}{{ with .Title }}{{ . }} | {{ end }}{{ .Site.Title }}{{ end }}</title>
<meta name="HandheldFriendly" content="True">

View file

@ -3,26 +3,6 @@
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: origin-when-cross-origin
*/
{{ $stylesheet := resources.Get "output/css/app.css" }}
{{ $scripts := resources.Get "output/js/app.js" }}
{{ with $stylesheet -}}Link: <{{ .Permalink | relURL }}>; rel=preload; as=style nopush{{- end}}
{{ with $scripts -}}Link: <{{ .Permalink | relURL }}>; rel=preload; as=script nopush{{- end}}
{{ range (readDir "/static/fonts/") }}
Link: </fonts/{{ .Name }}>; rel=preload; as=font nopush
{{ end }}
{{ range (readDir "./themes/gohugoioTheme/static/fonts") }}
Link: </fonts/{{ .Name }}>; rel=preload; as=font nopush
{{ end }}
{{ with $stylesheet }}
{{ .Permalink | relURL }}
Cache-Control: public, max-age=31556926,immutable
{{end }}
{{ with $scripts }}
{{ .Permalink | relURL }}
Cache-Control: public, max-age=31556926,immutable
{{end}}
/*
Link: <{{ "dist/app.bundle.js" | relURL }}>; rel=preload; as=script
Link: <{{ "dist/main.css" | relURL }}>; rel=preload; as=style

View file

@ -3,7 +3,7 @@
{{ with .cx.Site.Data.sponsors }}
<section class="{{ $.classes_section | default "bg-primary-color-dark b--dark-gray bb bt ph5 pv4 w-100"}}">
<div class="center mw9"> 
<f3 class="b f3 light-gray">Hugo Sponsors</f3>
<h3 class="b f3 mv0 light-gray">Hugo Sponsors</h3>
<div class="flex-ns flex-wrap center justify-between pt3">
{{ range .banners }}
{{ $banner := . }}

View file

@ -1,6 +1,6 @@
<form id="site-search-form" action="" role="search">
<fieldset class="bn ma0 pa0">
<label class="clip" for="search-input">Search</label>
<input type="search" id="search-input" class="needs-js bn f5 input-reset lh-solid mt3 mt0-ns pl4 pv2 w5 white" placeholder="Search the Docs" type="text" name="search-input" value="" style="background: transparent url('/images/icon-search.png') no-repeat left center;background-size:16px 16px;">
<input type="search" id="search-input" class="needs-js bg-left bg-transparent bn f5 input-reset lh-solid mt3 mt0-ns pl4 pv2 w5 white" placeholder="Search the Docs" name="search-input" value="" style="background-image:url('/images/icon-search.png');background-size:16px 16px;">
</fieldset>
</form>

5747
themes/gohugoioTheme/src/package-lock.json generated Normal file

File diff suppressed because it is too large Load diff

View file

@ -0,0 +1,36 @@
{
"name": "gohugo-default-styles",
"version": "1.0.0",
"description": "Default Theme for Hugo Sites",
"main": "index.js",
"repository": "",
"author": "budparr",
"license": "MIT",
"scripts": {
"build:production": "rm -rf ../static/dist && webpack -p",
"build": "webpack --progress --colors --watch",
"start": "npm run build"
},
"devDependencies": {
"babel-core": "^6.26.3",
"babel-loader": "^7.0.0",
"babel-preset-env": "^1.7.0",
"clipboard": "^1.6.1",
"css-loader": "^0.28.0",
"cssnano": "^3.10.0",
"docsearch.js": "^2.3.3",
"extract-text-webpack-plugin": "^2.1.0",
"file-loader": "^0.11.1",
"highlight.js": "^9.11.0",
"lazysizes": "^3.0.0",
"postcss": "^5.2.16",
"postcss-cssnext": "^2.10.0",
"postcss-import": "^9.1.0",
"postcss-loader": "^1.3.3",
"scrolldir": "^1.2.7",
"style-loader": "^0.16.1",
"tachyons": "^4.7.0",
"webpack": "^2.3.3"
},
"dependencies": {}
}

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long