mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-21 20:46:30 -05:00
Squashed 'docs/' changes from 2201ac0e5..2c0125b52
2c0125b52 Remove .Site.Author 2cf8841b3 Update partialCached.md (#1924) 385487191 Update data-templates.md (#1926) ce207e141 Remove redundant markdown and fix a few typos (#1936) 3687c2953 Make heading id linkable, take 2 45c79bea7 Make heading id linkable b22079344 Delete duplicates the lines 557-569 and 570-582. (#1934) 0a90dc122 Rework the taxonomy variables page (#1935) 7f8979c50 Update theme 26e682a3a Update multilingual.md d40e7693f Update postcss.md 375d75c01 Update postcss npm instructions (#1931) 63020094a Emphasize Window shell selection (#1930) 56824be2c Update configuration.md b7b8f16b3 Docu 'Theme components': minor fix (#1929) 09dc81a05 Remove Docker from BSD page (#1927) 205fea204 netlify: Hugo 0.108.0 6abe49c28 Merge commit 'da670c38ee63a7fef25e2b9f42519232055b60dc' 12b59a4c5 docs: Add basic doc for wrapStandAloneImageWithinParagraph etc. ba07bd970 dartsass: Add sourceMapIncludeSources option git-subtree-dir: docs git-subtree-split: 2c0125b5290494d49334606c451446ebd9df3c21
This commit is contained in:
Bjørn Erik Pedersen
parent
da670c38ee
commit
41bc6f702a
74 changed files with 348 additions and 298 deletions
|
|
@ -54,7 +54,7 @@ pre {
|
|||
}
|
||||
|
||||
@media (--breakpoint-large) {
|
||||
.full-width, pre.expand:hover
|
||||
.full-width
|
||||
{
|
||||
/*width: 100vw;
|
||||
position: relative;
|
||||
|
|
|
|||
|
|
@ -1,7 +1,6 @@
|
|||
require('typeface-muli');
|
||||
import styles from './css/main.css';
|
||||
import './js/clipboardjs.js';
|
||||
import './js/codeblocks.js';
|
||||
import './js/docsearch.js';
|
||||
import './js/lazysizes.js';
|
||||
import './js/menutoggle.js';
|
||||
|
|
|
|||
|
|
@ -1,10 +0,0 @@
|
|||
let article = document.getElementById('prose')
|
||||
|
||||
if (article) {
|
||||
let codeBlocks = article.getElementsByTagName('code')
|
||||
for (let [key, codeBlock] of Object.entries(codeBlocks)){
|
||||
var widthDif = codeBlock.scrollWidth - codeBlock.clientWidth
|
||||
if (widthDif > 0)
|
||||
codeBlock.parentNode.classList.add('expand')
|
||||
}
|
||||
}
|
||||
|
|
@ -4809,7 +4809,7 @@ pre {
|
|||
content: "Copied"
|
||||
}
|
||||
@media screen and (min-width: 60em) {
|
||||
.full-width, pre.expand:hover
|
||||
.full-width
|
||||
{
|
||||
/*width: 100vw;
|
||||
position: relative;
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
|
@ -1 +1 @@
|
|||
# github.com/gohugoio/gohugoioTheme v0.0.0-20221206093948-1408550ab675
|
||||
# github.com/gohugoio/gohugoioTheme v0.0.0-20221217122332-1c1752ad8f14
|
||||
|
|
|
|||
|
|
@ -27,11 +27,11 @@ This has many benefits. The most noticeable is performance. HTTP servers are *ve
|
|||
|
||||
## More on Static Site Generators
|
||||
|
||||
* ["An Introduction to Static Site Generators", David Walsh][]
|
||||
* ["An Introduction to Static Site Generators", David Walsh]
|
||||
* ["Hugo vs. WordPress page load speed comparison: Hugo leaves WordPress in its dust", GettingThingsTech][hugovwordpress]
|
||||
* ["Static Site Generators", O'Reilly][]
|
||||
* [StaticGen: Top Open-Source Static Site Generators (GitHub Stars)][]
|
||||
* ["Top 10 Static Website Generators", Netlify blog][]
|
||||
* ["Static Site Generators", O'Reilly]
|
||||
* [StaticGen: Top Open-Source Static Site Generators (GitHub Stars)]
|
||||
* ["Top 10 Static Website Generators", Netlify blog]
|
||||
* ["The Resurgence of Static", dotCMS][dotcms]
|
||||
|
||||
["An Introduction to Static Site Generators", David Walsh]: https://davidwalsh.name/introduction-static-site-generators
|
||||
|
|
|
|||
|
|
@ -17,42 +17,42 @@ toc: true
|
|||
|
||||
## General
|
||||
|
||||
* [Extremely fast][] build times (< 1 ms per page)
|
||||
* [Extremely fast] build times (< 1 ms per page)
|
||||
* Completely cross platform, with [easy installation][install] on macOS, Linux, Windows, and more
|
||||
* Renders changes on the fly with [LiveReload][] as you develop
|
||||
* [Powerful theming][]
|
||||
* Renders changes on the fly with [LiveReload] as you develop
|
||||
* [Powerful theming]
|
||||
* [Host your site anywhere][hostanywhere]
|
||||
|
||||
## Organization
|
||||
|
||||
* Straightforward [organization for your projects][], including website sections
|
||||
* Customizable [URLs][]
|
||||
* Support for configurable [taxonomies][], including categories and tags
|
||||
* [Sort content][] as you desire through powerful template [functions][]
|
||||
* Automatic [table of contents][] generation
|
||||
* [Dynamic menu][] creation
|
||||
* [Pretty URLs][] support
|
||||
* [Permalink][] pattern support
|
||||
* Redirects via [aliases][]
|
||||
* Straightforward [organization for your projects], including website sections
|
||||
* Customizable [URLs]
|
||||
* Support for configurable [taxonomies], including categories and tags
|
||||
* [Sort content] as you desire through powerful template [functions]
|
||||
* Automatic [table of contents] generation
|
||||
* [Dynamic menu] creation
|
||||
* [Pretty URLs] support
|
||||
* [Permalink] pattern support
|
||||
* Redirects via [aliases]
|
||||
|
||||
## Content
|
||||
|
||||
* Native Markdown and Emacs Org-Mode support, as well as other languages via *external helpers* (see [supported formats][])
|
||||
* TOML, YAML, and JSON metadata support in [front matter][]
|
||||
* Customizable [homepage][]
|
||||
* Multiple [content types][]
|
||||
* Automatic and user defined [content summaries][]
|
||||
* [Shortcodes][] to enable rich content inside of Markdown
|
||||
* Native Markdown and Emacs Org-Mode support, as well as other languages via *external helpers* (see [supported formats])
|
||||
* TOML, YAML, and JSON metadata support in [front matter]
|
||||
* Customizable [homepage]
|
||||
* Multiple [content types]
|
||||
* Automatic and user defined [content summaries]
|
||||
* [Shortcodes] to enable rich content inside of Markdown
|
||||
* ["Minutes to Read"][pagevars] functionality
|
||||
* ["WordCount"][pagevars] functionality
|
||||
|
||||
## Additional Features
|
||||
|
||||
* Integrated [Disqus][] comment support
|
||||
* Integrated [Google Analytics][] support
|
||||
* Automatic [RSS][] creation
|
||||
* Support for [Go][] HTML templates
|
||||
* [Syntax highlighting][] powered by [Chroma][]
|
||||
* Integrated [Disqus] comment support
|
||||
* Integrated [Google Analytics] support
|
||||
* Automatic [RSS] creation
|
||||
* Support for [Go] HTML templates
|
||||
* [Syntax highlighting] powered by [Chroma]
|
||||
|
||||
[aliases]: /content-management/urls/#aliases
|
||||
[Chroma]: https://github.com/alecthomas/chroma
|
||||
|
|
|
|||
|
|
@ -17,9 +17,9 @@ aliases: [/overview/introduction/,/about/why-i-built-hugo/]
|
|||
toc: true
|
||||
---
|
||||
|
||||
Hugo is a general-purpose website framework. Technically speaking, Hugo is a [static site generator][]. Unlike systems that dynamically build a page with each visitor request, Hugo builds pages when you create or update your content. Since websites are viewed far more often than they are edited, Hugo is designed to provide an optimal viewing experience for your website's end users and an ideal writing experience for website authors.
|
||||
Hugo is a general-purpose website framework. Technically speaking, Hugo is a [static site generator]. Unlike systems that dynamically build a page with each visitor request, Hugo builds pages when you create or update your content. Since websites are viewed far more often than they are edited, Hugo is designed to provide an optimal viewing experience for your website's end users and an ideal writing experience for website authors.
|
||||
|
||||
Websites built with Hugo are extremely fast and secure. Hugo sites can be hosted anywhere, including [Netlify][], [Heroku][], [GoDaddy][], [DreamHost][], [GitHub Pages][], [GitLab Pages][], [Surge][], [Firebase][], [Google Cloud Storage][], [Amazon S3][], [Rackspace][], [Azure][], and [CloudFront][] and work well with CDNs. Hugo sites run without the need for a database or dependencies on expensive runtimes like Ruby, Python, or PHP.
|
||||
Websites built with Hugo are extremely fast and secure. Hugo sites can be hosted anywhere, including [Netlify], [Heroku], [GoDaddy], [DreamHost], [GitHub Pages], [GitLab Pages], [Surge], [Firebase], [Google Cloud Storage], [Amazon S3], [Rackspace], [Azure], and [CloudFront] and work well with CDNs. Hugo sites run without the need for a database or dependencies on expensive runtimes like Ruby, Python, or PHP.
|
||||
|
||||
We think of Hugo as the ideal website creation tool with nearly instant build times, able to rebuild whenever a change is made.
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ aliases: [/content/archetypes/]
|
|||
|
||||
## What are Archetypes?
|
||||
|
||||
**Archetypes** are content template files in the [archetypes directory][] of your project that contain preconfigured [front matter][] and possibly also a content disposition for your website's [content types][]. These will be used when you run `hugo new`.
|
||||
**Archetypes** are content template files in the [archetypes directory] of your project that contain preconfigured [front matter] and possibly also a content disposition for your website's [content types]. These will be used when you run `hugo new`.
|
||||
|
||||
|
||||
The `hugo new` uses the `content-section` to find the most suitable archetype template in your project. If your project does not contain any archetype files, it will also look in the theme.
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ Disqus comments require you set a single value in your [site's configuration fil
|
|||
disqusShortname = "yourDisqusShortname"
|
||||
{{</ code-toggle >}}
|
||||
|
||||
For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter][] of a single content file:
|
||||
For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter] of a single content file:
|
||||
|
||||
* `disqus_identifier`
|
||||
* `disqus_title`
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ weight: 60
|
|||
aliases: [/content/front-matter/]
|
||||
---
|
||||
|
||||
**Front matter** allows you to keep metadata attached to an instance of a [content type][]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength.
|
||||
**Front matter** allows you to keep metadata attached to an instance of a [content type]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength.
|
||||
|
||||
{{< youtube Yh2xKRJGff4 >}}
|
||||
|
||||
|
|
@ -122,7 +122,7 @@ title
|
|||
: the title for the content.
|
||||
|
||||
type
|
||||
: the type of the content; this value will be automatically derived from the directory (i.e., the [section][]) if not specified in front matter.
|
||||
: the type of the content; this value will be automatically derived from the directory (i.e., the [section]) if not specified in front matter.
|
||||
|
||||
url
|
||||
: the full path to the content from the web root. It makes no assumptions about the path of the content file. See [URL Management](/content-management/urls/#set-url-in-front-matter).
|
||||
|
|
@ -144,7 +144,7 @@ If neither `slug` nor `url` is present and [permalinks are not configured otherw
|
|||
|
||||
You can add fields to your front matter arbitrarily to meet your needs. These user-defined key-values are placed into a single `.Params` variable for use in your templates.
|
||||
|
||||
The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables][] section provides more information on using Hugo's page- and site-level variables in your templates.
|
||||
The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables] section provides more information on using Hugo's page- and site-level variables in your templates.
|
||||
|
||||
{{< code-toggle copy="false" >}}
|
||||
include_toc: true
|
||||
|
|
|
|||
|
|
@ -220,10 +220,6 @@ slug: "a-propos"
|
|||
|
||||
At render, Hugo will build both `/about/` and `/fr/a-propos/` while maintaining their translation linking.
|
||||
|
||||
{{% note %}}
|
||||
If using `url`, remember to include the language part as well: `/fr/compagnie/a-propos/`.
|
||||
{{%/ note %}}
|
||||
|
||||
### Page Bundles
|
||||
|
||||
To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (Markdown files, HTML files etc...).
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ The bundle documentation is a **work in progress**. We will publish more compreh
|
|||
|
||||
In Hugo, your content should be organized in a manner that reflects the rendered website.
|
||||
|
||||
While Hugo supports content nested at any level, the top levels (i.e. `content/<DIRECTORIES>`) are special in Hugo and are considered the content type used to determine layouts etc. To read more about sections, including how to nest them, see [sections][].
|
||||
While Hugo supports content nested at any level, the top levels (i.e. `content/<DIRECTORIES>`) are special in Hugo and are considered the content type used to determine layouts etc. To read more about sections, including how to nest them, see [sections].
|
||||
|
||||
Without any additional configuration, the following will automatically work:
|
||||
|
||||
|
|
@ -59,7 +59,7 @@ The following demonstrates the relationships between your content organization a
|
|||
|
||||
### Index Pages: `_index.md`
|
||||
|
||||
`_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists]. These templates include those for [section templates][], [taxonomy templates][], [taxonomy terms templates][], and your [homepage template][].
|
||||
`_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists]. These templates include those for [section templates], [taxonomy templates], [taxonomy terms templates], and your [homepage template].
|
||||
|
||||
{{% note %}}
|
||||
**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/functions/getpage/).
|
||||
|
|
|
|||
|
|
@ -86,11 +86,11 @@ Also see [Page Variables](/variables/page/).
|
|||
|
||||
## Content Section Lists
|
||||
|
||||
Hugo will automatically create a page for each *root section* that lists all the content in that section. See the documentation on [section templates][] for details on customizing the way these pages are rendered.
|
||||
Hugo will automatically create a page for each *root section* that lists all the content in that section. See the documentation on [section templates] for details on customizing the way these pages are rendered.
|
||||
|
||||
## Content *Section* vs Content *Type*
|
||||
|
||||
By default, everything created within a section will use the [content `type`][content type] that matches the *root section* name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content `type`. If you are using an [archetype][] for your `posts` section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`.
|
||||
By default, everything created within a section will use the [content `type`][content type] that matches the *root section* name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content `type`. If you are using an [archetype] for your `posts` section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`.
|
||||
|
||||
[archetype]: /content-management/archetypes/
|
||||
[content type]: /content-management/types/
|
||||
|
|
|
|||
|
|
@ -214,7 +214,7 @@ To see even more options for adding syntax-highlighted code blocks to your websi
|
|||
|
||||
### `instagram`
|
||||
|
||||
If you'd like to embed a photo from [Instagram][], you only need the photo's ID. You can discern an Instagram photo ID from the URL:
|
||||
If you'd like to embed a photo from [Instagram], you only need the photo's ID. You can discern an Instagram photo ID from the URL:
|
||||
|
||||
```txt
|
||||
https://www.instagram.com/p/BWNjjyYFxVx/
|
||||
|
|
@ -329,7 +329,7 @@ Using the preceding `tweet` example, the following simulates the displayed exper
|
|||
|
||||
### `vimeo`
|
||||
|
||||
Adding a video from [Vimeo][] is equivalent to the [YouTube Input shortcode][].
|
||||
Adding a video from [Vimeo] is equivalent to the [YouTube Input shortcode].
|
||||
|
||||
```txt
|
||||
https://vimeo.com/channels/staffpicks/146022717
|
||||
|
|
@ -367,7 +367,7 @@ Using the preceding `vimeo` example, the following simulates the displayed exper
|
|||
|
||||
### `youtube`
|
||||
|
||||
The `youtube` shortcode embeds a responsive video player for [YouTube videos][]. Only the ID of the video is required, e.g.:
|
||||
The `youtube` shortcode embeds a responsive video player for [YouTube videos]. Only the ID of the video is required, e.g.:
|
||||
|
||||
```txt
|
||||
https://www.youtube.com/watch?v=w7Ft2ymGmfc
|
||||
|
|
@ -410,11 +410,11 @@ Using the preceding `youtube` example (without `autoplay="true"`), the following
|
|||
|
||||
## Privacy Config
|
||||
|
||||
To learn how to configure your Hugo site to meet the new EU privacy regulation, see [Hugo and the GDPR][].
|
||||
To learn how to configure your Hugo site to meet the new EU privacy regulation, see [Hugo and the GDPR].
|
||||
|
||||
## Create Custom Shortcodes
|
||||
|
||||
To learn more about creating custom shortcodes, see the [shortcode template documentation][].
|
||||
To learn more about creating custom shortcodes, see the [shortcode template documentation].
|
||||
|
||||
[`figure` shortcode]: #figure
|
||||
[contentmanagementsection]: /content-management/formats/
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ all **static files** (e.g. stylesheets, JavaScript, images). The static files ar
|
|||
|
||||
Hugo can be configured to look into a different directory, or even
|
||||
**multiple directories** for such static files by configuring the
|
||||
`staticDir` parameter in the [site config][]. All the files in all the
|
||||
`staticDir` parameter in the [site config]. All the files in all the
|
||||
static directories will form a union filesystem.
|
||||
|
||||
This union filesystem will be served from your site root. So a file
|
||||
|
|
@ -62,7 +62,7 @@ Note 1
|
|||
can be seen in the Norwegian site case).
|
||||
|
||||
Note 2
|
||||
: The example above is a [multihost setup][]. In a regular setup, all
|
||||
: The example above is a [multihost setup]. In a regular setup, all
|
||||
the static directories will be available to all sites.
|
||||
|
||||
[site config]: /getting-started/configuration/#all-configuration-settings
|
||||
|
|
|
|||
|
|
@ -81,7 +81,7 @@ Hugo uses the _first_ of the above steps that returns text. So if, for example,
|
|||
|
||||
## Example: First 10 Articles with Summaries
|
||||
|
||||
You can show content summaries with the following code. You could use the following snippet, for example, in a [section template][].
|
||||
You can show content summaries with the following code. You could use the following snippet, for example, in a [section template].
|
||||
|
||||
{{< code file="page-list-with-summaries.html" >}}
|
||||
{{ range first 10 .Pages }}
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ Let's assume you are making a website about movies. You may want to include the
|
|||
* Year
|
||||
* Awards
|
||||
|
||||
Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the [front matter][] of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award.
|
||||
Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the [front matter] of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award.
|
||||
|
||||
### Movie Taxonomy Organization
|
||||
|
||||
|
|
@ -99,10 +99,10 @@ disableKinds = ["taxonomy","term"]
|
|||
|
||||
### Default Destinations
|
||||
|
||||
When taxonomies are used---and [taxonomy templates][] are provided---Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your configuration and used in your content front matter will create the following pages:
|
||||
When taxonomies are used---and [taxonomy templates] are provided---Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your configuration and used in your content front matter will create the following pages:
|
||||
|
||||
* A single page at `example.com/categories/` that lists all the [terms within the taxonomy][]
|
||||
* [Individual taxonomy list pages][taxonomy templates] (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's [front matter][]
|
||||
* A single page at `example.com/categories/` that lists all the [terms within the taxonomy]
|
||||
* [Individual taxonomy list pages][taxonomy templates] (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's [front matter]
|
||||
|
||||
## Configure Taxonomies
|
||||
|
||||
|
|
@ -146,9 +146,9 @@ You can now use `.Page.Title` on the relevant taxonomy node to get the original
|
|||
|
||||
## Add Taxonomies to Content
|
||||
|
||||
Once a taxonomy is defined at the site level, any piece of content can be assigned to it, regardless of [content type][] or [content section][].
|
||||
Once a taxonomy is defined at the site level, any piece of content can be assigned to it, regardless of [content type] or [content section].
|
||||
|
||||
Assigning content to a taxonomy is done in the [front matter][]. Simply create a variable with the *plural* name of the taxonomy and assign all terms you want to apply to the instance of the content type.
|
||||
Assigning content to a taxonomy is done in the [front matter]. Simply create a variable with the *plural* name of the taxonomy and assign all terms you want to apply to the instance of the content type.
|
||||
|
||||
{{% note %}}
|
||||
If you would like the ability to quickly generate content files with preconfigured taxonomies or terms, read the docs on [Hugo archetypes](/content-management/archetypes/).
|
||||
|
|
@ -167,7 +167,7 @@ project_url = "https://github.com/gohugoio/hugo"
|
|||
|
||||
## Order Taxonomies
|
||||
|
||||
A content file can assign weight for each of its associate taxonomies. Taxonomic weight can be used for sorting or ordering content in [taxonomy list templates][] and is declared in a content file's [front matter][]. The convention for declaring taxonomic weight is `taxonomyname_weight`.
|
||||
A content file can assign weight for each of its associate taxonomies. Taxonomic weight can be used for sorting or ordering content in [taxonomy list templates] and is declared in a content file's [front matter]. The convention for declaring taxonomic weight is `taxonomyname_weight`.
|
||||
|
||||
The following show a piece of content that has a weight of 22, which can be used for ordering purposes when rendering the pages assigned to the "a", "b" and "c" values of the `tags` taxonomy. It has also been assigned the weight of 44 when rendering the "d" category page.
|
||||
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ The built-in `.TableOfContents` variables outputs a `<nav id="TableOfContents">`
|
|||
|
||||
## Template Example: Basic TOC
|
||||
|
||||
The following is an example of a very basic [single page template][]:
|
||||
The following is an example of a very basic [single page template]:
|
||||
|
||||
{{< code file="layout/_default/single.html" download="single.html" >}}
|
||||
{{ define "main" }}
|
||||
|
|
@ -67,7 +67,7 @@ The following is an example of a very basic [single page template][]:
|
|||
|
||||
## Template Example: TOC Partial
|
||||
|
||||
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:
|
||||
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 ) (.Params.toc) }}
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ 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 `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.
|
||||
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
|
||||
|
||||
|
|
@ -211,7 +211,7 @@ content/posts/post-1.md
|
|||
|
||||
If you would like to have what are often referred to as "ugly URLs" (e.g., example.com/urls.html), set `uglyurls = true` or `uglyurls: true` in your site's `config.toml` or `config.yaml`, respectively. You can also set the `HUGO_UGLYURLS` environment variable to `true` when running `hugo` or `hugo server`.
|
||||
|
||||
If you want a specific piece of content to have an exact URL, you can specify this in the [front matter][] under the `url` key. The following are examples of the same content directory and what the eventual URL structure will be when Hugo runs with its default behavior.
|
||||
If you want a specific piece of content to have an exact URL, you can specify this in the [front matter] under the `url` key. The following are examples of the same content directory and what the eventual URL structure will be when Hugo runs with its default behavior.
|
||||
|
||||
See [Content Organization][contentorg] for more details on paths.
|
||||
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ toc: true
|
|||
|
||||
## Introduction
|
||||
|
||||
Hugo is an open-source project and lives by the work of its [contributors][]. There are plenty of [open issues][issues], and we need your help to make Hugo even more awesome. You don't need to be a Go guru to contribute to the project's development.
|
||||
Hugo is an open-source project and lives by the work of its [contributors]. There are plenty of [open issues][issues], and we need your help to make Hugo even more awesome. You don't need to be a Go guru to contribute to the project's development.
|
||||
|
||||
## Assumptions
|
||||
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ git checkout -b jon-doe-showcase-addition
|
|||
|
||||
## Add New Content
|
||||
|
||||
The Hugo docs make heavy use of Hugo's [archetypes][] feature. All content sections in Hugo documentation have an assigned archetype.
|
||||
The Hugo docs make heavy use of Hugo's [archetypes] feature. All content sections in Hugo documentation have an assigned archetype.
|
||||
|
||||
Adding new content to the Hugo docs follows the same pattern, regardless of the content section:
|
||||
|
||||
|
|
@ -79,7 +79,7 @@ Here is a review of the front matter fields automatically generated for you usin
|
|||
: the version of Hugo that will ship with this new function.
|
||||
|
||||
`relatedfuncs`
|
||||
: other [templating functions][] you feel are related to your new function to help fellow Hugo users.
|
||||
: other [templating functions] you feel are related to your new function to help fellow Hugo users.
|
||||
|
||||
`{{.Content}}`
|
||||
: an extended description of the new function; examples are not only welcomed but encouraged.
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@ The previous examples have used the full content filename to look up the post. D
|
|||
|
||||
This code snippet---in the form of a [partial template][partials]---allows you to do the following:
|
||||
|
||||
1. Grab the index object of your `tags` [taxonomy][].
|
||||
1. Grab the index object of your `tags` [taxonomy].
|
||||
2. Assign this object to a variable, `$t`
|
||||
3. Sort the terms associated with the taxonomy by popularity.
|
||||
4. Grab the top two most popular terms in the taxonomy (i.e., the two most popular tags assigned to content.
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ The following shows `after` being used in conjunction with the [`slice` function
|
|||
|
||||
## Example of `after` with `first`: 2nd–4th Most Recent Articles
|
||||
|
||||
You can use `after` in combination with the [`first` function][] and Hugo's [powerful sorting methods][lists]. Let's assume you have a list page at `example.com/articles`. You have 10 articles, but you want your templating for the [list/section page][] to show only two rows:
|
||||
You can use `after` in combination with the [`first` function] and Hugo's [powerful sorting methods][lists]. Let's assume you have a list page at `example.com/articles`. You have 10 articles, but you want your templating for the [list/section page] to show only two rows:
|
||||
|
||||
1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter).
|
||||
2. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles.
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ Which will result in the following:
|
|||
"derek-perkins", "joe-bergevin", "tanner-linsley"
|
||||
```
|
||||
|
||||
This is *roughly* equivalent to using the following with [range][]:
|
||||
This is *roughly* equivalent to using the following with [range]:
|
||||
|
||||
```
|
||||
{{ range .Params.names }}{{ . | urlize }}{{ end }}
|
||||
|
|
@ -56,7 +56,7 @@ This is *roughly* equivalent to using the following with [range][]:
|
|||
|
||||
However, it is not possible to provide the output of a range to the [`delimit` function][delimit], so you need to `apply` it.
|
||||
|
||||
If you have `post-tag-list.html` and `post-tag-link.html` as [partials][], you *could* use the following snippets, respectively:
|
||||
If you have `post-tag-list.html` and `post-tag-link.html` as [partials], you *could* use the following snippets, respectively:
|
||||
|
||||
{{< code file="layouts/partials/post-tag-list.html" copy="false" >}}
|
||||
{{ with .Params.tags }}
|
||||
|
|
@ -96,7 +96,7 @@ This first version of `layouts/partials/post-tag-list.html` separates all of the
|
|||
{{ end }}
|
||||
```
|
||||
|
||||
Now in the completed version, you can sort the tags, convert the tags to links with `layouts/partials/post-tag-link.html`, [chomp][] off stray newlines, and join the tags together in a delimited list for presentation. Here is an even DRYer version of the preceding example:
|
||||
Now in the completed version, you can sort the tags, convert the tags to links with `layouts/partials/post-tag-link.html`, [chomp] off stray newlines, and join the tags together in a delimited list for presentation. Here is an even DRYer version of the preceding example:
|
||||
|
||||
{{< code file="layouts/partials/post-tag-list.html" download="post-tag-list.html" >}}
|
||||
{{ with .Params.tags }}
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@ Here is a visual explanation [taken directly from the Go docs][gdex]:
|
|||
|
||||
The following examples show the layout string followed by the rendered output.
|
||||
|
||||
The examples were rendered and tested in [CST][] and all point to the same field in a content file's front matter:
|
||||
The examples were rendered and tested in [CST] and all point to the same field in a content file's front matter:
|
||||
|
||||
```
|
||||
date: 2017-03-03T14:15:59-06:00
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ aliases: []
|
|||
>
|
||||
> Channel: the number of elements queued (unread) in the channel buffer; if v is nil, len(v) is zero.
|
||||
|
||||
`len` is also considered a [fundamental function for Hugo templating][].
|
||||
`len` is also considered a [fundamental function for Hugo templating].
|
||||
|
||||
## `len` Example 1: Longer Headings
|
||||
|
||||
|
|
@ -45,15 +45,15 @@ 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" "==" "posts") }}
|
||||
{{ $postCount := len $posts }}
|
||||
{{< /code >}}
|
||||
|
||||
Note the use of `.RegularPages`, a [site variable][] that counts all regular content pages but not the `_index.md` pages used to add front matter and content to [list templates][].
|
||||
Note the use of `.RegularPages`, a [site variable] that counts all regular content pages but not the `_index.md` pages used to add front matter and content to [list templates].
|
||||
|
||||
|
||||
[fundamental function for Hugo templating]: /templates/introduction/
|
||||
|
|
|
|||
|
|
@ -23,6 +23,6 @@ aliases: []
|
|||
{{ .Title | markdownify }}
|
||||
```
|
||||
|
||||
{{< new-in "0.93.0" >}} **Note**: `markdownify` now supports [Render Hooks][] just like [.RenderString](/functions/renderstring/).
|
||||
{{< new-in "0.93.0" >}} **Note**: `markdownify` now supports [Render Hooks] just like [.RenderString](/functions/renderstring/).
|
||||
|
||||
[Render Hooks]: /templates/render-hooks/
|
||||
|
|
|
|||
|
|
@ -19,11 +19,11 @@ draft: false
|
|||
aliases: []
|
||||
---
|
||||
|
||||
In Hugo, you can declare [site-wide params][sitevars] (i.e. in your [configuration][]), as well as params for [individual pages][pagevars].
|
||||
In Hugo, you can declare [site-wide params][sitevars] (i.e. in your [configuration]), as well as params for [individual pages][pagevars].
|
||||
|
||||
A common use case is to have a general value for the site and a more specific value for some of the pages (e.g., an image).
|
||||
|
||||
You can use the `.Param` method to call these values into your template. The following will first look for an `image` param in a specific content's [front matter][]. If not found, Hugo will look for an `image` param in your site's configuration:
|
||||
You can use the `.Param` method to call these values into your template. The following will first look for an `image` param in a specific content's [front matter]. If not found, Hugo will look for an `image` param in your site's configuration:
|
||||
|
||||
```
|
||||
$.Param "image"
|
||||
|
|
|
|||
|
|
@ -22,6 +22,8 @@ The `partialCached` template function can offer significant performance gains fo
|
|||
|
||||
**Note:** Each Site (or language) has its own `partialCached` cache, so each site will execute a partial once.
|
||||
|
||||
**Note**: Hugo renders pages in parallel, and will render the partial more than once with concurrent calls to the `partialCached` function. After Hugo caches the rendered partial, new pages entering the build pipeline will use the cached result.
|
||||
|
||||
Here is the simplest usage:
|
||||
|
||||
```
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ aliases: []
|
|||
|
||||
The view is an alternative layout and should be a file name that points to a template in one of the locations specified in the documentation for [Content Views](/templates/views).
|
||||
|
||||
This function is only available when applied to a single piece of content within a [list context][].
|
||||
This function is only available when applied to a single piece of content within a [list context].
|
||||
|
||||
This example could render a piece of content using the content view located at `/layouts/_default/summary.html`:
|
||||
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ deprecated: false
|
|||
aliases: []
|
||||
---
|
||||
|
||||
`safeURL` declares the provided string as a "safe" URL or URL substring (see [RFC 3986][]). A URL like `javascript:checkThatFormNotEditedBeforeLeavingPage()` from a trusted source should go in the page, but by default dynamic `javascript:` URLs are filtered out since they are a frequently exploited injection vector.
|
||||
`safeURL` declares the provided string as a "safe" URL or URL substring (see [RFC 3986]). A URL like `javascript:checkThatFormNotEditedBeforeLeavingPage()` from a trusted source should go in the page, but by default dynamic `javascript:` URLs are filtered out since they are a frequently exploited injection vector.
|
||||
|
||||
Without `safeURL`, only the URI schemes `http:`, `https:` and `mailto:` are considered safe by Go templates. If any other URI schemes (e.g., `irc:` and `javascript:`) are detected, the whole URL will be replaced with `#ZgotmplZ`. This is to "defang" any potential attack in the URL by rendering it useless.
|
||||
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ draft: false
|
|||
aliases: []
|
||||
---
|
||||
|
||||
It's named and used in the model of [GNU's seq][].
|
||||
It's named and used in the model of [GNU's seq].
|
||||
|
||||
```
|
||||
3 → 1, 2, 3
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ aliases: []
|
|||
toc: false
|
||||
---
|
||||
|
||||
One use case is the concatenation of elements in combination with the [`delimit` function][]:
|
||||
One use case is the concatenation of elements in combination with the [`delimit` function]:
|
||||
|
||||
{{< code file="slice.html" >}}
|
||||
{{ $sliceOfStrings := slice "foo" "bar" "buzz" }}
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ If no `TIMEZONE` is set, the `timeZone` from site configuration will be used.
|
|||
|
||||
## Example: Using `time` to get Month Index
|
||||
|
||||
The following example takes a UNIX timestamp---set as `utimestamp: "1489276800"` in a content's front matter---converts the timestamp (string) to an integer using the [`int` function][int], and then uses [`printf`][] to convert the `Month` property of `time` into an index.
|
||||
The following example takes a UNIX timestamp---set as `utimestamp: "1489276800"` in a content's front matter---converts the timestamp (string) to an integer using the [`int` function][int], and then uses [`printf`] to convert the `Month` property of `time` into an index.
|
||||
|
||||
The following example may be useful when setting up [multilingual sites][multilingual]:
|
||||
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ aliases: [/overview/introduction/]
|
|||
toc: false
|
||||
---
|
||||
|
||||
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.
|
||||
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/
|
||||
|
|
|
|||
|
|
@ -554,7 +554,7 @@ force = false
|
|||
|
||||
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 {#_404-server-error-page}
|
||||
|
||||
{{< new-in "0.103.0" >}}
|
||||
|
||||
|
|
@ -567,19 +567,6 @@ Hugo will, by default, render all 404 errors when running `hugo server` with the
|
|||
status = 404
|
||||
```
|
||||
|
||||
## 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 Config](#server-config), you need to add the 404 redirect explicitly, e.g:
|
||||
|
||||
```toml
|
||||
[[redirects]]
|
||||
from = "/**"
|
||||
to = "/404.html"
|
||||
status = 404
|
||||
```
|
||||
|
||||
## Configure Title Case
|
||||
|
||||
Set `titleCaseStyle` to specify the title style used by the [title](/functions/title/) template function and the automatic section titles in Hugo. It defaults to [AP Stylebook](https://www.apstylebook.com/) for title casing, but you can also set it to `Chicago` or `Go` (every word starts with a capital letter).
|
||||
|
|
@ -591,7 +578,7 @@ HUGO_NUMWORKERMULTIPLIER
|
|||
|
||||
## Configuration Lookup Order
|
||||
|
||||
Similar to the template [lookup order][], Hugo has a default set of rules for searching for a configuration file in the root of your website's source directory as a default behavior:
|
||||
Similar to the template [lookup order], Hugo has a default set of rules for searching for a configuration file in the root of your website's source directory as a default behavior:
|
||||
|
||||
1. `./config.toml`
|
||||
2. `./config.yaml`
|
||||
|
|
@ -602,7 +589,7 @@ In your `config` file, you can direct Hugo as to how you want your website rende
|
|||
|
||||
## Example Configuration
|
||||
|
||||
The following is a typical example of a configuration file. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]:
|
||||
The following is a typical example of a configuration file. The values nested under `params:` will populate the [`.Site.Params`] variable for use in [templates]:
|
||||
|
||||
{{< code-toggle file="config">}}
|
||||
baseURL: "https://yoursite.example.com/"
|
||||
|
|
@ -645,6 +632,8 @@ Test and document setting params via JSON env var.
|
|||
|
||||
## Ignore Content and Data Files when Rendering
|
||||
|
||||
**Note:** This works, but we recommend you use the newer and more powerful [includeFiles and excludeFiles](https://gohugo.io/hugo-modules/configuration/#module-config-mounts) mount options.
|
||||
|
||||
To exclude specific files from the `content` and `data` 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`:
|
||||
|
|
@ -721,7 +710,7 @@ The above will try first to extract the value for `.Date` from the filename, the
|
|||
|
||||
## 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.
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -42,36 +42,36 @@ The following is a high-level overview of each of the directories with links to
|
|||
|
||||
[`archetypes`](/content-management/archetypes/)
|
||||
: You can create new content files in Hugo using the `hugo new` command.
|
||||
By default, Hugo will create new content files with at least `date`, `title` (inferred from the filename), and `draft = true`. This saves time and promotes consistency for sites using multiple content types. You can create your own [archetypes][] with custom preconfigured front matter fields as well.
|
||||
By default, Hugo will create new content files with at least `date`, `title` (inferred from the filename), and `draft = true`. This saves time and promotes consistency for sites using multiple content types. You can create your own [archetypes] with custom preconfigured front matter fields as well.
|
||||
|
||||
[`assets`][]
|
||||
[`assets`]
|
||||
: Stores all the files which need be processed by [Hugo Pipes](/hugo-pipes/). Only the files whose `.Permalink` or `.RelPermalink` are used will be published to the `public` directory.
|
||||
|
||||
[`config`](/getting-started/configuration/)
|
||||
: Hugo ships with a large number of [configuration directives][].
|
||||
: Hugo ships with a large number of [configuration directives].
|
||||
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. Note: config directory is not created by default.
|
||||
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. Note: config directory is not created by default.
|
||||
|
||||
[`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][].
|
||||
[`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].
|
||||
|
||||
[`data`](/templates/data-templates/)
|
||||
: This directory is used to store configuration files that can be
|
||||
used by Hugo when generating your website. You can write these files in YAML, JSON, or TOML format. In addition to the files you add to this folder, you can also create [data templates][] that pull from dynamic content.
|
||||
used by Hugo when generating your website. You can write these files in YAML, JSON, or TOML format. In addition to the files you add to this folder, you can also create [data templates] that pull from dynamic content.
|
||||
|
||||
[`layouts`][]
|
||||
: Stores templates in the form of `.html` files that specify how views of your content will be rendered into a static website. Templates include [list pages][lists], your [homepage][], [taxonomy templates][], [partials][], [single page templates][singles], and more.
|
||||
[`layouts`]
|
||||
: Stores templates in the form of `.html` files that specify how views of your content will be rendered into a static website. Templates include [list pages][lists], your [homepage], [taxonomy templates], [partials], [single page templates][singles], and more.
|
||||
|
||||
[`static`][]
|
||||
[`static`]
|
||||
: Stores all the static content: images, CSS, JavaScript, etc. When Hugo builds your site, all assets inside your static directory are copied over as-is. A good example of using the `static` folder is for [verifying site ownership on Google Search Console][searchconsole], where you want Hugo to copy over a complete HTML file without modifying its content.
|
||||
|
||||
{{% note %}}
|
||||
From **Hugo 0.31** you can have multiple static directories.
|
||||
{{% /note %}}
|
||||
|
||||
[`resources`][]
|
||||
[`resources`]
|
||||
: Caches some files to speed up generation. Can be also used by template authors to distribute built Sass files, so you don't have to have the preprocessor installed. Note: resources directory is not created by default.
|
||||
|
||||
[archetypes]: /content-management/archetypes/
|
||||
|
|
|
|||
|
|
@ -33,9 +33,13 @@ You must also be comfortable working from the command line.
|
|||
|
||||
### Commands
|
||||
|
||||
Run these commands[^1] to create a Hugo site with the [Ananke] theme. The next section provides an explanation of each command.
|
||||
{{% note %}}
|
||||
If you are a Windows user, you must run these commands with [PowerShell]. You cannot use Windows Powershell, which is a different application, or the Command Prompt. You may also use a Linux shell if available.
|
||||
|
||||
[^1]: If you are a Windows user, you must run these commands with [PowerShell]. You cannot use Windows Powershell, which is a different application, or the Command Prompt.
|
||||
[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows
|
||||
{{% /note %}}
|
||||
|
||||
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
|
||||
|
|
@ -210,7 +214,6 @@ For other resources to help you learn Hugo, including books and video tutorials,
|
|||
[hosting and deployment]: /hosting-and-deployment/
|
||||
[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
|
||||
[Install Hugo]: /installation/
|
||||
[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows
|
||||
[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/
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@ AWS Amplify is a combination of client library, CLI toolchain, and a Console for
|
|||
|
||||
* [Sign up for an AWS Account](https://portal.aws.amazon.com/billing/signup?redirect_url=https%3A%2F%2Faws.amazon.com%2Fregistration-confirmation). There are no upfront charges or any term commitments to create an AWS account and signing up gives you immediate access to the AWS Free Tier.
|
||||
* You have an account with GitHub, GitLab, or Bitbucket.
|
||||
* You have completed the [Quick Start][] or have a Hugo website you are ready to deploy and share with the world.
|
||||
* You have completed the [Quick Start] or have a Hugo website you are ready to deploy and share with the world.
|
||||
|
||||
## Hosting
|
||||
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@ _The following documentation covers how to use GitHub Actions for the deployment
|
|||
1. You have Git 2.8 or greater [installed on your machine][installgit].
|
||||
2. You have a GitHub account. [Signing up][ghsignup] for GitHub is free.
|
||||
3. You have an Azure account. You can sign up for a [Free Trail][azuretrial].
|
||||
4. You have a ready-to-publish Hugo website or have at least completed the [Quick Start][].
|
||||
4. You have a ready-to-publish Hugo website or have at least completed the [Quick Start].
|
||||
|
||||
## Deploy Hugo to Azure Static Web Apps
|
||||
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ aliases: []
|
|||
## Assumptions
|
||||
|
||||
1. You have an account with [Firebase][signup]. (If you don't, you can sign up for free using your Google account.)
|
||||
2. You have completed the [Quick Start][] or have a completed Hugo website ready for deployment.
|
||||
2. You have completed the [Quick Start] or have a completed Hugo website ready for deployment.
|
||||
|
||||
## Initial setup
|
||||
|
||||
|
|
@ -62,11 +62,11 @@ Here you will be redirected to login in your GitHub account to get permissions.
|
|||
7. For which GitHub repository would you like to set up a GitHub workflow? (format: user/repository)
|
||||
|
||||
Include the repository you will use in the format above (Account/Repo)
|
||||
Firebase script with retrive credentials, create a service account you can later manage in yout github settings.
|
||||
Firebase script with retrive credentials, create a service account you can later manage in your github settings.
|
||||
|
||||
8. Set up the workflow to run a build script before every deploy?
|
||||
|
||||
Here is your oportunity to include some commands before you run the deploy.
|
||||
Here is your opportunity to include some commands before you run the deploy.
|
||||
|
||||
9. Set up automatic deployment to your site's live channel when a PR is merged?
|
||||
|
||||
|
|
@ -78,7 +78,7 @@ After that Firebase has been set in your project with CI/CD. After that run:
|
|||
hugo && firebase deploy
|
||||
```
|
||||
|
||||
With this you will have the app initialized manualy. After that you can manage and fix your github workflow from: https://github.com/your-account/yout-repo/actions
|
||||
With this you will have the app initialized manually. After that you can manage and fix your github workflow from: https://github.com/your-account/yout-repo/actions
|
||||
|
||||
Don't forget to update your static pages before push!
|
||||
|
||||
|
|
|
|||
|
|
@ -17,13 +17,13 @@ toc: true
|
|||
aliases: [/tutorials/github-pages-blog/]
|
||||
---
|
||||
|
||||
GitHub provides free and fast static hosting over SSL for personal, organization, or project pages directly from a GitHub repository via its [GitHub Pages service][] and automating development workflows and build with [GitHub Actions].
|
||||
GitHub provides free and fast static hosting over SSL for personal, organization, or project pages directly from a GitHub repository via its [GitHub Pages service] and automating development workflows and build with [GitHub Actions].
|
||||
|
||||
## Assumptions
|
||||
|
||||
1. You have Git 2.8 or greater [installed on your machine][installgit].
|
||||
2. You have a GitHub account. [Signing up][ghsignup] for GitHub is free.
|
||||
3. You have a ready-to-publish Hugo website or have at least completed the [Quick Start][].
|
||||
3. You have a ready-to-publish Hugo website or have at least completed the [Quick Start].
|
||||
|
||||
## Types of GitHub Pages
|
||||
|
||||
|
|
|
|||
|
|
@ -22,12 +22,12 @@ toc: true
|
|||
## Assumptions
|
||||
|
||||
* You have an account with GitHub, GitLab, or Bitbucket.
|
||||
* You have completed the [Quick Start][] or have a Hugo website you are ready to deploy and share with the world.
|
||||
* You have completed the [Quick Start] or have a Hugo website you are ready to deploy and share with the world.
|
||||
* You do not already have a Netlify account.
|
||||
|
||||
## Create a Netlify account
|
||||
|
||||
Go to [app.netlify.com][] and select your preferred signup method. This will likely be a hosted Git provider, although you also have the option to sign up with an email address.
|
||||
Go to [app.netlify.com] and select your preferred signup method. This will likely be a hosted Git provider, although you also have the option to sign up with an email address.
|
||||
|
||||
The following examples use GitHub, but other git providers will follow a similar process.
|
||||
|
||||
|
|
@ -55,7 +55,7 @@ Select the repo you want to use for continuous deployment. If you have a large n
|
|||
|
||||
|
||||
|
||||
Once selected, you'll be brought to a screen for basic setup. Here you can select the branch you want to publish, your [build command][], and your publish (i.e. deploy) directory. The publish directory should mirror that of what you've set in your [site configuration][config], the default of which is `public`. The following steps assume you are publishing from the `master` branch.
|
||||
Once selected, you'll be brought to a screen for basic setup. Here you can select the branch you want to publish, your [build command], and your publish (i.e. deploy) directory. The publish directory should mirror that of what you've set in your [site configuration][config], the default of which is `public`. The following steps assume you are publishing from the `master` branch.
|
||||
|
||||
## Configure Hugo version in Netlify
|
||||
|
||||
|
|
@ -136,9 +136,9 @@ git submodule update --rebase --remote
|
|||
|
||||
You now have a live website served over HTTPS, distributed through CDN, and configured for continuous deployment. Dig deeper into the Netlify documentation:
|
||||
|
||||
1. [Using a Custom Domain][]
|
||||
1. [Using a Custom Domain]
|
||||
2. [Setting up HTTPS on Custom Domains][httpscustom]
|
||||
3. [Redirects and Rewrite Rules][]
|
||||
3. [Redirects and Rewrite Rules]
|
||||
|
||||
[app.netlify.com]: https://app.netlify.com
|
||||
[build command]: /getting-started/usage/#the-hugo-command
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ Static sites are **completely free** on Render and include the following:
|
|||
## Assumptions
|
||||
|
||||
- You have an account with GitHub or GitLab.
|
||||
- You have completed the [Quick Start][] or have a Hugo website you are ready to deploy and share with the world.
|
||||
- You have completed the [Quick Start] or have a Hugo website you are ready to deploy and share with the world.
|
||||
- You have a Render account. You can sign up at https://render.com/register.
|
||||
|
||||
## Deployment
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ You can use the "hugo deploy" command to upload your site directly to a Google C
|
|||
|
||||
## Assumptions
|
||||
|
||||
* You have completed the [Quick Start][] or have a Hugo website you are ready to deploy and share with the world.
|
||||
* You have completed the [Quick Start] or have a Hugo website you are ready to deploy and share with the world.
|
||||
* You have an account with the service provider ([Google Cloud](https://cloud.google.com/), [AWS](https://aws.amazon.com), or [Azure](https://azure.microsoft.com)) that you want to deploy to.
|
||||
* You have authenticated.
|
||||
* Google Cloud: [Install the CLI](https://cloud.google.com/sdk) and run [`gcloud auth login`](https://cloud.google.com/sdk/gcloud/reference/auth/login).
|
||||
|
|
@ -140,4 +140,3 @@ See `hugo help deploy` for more command-line options.
|
|||
[Google Cloud]: [https://cloud.google.com]
|
||||
[AWS]: [https://aws.amazon.com]
|
||||
[Azure]: [https://azure.microsoft.com]
|
||||
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ You can even nest this, and have the theme component itself include theme compon
|
|||
|
||||
The theme definition example above in `config.toml` creates a theme with 3 theme components with precedence from left to right.
|
||||
|
||||
For any given file, data entry, etc., Hugo will look first in the project and then in `my-shortcode`, `base-theme`, and lastly `hyde`.
|
||||
For any given file, data entry, etc., Hugo will look first in the project and then in `my-shortcodes`, `base-theme`, and lastly `hyde`.
|
||||
|
||||
Hugo uses two different algorithms to merge the filesystems, depending on the file type:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,6 @@
|
|||
---
|
||||
title: PostCSS
|
||||
description: Hugo Pipes can process CSS files with PostCSS.
|
||||
date: 2018-07-14
|
||||
publishdate: 2018-07-14
|
||||
categories: [asset management]
|
||||
keywords: []
|
||||
menu:
|
||||
|
|
@ -10,7 +8,6 @@ menu:
|
|||
parent: "pipes"
|
||||
weight: 40
|
||||
weight: 40
|
||||
sections_weight: 40
|
||||
---
|
||||
|
||||
Any asset file can be processed using `resources.PostCSS` which takes for argument the resource object and a slice of options listed below.
|
||||
|
|
@ -22,11 +19,11 @@ The resource will be processed using the project's or theme's own `postcss.confi
|
|||
{{ $style := $css | resources.PostCSS }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Hugo Pipe's PostCSS requires the `postcss-cli` JavaScript package to be installed in the environment (`npm install -g postcss postcss-cli`) along with any PostCSS plugin(s) used (e.g., `npm install -g autoprefixer`).
|
||||
You must install the required Node.js packages to use the PostCSS feature. For example, to use the `autoprefixer` package, run these commands from the root of your project:
|
||||
|
||||
If you are using the Hugo Snap package, PostCSS and plugin(s) need to be installed locally within your Hugo site directory, e.g., `npm install postcss-cli` without the `-g` flag.
|
||||
{{% /note %}}
|
||||
```text
|
||||
npm install postcss postcss-cli autoprefixer
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
|
|
|
|||
|
|
@ -38,6 +38,9 @@ precision [int]
|
|||
enableSourceMap [bool]
|
||||
: When enabled, a source map will be generated.
|
||||
|
||||
sourceMapIncludeSources [bool]
|
||||
: When enabled, sources will be embedded in the generated source map. (Dart Sass only). {{< new-in "0.108.0" >}}
|
||||
|
||||
includePaths [string slice]
|
||||
: Additional SCSS/Sass include paths. Paths must be relative to the project directory.
|
||||
|
||||
|
|
|
|||
|
|
@ -62,18 +62,14 @@ doas pkg_add hugo
|
|||
|
||||
[OpenBSD]: https://www.openbsd.org/
|
||||
|
||||
{{% readfile file="/installation/common/04-docker.md" %}}
|
||||
|
||||
{{% readfile file="/installation/common/05-build-from-source.md" %}}
|
||||
|
||||
## Comparison
|
||||
|
||||
||Prebuilt binaries|Repository packages|Docker|Build from source
|
||||
:--|:--:|:--:|:--:|:--:
|
||||
Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|
|
||||
Easy to upgrade?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
|
||||
Easy to downgrade?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
|
||||
Automatic updates?|:x:|varies|:x: [^1]|:x:
|
||||
Latest version available?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
|
||||
|
||||
[^1]: Possible but requires advanced configuration.
|
||||
||Prebuilt binaries|Repository packages|Build from source
|
||||
:--|:--:|:--:|:--:
|
||||
Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
|
||||
Easy to upgrade?|:heavy_check_mark:|varies|:heavy_check_mark:
|
||||
Easy to downgrade?|:heavy_check_mark:|varies|:heavy_check_mark:
|
||||
Automatic updates?|:x:|varies|:x:
|
||||
Latest version available?|:heavy_check_mark:|varies|:heavy_check_mark:
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ Jan 2 15:04:05 2006 MST
|
|||
|
||||
Each of the following examples show the reference formatting string followed by the string Hugo will output in your HTML.
|
||||
|
||||
Note that the examples were rendered and tested in [CST][] and pull from a single example date you might have in your content's front matter:
|
||||
Note that the examples were rendered and tested in [CST] and pull from a single example date you might have in your content's front matter:
|
||||
|
||||
```yml
|
||||
date: 2017-03-03T14:15:59-06:00
|
||||
|
|
|
|||
|
|
@ -18,23 +18,31 @@ toc: true
|
|||
|
||||
<!-- begin data files -->
|
||||
|
||||
Hugo supports loading data from YAML, JSON, XML, and TOML files located in the `data` directory in the root of your Hugo project.
|
||||
Hugo supports loading data from YAML, JSON, XML, and TOML files located in the `data` directory at the root of your Hugo project.
|
||||
|
||||
{{< youtube FyPgSuwIMWQ >}}
|
||||
|
||||
## The Data Folder
|
||||
|
||||
The `data` folder is where you can store additional data for Hugo to use when generating your site. Data files aren't used to generate standalone pages; rather, they're meant to be supplemental to content files. This feature can extend the content in case your front matter fields grow out of control. Or perhaps you want to show a larger dataset in a template (see example below). In both cases, it's a good idea to outsource the data in their own files.
|
||||
The `data` folder should store additional data for Hugo to use when generating your site.
|
||||
|
||||
Data files are not for generating standalone pages. They should supplement content files by:
|
||||
|
||||
- extending the content when the front matter fields grow out of control, or
|
||||
- showing a larger dataset in a template (see the example below).
|
||||
|
||||
In both cases, it's a good idea to outsource the data in their (own) files.
|
||||
|
||||
These files must be YAML, JSON, XML, or TOML files (using the `.yml`, `.yaml`, `.json`, `.xml`, or `.toml` extension). The data will be accessible as a `map` in the `.Site.Data` variable.
|
||||
|
||||
If you wish to access the data using the `.Site.Data.filename` notation, the filename must begin with an underscore or a Unicode letter, followed by zero or more underscores, Unicode letters, or Unicode digits. eg:
|
||||
To access the data using the `site.Data.filename` notation, the filename must begin with an underscore or a Unicode letter, followed by zero or more underscores, Unicode letters, or Unicode digits. For example:
|
||||
|
||||
- `123.json` - Invalid
|
||||
- `x123.json` - Valid
|
||||
- `_123.json` - Valid
|
||||
|
||||
If you wish to access the data using the [`index`](/functions/index-function/) function, the filename is irrelevant. For example:
|
||||
To access the data using the [`index`](/functions/index-function/) function, the filename is irrelevant. For example:
|
||||
|
||||
Data file|Template code
|
||||
:--|:--
|
||||
`123.json`|`{{ index .Site.Data "123" }}`
|
||||
|
|
@ -44,11 +52,13 @@ Data file|Template code
|
|||
|
||||
## Data Files in Themes
|
||||
|
||||
Data Files can also be used in [Hugo themes][themes] but note that theme data files are merged with the project directory taking precedence (i.e., given two files with the same name and relative path, the data in the file in the root project `data` directory will override the data from the file in the `themes/<THEME>/data` directory *for keys that are duplicated*).
|
||||
Data Files can also be used in [Hugo themes][themes].
|
||||
|
||||
Therefore, theme authors should take care to not include data files that could be easily overwritten by a user who decides to [customize a theme][customize]. For theme-specific data items that shouldn't be overridden, it can be wise to prefix the folder structure with a namespace; e.g. `mytheme/data/<THEME>/somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag.
|
||||
However, note that the theme data files are merged with the project directory taking precedence. That is, Given two files with the same name and relative path, the data in the file in the root project `data` directory will override the data from the file in the `themes/<THEME>/data` directory *for keys that are duplicated*).
|
||||
|
||||
The keys in the map created with data templates from data files will be a dot-chained set of `path`, `filename`, and `key` in file (if applicable).
|
||||
Therefore, theme authors should be careful not to include data files that could be easily overwritten by a user who decides to [customize a theme][customize]. For theme-specific data items that shouldn't be overridden, it can be wise to prefix the folder structure with a namespace; e.g. `mytheme/data/<THEME>/somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag.
|
||||
|
||||
The keys in the map created with data templates from data files will be a dot-chained set of `path`, `filename`, and `key` in the file (if applicable).
|
||||
|
||||
This is best explained with an example:
|
||||
|
||||
|
|
@ -213,7 +223,7 @@ If you don't like caching at all, you can fully disable caching with the command
|
|||
|
||||
### Authentication When Using REST URLs
|
||||
|
||||
Currently, you can only use those authentication methods that can be put into an URL. [OAuth][] and other authentication methods are not implemented.
|
||||
Currently, you can only use those authentication methods that can be put into an URL. [OAuth] and other authentication methods are not implemented.
|
||||
|
||||
## Load Local files
|
||||
|
||||
|
|
@ -227,7 +237,7 @@ The local CSV files to be loaded using `getCSV` must be located **outside** the
|
|||
|
||||
## LiveReload with Data Files
|
||||
|
||||
There is no chance to trigger a [LiveReload][] when the content of a URL changes. However, when a *local* file changes (i.e., `data/*` and `themes/<THEME>/data/*`), a LiveReload will be triggered. Symlinks are not supported. Note too that because downloading of data takes a while, Hugo stops processing your Markdown files until the data download has completed.
|
||||
There is no chance to trigger a [LiveReload] when the content of a URL changes. However, when a *local* file changes (i.e., `data/*` and `themes/<THEME>/data/*`), a LiveReload will be triggered. Symlinks are not supported. Note too that because downloading data takes a while, Hugo stops processing your Markdown files until the data download has been completed.
|
||||
|
||||
{{% warning "URL Data and LiveReload" %}}
|
||||
If you change any local file and the LiveReload is triggered, Hugo will read the data-driven (URL) content from the cache. If you have disabled the cache (i.e., by running the server with `hugo server --ignoreCache`), Hugo will re-download the content every time LiveReload triggers. This can create *huge* traffic. You may reach API limits quickly.
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ See the homepage template below or [Content Organization][contentorg] for more i
|
|||
|
||||
## Example Homepage Template
|
||||
|
||||
The following is an example of a homepage template that uses [partial][partials], [base][] templates, and a content file at `content/_index.md` to populate the `{{.Title}}` and `{{.Content}}` [page variables][pagevars].
|
||||
The following is an example of a homepage template that uses [partial][partials], [base] templates, and a content file at `content/_index.md` to populate the `{{.Title}}` and `{{.Content}}` [page variables][pagevars].
|
||||
|
||||
{{< code file="layouts/index.html" download="index.html" >}}
|
||||
{{ define "main" }}
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ While the following internal templates are called similar to partials, they do *
|
|||
|
||||
Hugo ships with internal templates supporting Google Analytics, both [Google Analytics 4][GA4] (GA4) and Universal Analytics.
|
||||
|
||||
**Note:** Universal Analytics are deprecated. For details, see [Universal Analytics will be going away][].
|
||||
**Note:** Universal Analytics are deprecated. For details, see [Universal Analytics will be going away].
|
||||
|
||||
[GA4]: https://support.google.com/analytics/answer/10089681
|
||||
[Universal Analytics will be going away]: https://support.google.com/analytics/answer/11583528
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@ The following example calls the `add` function with inputs of `1` and `2`:
|
|||
|
||||
#### Methods and Fields are Accessed via dot Notation
|
||||
|
||||
Accessing the Page Parameter `bar` defined in a piece of content's [front matter][].
|
||||
Accessing the Page Parameter `bar` defined in a piece of content's [front matter].
|
||||
|
||||
```go-html-template
|
||||
{{ .Params.bar }}
|
||||
|
|
@ -519,11 +519,11 @@ The templating engine will strip the content within the HTML comment, but will f
|
|||
|
||||
## Hugo Parameters
|
||||
|
||||
Hugo provides the option of passing values to your template layer through your [site configuration][config] (i.e. for site-wide values) or through the metadata of each specific piece of content (i.e. the [front matter][]). You can define any values of any type and use them however you want in your templates, as long as the values are supported by the [front matter format]({{< ref "front-matter.md#front-matter-formats" >}}).
|
||||
Hugo provides the option of passing values to your template layer through your [site configuration][config] (i.e. for site-wide values) or through the metadata of each specific piece of content (i.e. the [front matter]). You can define any values of any type and use them however you want in your templates, as long as the values are supported by the [front matter format]({{< ref "front-matter.md#front-matter-formats" >}}).
|
||||
|
||||
## Use Content (`Page`) Parameters
|
||||
|
||||
You can provide variables to be used by templates in individual content's [front matter][].
|
||||
You can provide variables to be used by templates in individual content's [front matter].
|
||||
|
||||
An example of this is used in the Hugo docs. Most of the pages benefit from having the table of contents provided, but sometimes the table of contents doesn't make a lot of sense. We've defined a `notoc` variable in our front matter that will prevent a table of contents from rendering when specifically set to `true`.
|
||||
|
||||
|
|
|
|||
|
|
@ -199,7 +199,7 @@ This list template has been modified slightly from a template originally used in
|
|||
|
||||
## Order Content
|
||||
|
||||
Hugo lists render the content based on metadata you provide in [front matter][]. In addition to sane defaults, Hugo also ships with multiple methods to make quick work of ordering content inside list templates:
|
||||
Hugo lists render the content based on metadata you provide in [front matter]. In addition to sane defaults, Hugo also ships with multiple methods to make quick work of ordering content inside list templates:
|
||||
|
||||
### Default: Weight > Date > LinkTitle > FilePath
|
||||
|
||||
|
|
@ -499,7 +499,7 @@ In the above example, you may want `{{.Title}}` to point the `title` field you h
|
|||
|
||||
### By Page Parameter in Date Format
|
||||
|
||||
The following template takes grouping by `date` a step further and uses Go's layout string. See the [`Format` function][] for more examples of how to use Go's layout string to format dates in Hugo.
|
||||
The following template takes grouping by `date` a step further and uses Go's layout string. See the [`Format` function] for more examples of how to use Go's layout string to format dates in Hugo.
|
||||
|
||||
{{< code file="layouts/partials/by-page-param-as-date.html" >}}
|
||||
<!-- Groups content by month according to the "param_key" field in front matter -->
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ This page describes how to properly configure your site with the media types and
|
|||
|
||||
## Media Types
|
||||
|
||||
A [media type][] (also known as _MIME type_ and _content type_) is a two-part identifier for file formats and format contents transmitted on the internet.
|
||||
A [media type] (also known as _MIME type_ and _content type_) is a two-part identifier for file formats and format contents transmitted on the internet.
|
||||
|
||||
This is the full set of built-in media types in Hugo:
|
||||
|
||||
|
|
@ -228,7 +228,7 @@ A new output format needs a corresponding template in order to render anything u
|
|||
The key distinction for Hugo versions 0.20 and newer is that Hugo looks at an output format's `Name` and MediaType's `Suffixes` when choosing the template used to render a given `Page`.
|
||||
{{% /note %}}
|
||||
|
||||
The following table shows examples of different output formats, the suffix used, and Hugo's respective template [lookup order][]. All the examples in the table can:
|
||||
The following table shows examples of different output formats, the suffix used, and Hugo's respective template [lookup order]. All the examples in the table can:
|
||||
|
||||
* Use a [base template][base].
|
||||
* Include [partial templates][partials]
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ aliases: [/extras/pagination,/doc/pagination/]
|
|||
toc: true
|
||||
---
|
||||
|
||||
The real power of Hugo pagination shines when combined with the [`where` function][where] and its SQL-like operators: [`first`][], [`last`][], and [`after`][]. You can even [order the content][lists] the way you've become used to with Hugo.
|
||||
The real power of Hugo pagination shines when combined with the [`where` function][where] and its SQL-like operators: [`first`], [`last`], and [`after`]. You can even [order the content][lists] the way you've become used to with Hugo.
|
||||
|
||||
## Configure Pagination
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ toc: true
|
|||
|
||||
## Partial Template Lookup Order
|
||||
|
||||
Partial templates---like [single page templates][singletemps] and [list page templates][listtemps]---have a specific [lookup order][]. However, partials are simpler in that Hugo will only check in two places:
|
||||
Partial templates---like [single page templates][singletemps] and [list page templates][listtemps]---have a specific [lookup order]. However, partials are simpler in that Hugo will only check in two places:
|
||||
|
||||
1. `layouts/partials/*<PARTIALNAME>.html`
|
||||
2. `themes/<THEME>/layouts/partials/*<PARTIALNAME>.html`
|
||||
|
|
|
|||
|
|
@ -84,7 +84,16 @@ PlainText
|
|||
: The plain variant of the above.
|
||||
|
||||
Attributes (map)
|
||||
: A map of attributes (e.g. `id`, `class`)
|
||||
: A map of attributes (e.g. `id`, `class`). Note that this will currently always be empty for links.
|
||||
|
||||
The `render-image` templates will also receive:
|
||||
|
||||
IsBlock {{< new-in "0.108.0" >}}
|
||||
: Returns true if this is a standalone image and the config option [markup.goldmark.parser.wrapStandAloneImageWithinParagraph](/getting-started/configuration-markup/#goldmark) is disabled.
|
||||
|
||||
Ordinal {{< new-in "0.108.0" >}}
|
||||
: Zero-based ordinal for all the images in the current document.
|
||||
|
||||
|
||||
### Link with title Markdown example
|
||||
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ aliases: []
|
|||
toc: true
|
||||
---
|
||||
|
||||
Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside your content. In this sense, you can think of shortcodes as the intermediary between [page and list templates][templates] and [basic content files][].
|
||||
Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside your content. In this sense, you can think of shortcodes as the intermediary between [page and list templates][templates] and [basic content files].
|
||||
|
||||
{{% note %}}
|
||||
Hugo also ships with built-in shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).)
|
||||
|
|
@ -32,7 +32,7 @@ Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, H
|
|||
|
||||
### File Location
|
||||
|
||||
To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization][]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}` depending on the type of parameters you choose.
|
||||
To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}` depending on the type of parameters you choose.
|
||||
|
||||
You can organize your shortcodes in subfolders, e.g. in `layouts/shortcodes/boxes`. These shortcodes would then be accessible with their relative path, e.g:
|
||||
|
||||
|
|
@ -44,7 +44,7 @@ Note the forward slash.
|
|||
|
||||
### Shortcode Template Lookup Order
|
||||
|
||||
Shortcode templates have a simple [lookup order][]:
|
||||
Shortcode templates have a simple [lookup order]:
|
||||
|
||||
1. `/layouts/shortcodes/<SHORTCODE>.html`
|
||||
2. `/themes/<THEME>/layouts/shortcodes/<SHORTCODE>.html`
|
||||
|
|
@ -279,7 +279,7 @@ Would be rendered as:
|
|||
|
||||
### Paired Example: `highlight`
|
||||
|
||||
The following is taken from `highlight`, which is a [built-in shortcode][] that ships with Hugo.
|
||||
The following is taken from `highlight`, which is a [built-in shortcode] that ships with Hugo.
|
||||
|
||||
{{< code file="highlight-example.md" >}}
|
||||
{{</* highlight html */>}}
|
||||
|
|
|
|||
|
|
@ -24,11 +24,11 @@ See [Template Lookup](/templates/lookup-order/).
|
|||
|
||||
## Example Single Page Templates
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
### `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.
|
||||
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/posts/single.html" download="single.html" >}}
|
||||
{{ define "main" }}
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ Hugo provides multiple ways to use taxonomies throughout your project templates:
|
|||
|
||||
* Order the way content associated with a taxonomy term is displayed in a [taxonomy list template](#taxonomy-list-templates)
|
||||
* Order the way the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-templates)
|
||||
* List a single content's taxonomy terms within a [single page template][]
|
||||
* List a single content's taxonomy terms within a [single page template]
|
||||
|
||||
## Taxonomy List Templates
|
||||
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ This will print out a list of all the variables scoped to the current context
|
|||
{{ printf "%#v" . }}
|
||||
```
|
||||
|
||||
When developing a [homepage][], what does one of the pages you're looping through look like?
|
||||
When developing a [homepage], what does one of the pages you're looping through look like?
|
||||
|
||||
```go-html-template
|
||||
{{ range .Pages }}
|
||||
|
|
|
|||
|
|
@ -23,10 +23,10 @@ Know of a Hugo-related starter kit that isn't mentioned here? [Please add it to
|
|||
The following starter kits are developed by active members of the Hugo community. If you find yourself having issues with any of the projects, it's best to file an issue directly with the project's maintainer(s).
|
||||
{{% /note %}}
|
||||
|
||||
* [Wowchemy][]. Wowchemy is the 5,500+ star open source Hugo starter kit and website builder trusted by 750,000+ sites since 2016. Create _any_ kind of site with [50+ templates, widgets, and extensions](https://wowchemy.com/). Translated into 35+ languages and backed by a large, active community of 150+ contributors.
|
||||
* [Wowchemy]. Wowchemy is the 5,500+ star open source Hugo starter kit and website builder trusted by 750,000+ sites since 2016. Create _any_ kind of site with [50+ templates, widgets, and extensions](https://wowchemy.com/). Translated into 35+ languages and backed by a large, active community of 150+ contributors.
|
||||
* [Hugo Wrapper][hugow]. Hugo Wrapper is a POSIX-style shell script which acts as a wrapper to download and run Hugo binary for your platform. It can be executed in variety of [Operating Systems][hugow-test] and [Command Shells][hugow-test].
|
||||
* [GOHUGO AMP][]. GoHugo AMP is a starter theme that aims to make it easy to adopt [Google's AMP Project][amp]. The starter kit comes with 40+ shortcodes and partials plus automatic structured data. The project also includes a [separate site with extensive documentation][gohugodocs].
|
||||
* [Hyas][]. Hyas is a Hugo starter helping you build modern websites that are secure, fast, and SEO-ready — by default. It is Netlify-ready (functions, redirects, headers) and comes with [documentation](https://gethyas.com/) to easily make it your own.
|
||||
* [GOHUGO AMP]. GoHugo AMP is a starter theme that aims to make it easy to adopt [Google's AMP Project][amp]. The starter kit comes with 40+ shortcodes and partials plus automatic structured data. The project also includes a [separate site with extensive documentation][gohugodocs].
|
||||
* [Hyas]. Hyas is a Hugo starter helping you build modern websites that are secure, fast, and SEO-ready — by default. It is Netlify-ready (functions, redirects, headers) and comes with [documentation](https://gethyas.com/) to easily make it your own.
|
||||
|
||||
[Wowchemy]: https://github.com/wowchemy/wowchemy-hugo-modules
|
||||
[addkit]: https://github.com/gohugoio/hugo/edit/master/docs/content/en/tools/starter-kits.md
|
||||
|
|
|
|||
|
|
@ -54,7 +54,7 @@ See [`.Scratch`](/functions/scratch/) for page-scoped, writable variables.
|
|||
: the date on which the content is scheduled to expire; `.ExpiryDate` pulls from the `expirydate` field in a content's front matter. See also `.PublishDate`, `.Date`, and `.Lastmod`.
|
||||
|
||||
.File
|
||||
: filesystem-related data for this content file. See also [File Variables][].
|
||||
: filesystem-related data for this content file. See also [File Variables].
|
||||
|
||||
.FuzzyWordCount
|
||||
: the approximate number of words in the content.
|
||||
|
|
|
|||
|
|
@ -29,9 +29,6 @@ All the methods below, e.g. `.Site.RegularPages` can also be reached via the glo
|
|||
.Site.AllPages
|
||||
: array of all pages, regardless of their translation.
|
||||
|
||||
.Site.Author
|
||||
: a map of the authors as defined in the site configuration.
|
||||
|
||||
.Site.BaseURL
|
||||
: the base URL for the site as defined in the site configuration.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,75 +1,131 @@
|
|||
---
|
||||
title: Taxonomy Variables
|
||||
linktitle:
|
||||
description: Taxonomy pages are of type `Page` and have all page-, site-, and list-level variables available to them. However, taxonomy terms templates have additional variables available to their templates.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
description: Hugo's taxonomy system exposes variables to taxonomy and term templates.
|
||||
categories: [variables and params]
|
||||
keywords: [taxonomies,terms]
|
||||
draft: false
|
||||
keywords: [taxonomy,term]
|
||||
menu:
|
||||
docs:
|
||||
parent: "variables"
|
||||
weight: 30
|
||||
weight: 30
|
||||
sections_weight: 30
|
||||
aliases: []
|
||||
toc: true
|
||||
weight: 30
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Taxonomy Terms Page Variables
|
||||
## Taxonomy templates
|
||||
|
||||
[Taxonomy terms pages][taxonomytemplates] are of the type `Page` and have the following additional variables.
|
||||
Pages rendered by taxonomy templates have `.Kind` set to `taxonomy` and `.Type` set to the taxonomy name.
|
||||
|
||||
For example, the following fields would be available in `layouts/_defaults/terms.html`, depending on how you organize your [taxonomy templates][taxonomytemplates]:
|
||||
In taxonomy templates you may access `.Site`, `.Page`. `.Section`, and `.File` variables, as well as the following _taxonomy_ variables:
|
||||
|
||||
.Data.Singular
|
||||
: The singular name of the taxonomy (e.g., `tags => tag`)
|
||||
: The singular name of the taxonomy (e.g., `tags => tag`).
|
||||
|
||||
.Data.Plural
|
||||
: The plural name of the taxonomy (e.g., `tags => tags`)
|
||||
: The plural name of the taxonomy (e.g., `tags => tags`).
|
||||
|
||||
.Data.Pages
|
||||
: The list of pages in the taxonomy
|
||||
: The collection of term pages related to this taxonomy. Aliased by `.Pages`.
|
||||
|
||||
.Data.Terms
|
||||
: The taxonomy itself
|
||||
: A map of terms and weighted pages related to this taxonomy.
|
||||
|
||||
.Data.Terms.Alphabetical
|
||||
: The taxonomy terms alphabetized
|
||||
: A map of terms and weighted pages related to this taxonomy, sorted alphabetically in ascending order. Reverse the sort order with`.Data.Terms.Alphabetical.Reverse`.
|
||||
|
||||
.Data.Terms.ByCount
|
||||
: The Terms ordered by popularity
|
||||
: A map of terms and weighted pages related to this taxonomy, sorted by count in ascending order. Reverse the sort order with`.Data.Terms.ByCount.Reverse`.
|
||||
|
||||
Note that `.Data.Terms.Alphabetical` and `.Data.Terms.ByCount` can also be reversed:
|
||||
## Term templates
|
||||
|
||||
* `.Data.Terms.Alphabetical.Reverse`
|
||||
* `.Data.Terms.ByCount.Reverse`
|
||||
Pages rendered by term templates have `.Kind` set to `term` and `.Type` set to the taxonomy name.
|
||||
|
||||
## Use `.Site.Taxonomies` Outside of Taxonomy Templates
|
||||
In term templates you may access `.Site`, `.Page`. `.Section`, and `.File` variables, as well as the following _term_ variables:
|
||||
|
||||
The `.Site.Taxonomies` variable holds all the taxonomies defined site-wide. `.Site.Taxonomies` is a map of the taxonomy name to a list of its values (e.g., `"tags" -> ["tag1", "tag2", "tag3"]`). Each value, though, is not a string but rather a *Taxonomy variable*.
|
||||
.Data.Singular
|
||||
: The singular name of the taxonomy (e.g., `tags => tag`).
|
||||
|
||||
## The `.Taxonomy` Variable
|
||||
.Data.Plural
|
||||
: The plural name of the taxonomy (e.g., `tags => tags`).
|
||||
|
||||
The `.Taxonomy` variable, available, for example, as `.Site.Taxonomies.tags`, contains the list of tags (values) and, for each tag, their corresponding content pages.
|
||||
.Data.Pages
|
||||
: The collection of content pages related to this taxonomy. Aliased by `.Pages`.
|
||||
|
||||
### Example Usage of `.Site.Taxonomies`
|
||||
.Data.Term
|
||||
: The term itself (e.g., `tag-one`).
|
||||
|
||||
The following [partial template][partials] will list all your site's taxonomies, each of their keys, and all the content assigned to each of the keys. For more examples of how to order and render your taxonomies, see [Taxonomy Templates][taxonomytemplates].
|
||||
## Access taxonomy data from any template
|
||||
|
||||
{{< code file="all-taxonomies-keys-and-pages.html" download="all-taxonomies-keys-and-pages.html" >}}
|
||||
<section>
|
||||
Access the entire taxonomy data structure from any template with `site.Taxonomies`. This returns a map of taxonomies, terms, and a collection of weighted content pages related to each term. For example:
|
||||
|
||||
```json
|
||||
{
|
||||
"categories": {
|
||||
"news": [
|
||||
{
|
||||
"Weight": 0,
|
||||
"Page": {
|
||||
"Title": "Post 1",
|
||||
"Date": "2022-12-18T15:13:35-08:00"
|
||||
...
|
||||
}
|
||||
},
|
||||
{
|
||||
"Weight": 0,
|
||||
"Page": {
|
||||
"Title": "Post 2",
|
||||
"Date": "2022-12-18T15:13:46-08:00",
|
||||
...
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"tags": {
|
||||
"international": [
|
||||
{
|
||||
"Weight": 0,
|
||||
"Page": {
|
||||
"Title": "Post 1",
|
||||
"Date": "2021-01-01T00:00:00Z"
|
||||
...
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Access a subset of the taxonomy data structure by chaining one or more identifiers, or by using the [`index`] function with one or more keys. For example, to access the collection of weighted content pages related to the news category, use either of the following:
|
||||
|
||||
[`index`]: /functions/index-function/
|
||||
|
||||
```go-html-template
|
||||
{{ $pages := site.Taxonomies.categories.news }}
|
||||
{{ $pages := index site.Taxonomies "categories" "news" }}
|
||||
```
|
||||
|
||||
For example, to render the entire taxonomy data structure as a nested unordered list:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range $taxonomyname, $taxonomy := .Site.Taxonomies }}
|
||||
<li><a href="{{ "/" | relLangURL}}{{ $taxonomyname | urlize }}">{{ $taxonomyname }}</a>
|
||||
{{ range $taxonomy, $terms := site.Taxonomies }}
|
||||
<li>
|
||||
{{ with site.GetPage $taxonomy }}
|
||||
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
|
||||
{{ end }}
|
||||
<ul>
|
||||
{{ range $key, $value := $taxonomy }}
|
||||
<li> {{ $key }} </li>
|
||||
{{ range $term, $weightedPages := $terms }}
|
||||
<li>
|
||||
{{ with site.GetPage (path.Join $taxonomy $term) }}
|
||||
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
|
||||
{{ end }}
|
||||
</li>
|
||||
<ul>
|
||||
{{ range $value.Pages }}
|
||||
<li><a href="{{ .Permalink}}"> {{ .LinkTitle }} </a> </li>
|
||||
{{ range $weightedPages }}
|
||||
<li>
|
||||
<a href="{{ .RelPermalink}}"> {{ .LinkTitle }}</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
|
|
@ -77,8 +133,8 @@ The following [partial template][partials] will list all your site's taxonomies,
|
|||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
</section>
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
[partials]: /templates/partials/
|
||||
[taxonomytemplates]: /templates/taxonomy-templates/
|
||||
See [Taxonomy Templates] for more examples.
|
||||
|
||||
[Taxonomy Templates]: /templates/taxonomy-templates/
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ 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 `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.
|
||||
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 `posts` base template:
|
||||
|
||||
|
|
|
|||
|
|
@ -1572,7 +1572,8 @@
|
|||
"attribute": {
|
||||
"title": true,
|
||||
"block": false
|
||||
}
|
||||
},
|
||||
"wrapStandAloneImageWithinParagraph": true
|
||||
},
|
||||
"extensions": {
|
||||
"typographer": true,
|
||||
|
|
@ -1722,7 +1723,8 @@
|
|||
},
|
||||
"funcs": {
|
||||
"getenv": [
|
||||
"^HUGO_"
|
||||
"^HUGO_",
|
||||
"^CI$"
|
||||
]
|
||||
},
|
||||
"http": {
|
||||
|
|
@ -3632,7 +3634,7 @@
|
|||
"Aliases": null,
|
||||
"Examples": [
|
||||
[
|
||||
"{{- $m := newScratch -}}\n{{- $m.Set \"Hugo\" \"Rocks!\" -}}\n{{- $m.Values | debug.Dump | safeHTML -}}",
|
||||
"{{ $m := newScratch }}\n{{ $m.Set \"Hugo\" \"Rocks!\" }}\n{{ $m.Values | debug.Dump | safeHTML }}",
|
||||
"map[string]interface {}{\n \"Hugo\": \"Rocks!\",\n}"
|
||||
]
|
||||
]
|
||||
|
|
|
|||
2
go.mod
2
go.mod
|
|
@ -2,4 +2,4 @@ module github.com/gohugoio/hugoDocs
|
|||
|
||||
go 1.16
|
||||
|
||||
require github.com/gohugoio/gohugoioTheme v0.0.0-20221206093948-1408550ab675 // indirect
|
||||
require github.com/gohugoio/gohugoioTheme v0.0.0-20221217122332-1c1752ad8f14 // indirect
|
||||
|
|
|
|||
2
go.sum
2
go.sum
|
|
@ -47,3 +47,5 @@ github.com/gohugoio/gohugoioTheme v0.0.0-20221124154621-1451a01f406b h1:TRrIisSY
|
|||
github.com/gohugoio/gohugoioTheme v0.0.0-20221124154621-1451a01f406b/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs=
|
||||
github.com/gohugoio/gohugoioTheme v0.0.0-20221206093948-1408550ab675 h1:wjpYa1cTELeceWndBDV7IG2vRxRWICBBO79HObOfTtk=
|
||||
github.com/gohugoio/gohugoioTheme v0.0.0-20221206093948-1408550ab675/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs=
|
||||
github.com/gohugoio/gohugoioTheme v0.0.0-20221217122332-1c1752ad8f14 h1:K6tPFpi7W0zb89QIf+lNdgdTXfDFemU6NKk46MlX9lQ=
|
||||
github.com/gohugoio/gohugoioTheme v0.0.0-20221217122332-1c1752ad8f14/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs=
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ publish = "public"
|
|||
command = "hugo --gc --minify"
|
||||
|
||||
[context.production.environment]
|
||||
HUGO_VERSION = "0.107.0"
|
||||
HUGO_VERSION = "0.108.0"
|
||||
HUGO_ENV = "production"
|
||||
HUGO_ENABLEGITINFO = "true"
|
||||
|
||||
|
|
@ -11,20 +11,20 @@ HUGO_ENABLEGITINFO = "true"
|
|||
command = "hugo --gc --minify --enableGitInfo"
|
||||
|
||||
[context.split1.environment]
|
||||
HUGO_VERSION = "0.107.0"
|
||||
HUGO_VERSION = "0.108.0"
|
||||
HUGO_ENV = "production"
|
||||
|
||||
[context.deploy-preview]
|
||||
command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL"
|
||||
|
||||
[context.deploy-preview.environment]
|
||||
HUGO_VERSION = "0.107.0"
|
||||
HUGO_VERSION = "0.108.0"
|
||||
|
||||
[context.branch-deploy]
|
||||
command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"
|
||||
|
||||
[context.branch-deploy.environment]
|
||||
HUGO_VERSION = "0.107.0"
|
||||
HUGO_VERSION = "0.108.0"
|
||||
|
||||
[context.next.environment]
|
||||
HUGO_ENABLEGITINFO = "true"
|
||||
|
|
|
|||
Loading…
Reference in a new issue