blogs/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2026-08-25 15:58:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into master

Browse Source
This commit is contained in:
Ryan Watters
2017-03-09 20:04:15 -06:00
committed by GitHub
parent 4e1ad212fb 8381df3b37
commit 68d58c29fa
443 changed files with 1069 additions and 1225 deletions
Download Patch File Download Diff File Expand all files Collapse all files
config.toml
+9 -14
View File
@@ -16,6 +16,8 @@ disablePathToLower = false
disableRSS = false
# Set to false if you want a sitemap.xml created at the site root
disableSitemap = false
# Allows use of emoji shorthand directly in content
enableEmoji = true
# Set the unicode character used for the "return" link in page footnotes.
footnotereturnlinkcontents = "↩"
# Create an array of files you don't want hugo to build
@@ -61,11 +63,7 @@ watch = true
# Add GA Tracking Code Here. This leverages a built-in (ie, "internal") partial from HUGO: https://gohugo.io/extras/analytics#configuring-google-analytics
googleanalyticstrackingcode = ""
## Critical Render Path. If true, site style will be embedded in a <style> tag in each html <head> as part of Gulp Build. False puts a typical <link> to the stylesheet in <head>>
usecrp = false
## Include jQuery 2.2.4 in your site head. (see /static/assets/js)
includejq = false
## Date the Site is Published, use YYYY-MM-DD
sitepublishdate = ""
usecrp = true
## Twitter handle without the "@"
twitterhandle = "GoHugoIO"
## Facebook URL
@@ -73,19 +71,15 @@ watch = true
## Default Image for Social Sharing. This image should live at static/images/
defaultsocialimage = "hugodefaultsocial.png"
## Setting this to true will add a "noindex" to *every* page on the site
removefromexternalsearch = true
## This is used when the BaseURL does not need to modified (eg, in share links)
siteaddress = "https://hugodocsconcept.netlify.com"
removefromexternalsearch = false
## This is used when the BaseURL does not need to modified (eg, in share links or in prerender, prefetch, etc to control for relativeURLs setting)
siteaddress = "https://hugodocs.info"
## Gh repo for site footer (include trailing slash)
ghrepo = "https://github.com/spf13/hugo/"
## GitHub Docs Repository Base URL (include trailing slash)
### https://github.com/spf13/hugo/tree/master/docs
### Edit content repo (set to automatically enter "edit" mode => good for "improve this page" links)
ghdocsrepo = "https://github.com/rdwatters/hugo-docs-concept/edit/master/"
### Edit content repo
## Github Wiki for Documentation
ghdocswiki = ""
## Github Wiki for Development
ghdevwiki = ""
## Gitter URL
gitter = "https://gitter.im/spf13/hugo"
## Discuss Forum URL
@@ -93,6 +87,7 @@ watch = true
gtmid = ""
# Set to true to include a CDN call to FontAwesome (not that Hugo docs currently hosts its own FA (see pipeline/scss/_variables.scss))
usefontawesome = false
# MARKDOWN
## Configuration for BlackFriday markdown parser: https://github.com/russross/blackfriday
[blackfriday]
@@ -103,4 +98,4 @@ watch = true
[taxonomies]
tag = "tags"
category = "categories"
category = ""
content/about/benefits.md
+3 -3
View File
@@ -12,15 +12,15 @@ aliases: []
toc: false
---
The purpose of website generators is to render content into HTML files. Most are "dynamic site generators." That means the HTTP server---i.e., the program that files to the browser to be viewed---runs the generator to create a new HTML file every time an end user requests a page.
The purpose of website generators is to render content into HTML files. Most are "dynamic site generators." That means the HTTP server---i.e., the program that sends files to the browser to be viewed---runs the generator to create a new HTML file every time an end user requests a page.
Creating the page dynamically requires the HTTP server to have enough memory and CPU to effectively run the generator nonstop. If not, your end user will wait in a queue for the page to be generated.
Over time, dynamic site generators were programmed to cache their HTML files to prevent unnecessary delays in delivering pages to end users. A cached page is a static version of a web page that is temporarily stored on a server for. Sending a cached copy of a web page is faster than generating a new page at the time of request because the majority of the work is already done.
Over time, dynamic site generators were programmed to cache their HTML files to prevent unnecessary delays in delivering pages to end users. A cached page is a static version of a web page that is temporarily stored on a server. Sending a cached copy of a web page is faster than generating a new page at the time of request because the majority of the work is already done.
Hugo is in a family of generators that take caching a step further. All HTML files are rendered on your computer. You can review the files locally before copying them to the computer hosting the HTTP server. Since the HTML files aren't generated dynamically, we say that Hugo is a *static site generator*.
Not running a website generator on your HTTP server has many benefits. The most noticeable is performance. HTTP servers are *very* good at sending files---so good, in fact, that you can effectively serve the same number of pages with a fraction of the memory and CPU needed for a dynamic site.
Not running a website generator on your HTTP server has many benefits. The most noticeable is performance. HTTP servers are *very* good at sending files---so good, in fact, that you can effectively serve the same number of pages with a fraction of the memory and CPU needed for a ~~dynamic site~~.
## More on Static Site Generators
content/concept.md
+2 -2
View File
@@ -241,7 +241,7 @@ Themes section organization has only changed slightly in that the 6 content page
* Base templates
* Hugo Lists (introduces the lists concept [i.e. sections, taxonomies, etc]); this includes one of multiple forthcoming visualizations for Hugo architecture
* Rendering Hugo Lists (i.e., ordering, grouping, etc)
* Shortcodes and menus (templating), pagination, data, traversing local files, data-driven content, and data files have all moved out from "Extras" and into templating. *Note that there is only one stylesheet in the local example now* {{< emo ":wink:" >}}.
* Shortcodes and menus (templating), pagination, data, traversing local files, data-driven content, and data files have all moved out from "Extras" and into templating. *Note that there is only one stylesheet in the local example now*..
* **2017-02-26**. I am currently working on a new example for `readDir`.
### Taxonomies
@@ -376,7 +376,7 @@ Apache License - 60
* Template Lookup Order -15
* Base Templates And Blocks - 20
* Lists in Hugo - 22
* Rendering Lists in Hugo - 27
* Ordering and Grouping Hugo Lists - 27
* Homepage Template - 30
* Section Templates - 40
* Taxonomy Templates - 50
content/content-management/comments.md
+3 -1
View File
@@ -4,7 +4,7 @@ linktitle: Comments
description: Hugo ships with an internal Disqus template that requires negligible effort to implement, but Disqus isn't the only commenting system that will work with your new Hugo website.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
lastmod: 2017-03-09
tags: [sections,content,organization, fundamentals]
categories: [project organization]
weight: 140
@@ -52,6 +52,7 @@ There are a few alternatives to commenting on static sites for those who do not
* [Static Man](https://staticman.net/)
* [IntenseDebate](http://intensedebate.com/)
* [Livefyre](http://livefyre.com/)
* [Graph Comment][]
* [Muut](http://muut.com/)
* [多说](http://duoshuo.com/) ([Duoshuo](http://duoshuo.com/), popular in China)
* [isso](http://posativ.org/isso/) (Self-hosted, Python)
@@ -74,6 +75,7 @@ It is in early development but shows promise. If you have interest, please help
[disqussetup]: https://disqus.com/profile/signup/
[forum]: https://discuss.gohugo.io
[front matter]: /content-management/front-matter/
[Graph Comment]: https://graphcomment.com/
[kaijuissue]: https://github.com/spf13/kaiju/issues/new
[issotutorial]: https://stiobhart.net/2017-02-24-isso-comments/
[partials]: /templates/partials/
content/content-management/formats.md
+5 -4
View File
@@ -18,12 +18,12 @@ toc: true
Markdown is the native content format for Hugo and is rendered using the excellent [Blackfriday project][blackfriday], a blazingly fast parser written in Golang.
{{% note "Deeply Nested Lists" %}}
Before you begin writing your content in markdown, Blackfriday has a known issue [(#329)](https://github.com/russross/blackfriday/issues/329) with handling deeply nested lists. Luckily, there is an easy workaround. Use 4-spaces (i.e., <kbd>tab</kbd>) rather than 2-space indentations to delimit nesting of lists in your content.
Before you begin writing your content in markdown, Blackfriday has a known issue [(#329)](https://github.com/russross/blackfriday/issues/329) with handling deeply nested lists. Luckily, there is an easy workaround. Use 4-spaces (i.e., <kbd>tab</kbd>) rather than 2-space indentations.
{{% /note %}}
## Configuring Markdown Rendering
You can configure multiple aspects of Blackfriday. For more information, see [how to configure your Hugo projects][config]:
You can configure multiple aspects of Blackfriday as show in the following list. See the docs on [Configuration][config] for the full list of explicit directions you can give to Hugo when rendering your site.
{{< readfile file="content/readfiles/bfconfig.md" markdown="true" >}}
@@ -33,7 +33,7 @@ Hugo provides some convenient methods for extending markdown.
### Task Lists
Hugo supports GitHub-styled task lists (i.e., TODO lists) for the Blackfriday markdown renderer. If you do not want to use this feature, you can disable it in your configuration.
Hugo supports [GitHub-styled task lists (i.e., TODO lists)][gfmtasks] for the Blackfriday markdown renderer. If you do not want to use this feature, you can disable it in your configuration.
#### Example Task List Input
@@ -97,7 +97,7 @@ For example, for Asciidoc files, Hugo will try to call the `asciidoctor` or `asc
To use these formats, just use the standard extension and the front matter exactly as you would do with natively supported `.md` files.
{{% warning "Performance of External Helpers" %}}
Because additional format are external commands---with the exception of org mode---generation performance will rely heavily on the performance of the external tool used. As this feature is still in its infancy, feedback is especially welcome.
Because additional formats are external commands---with the exception of org mode---generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome.
{{% /warning %}}
[ascii]: http://asciidoc.org/
@@ -106,6 +106,7 @@ Because additional format are external commands---with the exception of org mode
[config]: /getting-started/configuration/
[developer tools]: /tools/
[fireball]: https://daringfireball.net/projects/markdown/
[gfmtasks]: https://guides.github.com/features/mastering-markdown/#syntax
[helperssource]: https://github.com/spf13/hugo/blob/77c60a3440806067109347d04eb5368b65ea0fe8/helpers/general.go#L65
[hl]: /tools/syntax-highlighting/
[hlsc]: /content-management/shortcodes/#highlight
content/content-management/front-matter.md
+34 -27
View File
@@ -10,20 +10,25 @@ tags: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"]
weight: 30
draft: false
aliases: [/content/front-matter/]
wip: true
toc: true
notesforauthors:
---
**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. Hugo supports a few different formats for front matter, each with their own identifying tokens.
**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.
## Supported Front Matter Formats
## Front Matter Formats
* TOML. identified by opening and closing `+++`.
* YAML. identified by opening and closing `---` *or* opening `---` and closing `...`
* JSON. a single JSON object which is surrounded by '`{`' and '`}`', each on their own line.
Hugo supports three formats for front matter, each with their own identifying tokens.
### TOML Front Matter Example
TOML
: identified by opening and closing `+++`.
YAML
: identified by opening and closing `---` *or* opening `---` and closing `...`
JSON
: a single JSON object surrounded by '`{`' and '`}`', each on their own line.
### TOML Example
```toml
+++
@@ -39,7 +44,7 @@ slug = "spf13-vim-3-0-release-and-new-website"
+++
```
### YAML Front Matter Example
### YAML Example
```yaml
---
@@ -55,7 +60,7 @@ slug: "spf13-vim-3-0-release-and-new-website"
---
```
### JSON Front Matter Example
### JSON Example
```json
{
@@ -71,7 +76,7 @@ slug: "spf13-vim-3-0-release-and-new-website"
}
```
## Variables
## Front Matter Variables
There are a few predefined variables that Hugo is aware of and utilizes.
@@ -105,7 +110,7 @@ categories above)
: If true, explicitly treat the content as CJKLanguage (`.Summary` and `.WordCount` can work properly in CJKLanguage)
`markup`
: **Experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown
: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown
`publishdate`
: If in the future, content will not be rendered unless `hugo` is called with `--buildFuture`
@@ -124,33 +129,33 @@ the multilingual feature.
: Used for sorting
{{% note "Hugo's Default URL Destinations" %}}
If neither `slug` nor `url` is present, and [permalinks are not configured otherwise](/content-management/urls/#permalinks), the filename will be used to create the URL for a page. See [Content Organization][contentorg] and [URL Management][urls].
If neither `slug` nor `url` is present, and [permalinks are not configured otherwise](/content-management/urls/#permalinks), the filename will be used to create the URL for a page. See [Content Organization](/content-management/organization) and [URL Management](/content-management/urls/).
{{% /note %}}
### User-Defined
The user can also create any variable they want. These will be placed into the `.Params` variable available to the templates.
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:
```yaml
include_toc: true
show_comments: false
```
These two user-defined fields can then 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.
{{% note %}}
Field names are always normalized to lowercase (e.g., `camelCase: true` is available as `.Params.camelcase`) for both Hugo's built-in *and* user-defined variables.
Field names are always normalized to lowercase; e.g., `camelCase: true` is available as `.Params.camelcase`.
{{% /note %}}
**Show example toml and yaml front matter**
## Ordering Through Front Matter
You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][] in list views. You can use `weight` for ordering of content and the convention of [`<TAXONOMY>_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][] to see how `weight` can be used to organize your content in list views.
## Overriding Global Blackfriday Configuration
It's possible to set some options for Markdown rendering in the page's front matter as an override to the site-wide configuration.
It's possible to set some options for Markdown rendering in a content's front matter as an override to the options set in your site `config`.
See [site configuration][config] for more information on setting up global Blackfriday options.
User-Define Parameter (`.Params`)
## Assigning `weight`
### Assigning `weight` for Ordering Content
### Assigning `weight` for Ordering Taxonomies
See [site configuration][config] for more information on Blackfriday configuration options.
## Front Matter Format Specs
@@ -163,6 +168,8 @@ User-Define Parameter (`.Params`)
[contentorg]: /content-management/organization/
[content type]: /content-management/types/
[JSON Spec]: /documents/ecma-404-json-spec.pdf "Specification for JSON, JavaScript Object Notation"
[ordering]: /templates/ordering-and-grouping/ "Hugo provides multiple ways to sort and order your content in list templates"
[taxweight]: /content-management/taxonomies/
[TOML Spec]: https://github.com/toml-lang/toml "Specification for TOML, Tom's Obvious Minimal Language"
[urls]: /content-management/urls/
[YAML Spec]: http://yaml.org/spec/ "Specification for YAML, YAML Ain't Markup Language"
content/content-management/menus.md
+10 -11
View File
@@ -5,13 +5,12 @@ description: Hugo's simple yet powerful menu system allows you to add content to
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [templating]
tags: [lists,sections,menus]
categories: [content management]
tags: [menus]
draft: false
weight: 120
aliases: [/extras/menus/]
toc: true
wip: true
---
Hugo's simple yet powerful menu system allows you to add content to menus with a high degree of control and a very low amount of effort on the part of content authors.
@@ -78,11 +77,11 @@ menu:
## Adding Non-content Entries to a Menu
You can also add entries to menus that aren’t attached to a piece of content. This takes place in the sitewide [config file](/overview/configuration/).
You can also add entries to menus that aren’t attached to a piece of content. This takes place in your Hugo project's [`config` file][config].
Here’s an example snippet pulled from a `config.toml`:
{{% code file="menu-in-config.toml" %}}
{{% code file="config.toml" %}}
```toml
[[menu.main]]
name = "about hugo"
@@ -98,9 +97,9 @@ Here’s an example snippet pulled from a `config.toml`:
```
{{% /code %}}
Here's the equivalent snippet pulled from a `config.yaml`:
Here's the equivalent snippet in a `config.yaml`:
{{% code file="menu-in-config.yml" %}}
{{% code file="config.yml" %}}
```yaml
---
menu:
@@ -119,18 +118,18 @@ menu:
{{% /code %}}
{{% note %}}
The URLs must be relative to the context root. If the `baseURL` is `http://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will overide the baseURL. If the `URL` is `http://subdomain.example.com/`, the output will be `http://subdomain.example.com`.
The URLs must be relative to the context root. If the `baseURL` is `http://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will overide the baseURL. If the value used for `URL` in the above example is `http://subdomain.example.com/`, the output will be `http://subdomain.example.com`.
{{% /note %}}
## Nesting
All nesting of content is done via the `parent` field.
The parent of an entry should be the identifier of another entry. Identifier should be unique (within a menu).
The parent of an entry should be the identifier of another entry. The identifier should be unique (within a menu).
The following order is used to determine an Identifier:
`.Name > .LinkTitle` > .Title`
`.Name > .LinkTitle > .Title`
This means that `.Title` will be used unless `.LinkTitle` is present, etc. In practice, `.Name` and `.Identifier` are only used to structure relationships and therefore never displayed.
@@ -138,7 +137,7 @@ In this example, the top level of the menu is defined in your [site `config` fil
## Rendering Menus
See [Menu Templates](/templates/menu-templates/) for information on how to render your site menus.
See [Menu Templates](/templates/menu-templates/) for information on how to render your site menus within your templates.
[config]: /getting-started/configuration/
[multilingual]: /content-management/multilingual/
content/content-management/multilingual.md
+24 -22
View File
@@ -11,10 +11,9 @@ weight: 150
draft: false
aliases: [/content/multilingual/,/content-management/multilingual/]
toc: true
wip: true
---
Hugo supports multiple languages side-by-side (added in `Hugo 0.17`). Define the available languages in a `Languages` section in your top-level `config.toml` (or equivalent).
Hugo supports multiple languages side-by-side (added in `Hugo 0.17`). You should Define the available languages in a `Languages` section in your site configuration.
## Configuring Multilingual Mode
@@ -62,6 +61,8 @@ Only the obvious non-global options can be overridden per language. Examples of
Taxonomies and [Blackfriday configuration][hugoconfig] can also be set per language:
{{% code file="bf-config.toml" %}}
```toml
[Taxonomies]
tag = "tags"
@@ -83,6 +84,7 @@ title = "Français"
[Languages.fr.Taxonomies]
plaque = "plaques"
```
{{% /code %}}
## Translating Your Content
@@ -93,21 +95,18 @@ Translated articles are identified by the name of the content file.
1. `/content/about.en.md`
2. `/content/about.fr.md`
You can also have:
You can also have the following, in which case the config variable `defaultContentLanguage` will be used to affect the default language `about.md`. This way, you can slowly start to translate your current content without having to rename everything:
1. `/content/about.md`
2. `/content/about.fr.md`
In which case the config variable `defaultContentLanguage` will be used to affect the default language `about.md`. This way, you can
slowly start to translate your current content without having to rename everything.
If left unspecified, the default value for `defaultContentLanguage` is `en`.
If left unspecified, the value for `defaultContentLanguage` defaults to `en`.
By having the same _base file name_, the content pieces are linked together as translated pieces.
By having the same *base filename*, the content pieces are linked together as translated pieces.
## Link to Translated Content
To create a list of links to translated content, use a template similar to this:
To create a list of links to translated content, use a template similar to the following:
{{% code file="layouts/partials/i18nlist.html" %}}
```html
@@ -124,13 +123,13 @@ To create a list of links to translated content, use a template similar to this:
```
{{% /code %}}
The above can be put in a `partial` (`./layouts/partials/`) and included in any template, be it for a [content page][contenttemplate] or the [homepage][]]. It will not print anything if there are no translations for a given page, or if there is---in the case of the homepage, section listing, etc.---a site with only one language.
The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, be it for a [single content page][contenttemplate] or the [homepage][]. It will not print anything if there are no translations for a given page, or if there are translations---in the case of the homepage, section listing, etc.---a site with only render one language.
The above also uses the [`i18n` function][i18func] described in the next section.
## Translation of Strings
Hugo uses [go-i18n](https://github.com/nicksnyder/go-i18n) to support string translations. [See the project's source repository](https://github.com/nicksnyder/go-i18n) to find tools that will help you manage your translation workflows.
Hugo uses [go-i18n][] to support string translations. [See the project's source repository][go-i18n-source] to find tools that will help you manage your translation workflows.
Translations are collected from the `themes/<THEME>/i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646][] with names such as `en-US.yaml`, `fr.yaml`, etc.
@@ -181,7 +180,7 @@ i18n|MISSING_TRANSLATION|en|wordCount
## Menus
You can define your menus for each language independently. The [creation of a menu](/content-management/menus/) works analogous to earlier versions of Hugo, except that they have to be defined in their language-specific block in the configuration file:
You can define your menus for each language independently. The [creation of a menu][menus] works analogous to earlier versions of Hugo, except that they have to be defined in their language-specific block in the configuration file:
```toml
defaultContentLanguage = "en"
@@ -206,7 +205,7 @@ name = "Startseite"
weight = 0
```
The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu of the current language. Pay attention to the generation of the menu links. `absLangURL` takes care that you link to the correct locale of your website. Otherwise, both menu entries would link to the English version because it's the default content language that resides in the root directory.
The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu of the current language. Pay attention to the generation of the menu links. `absLangURL` takes care that you link to the correct locale of your website. Otherwise, both menu entries would link to the English version as the default content language that resides in the root directory.
```html
<ul>
@@ -224,28 +223,31 @@ The rendering of the main navigation works as usual. `.Site.Menus` will just con
If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown.
While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`EnableMissingTranslationPlaceholders` configuration option][hugoconfig] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation.
While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`EnableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation.
{{% note %}}
Hugo will generate your website with these placeholders. It might not be suited for production environments.
Hugo will generate your website with these missing translation placeholders. It might not be suited for production environments.
{{% /note %}}
## Multilingual Themes support
To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must
To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria:
* Come from the built-in `.Permalink` or `.URL`
* Be constructed with
* The [`relLangURL` template function][rellangurl] or the [`absLangURL` template function][abslangurl] template functions **OR**
* Prefixed with `{{.LanguagePrefix }}`
* The [`relLangURL` template function][rellangurl] or the [`absLangURL` template function][abslangurl] **OR**
* Prefixed with `{{ .LanguagePrefix }}`
If there is more than one language defined, the`LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string and is therefore harmless for single-language Hugo websites.
If there is more than one language defined, the `LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string and is therefore harmless for single-language Hugo websites.
[abslangurl]: /functions/abslangurl
[config]: /getting-started/configuration/
[contenttemplate]: /templates/single-page-template/
[go-i18n-source]: https://github.com/nicksnyder/go-i18n
[go-i18n]: https://github.com/nicksnyder/go-i18n
[homepage]: /templates/homepage/
[hugoconfig]: /getting-started/configuration/
[i18func]: /functions/i18n/
[menus]: /content-management/menus/
[rellangurl]: /functions/rellangurl
[RFC 5646]: https://tools.ietf.org/html/rfc5646
[singles]: /templates/single-page-templates/
[rellangurl]: /functions/rellangurl
[singles]: /templates/single-page-templates/
content/content-management/organization.md
+30 -125
View File
@@ -9,9 +9,8 @@ categories: [content management]
tags: [sections,content,organization,fundamentals]
weight: 10
draft: false
aliases: [/content-management/sections,/content/sections/]
aliases: [/content/sections/]
toc: true
wip: true
---
## Organization of Content Source
@@ -37,18 +36,18 @@ While Hugo supports content nested at any level, the top levels (i.e. `content/<
## Path Breakdown in Hugo
The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website at render. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseurl = "http://yoursite.com"` in your [site's configuration file][config].
The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseurl = "http://yoursite.com"` in your [site's configuration file][config].
### Section Index Page
### 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] as of v0.18. 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] as of v0.18. These templates include those for [section templates][], [taxonomy templates][], [taxonomy terms templates][], and your [homepage template][]. In your templates, you can grab information from `_index.md` using the [`.Site.GetPage` function][getpage].
You can keep one `_index.md` in each of your content sections. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website:
You can keep one `_index.md` for your homepage and one in each of your content sections, taxonomies, and taxonomy terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website:
```bash
. url
. ⊢------^------⊣
. url
. ⊢--^-⊣
. path slug
. ⊢--^-⊣⊢---^---⊣
. filepath
@@ -82,7 +81,7 @@ Single content files in each of your sections are going to be rendered as [singl
content/posts/my-first-hugo-post.md
```
At the time Hugo renders your site, the content will be output to the following destination:
At the time Hugo builds your site, the content will be output to the following destination:
```bash
@@ -114,45 +113,45 @@ http://yoursite.com/events/chicago/lollapalooza/
```
{{% note %}}
As of v0.20, Hugo does not recognize nested sections. So while you can nest as many content *directories* as you'd like, any child directory of a section will still be considered the same section as that of its parents. Therefore, in the above example, `{{.Section}}` for `lollapalooza.md` is `events` and *not* `chicago`.
{{% /note %}}
## Paths Explained
#### `section`
The following concepts will provide more insight into the relationship between your project's organization and the default behaviors of Hugo when building the output website.
### `section`
A default content type is determined by a piece of content's section. `section` is determined by the location within the project's `content` directory. `section` *cannot* be specified or overridden in front matter.
#### `slug`
### `slug`
A content's `slug` is either `name.extension` or `name/`. The value for `slug` is determined by
* the name of the content file (e.g., `lollapalooza.md`) OR
* front matter overrides
#### `path`
### `path`
A content's `path` is determined by the section's path to the file. The file `path`
* is based on the path to the content's location AND
* does not include the slug
#### `url`
### `url`
The `url` is the relative URL for the piece of content. The `url`
* is based on the content's location within the directory structure OR
* is defined in front matter and *overrides all the above*
## Overriding Destinations via Front Matter
## Overriding Default Behaviors via Front Matter
Hugo believes that you organize your content with a purpose. The same structure that works to organize your source content is used to organize the rendered site. As displayed above, the organization of the source content will be mirrored in the destination.
Notice that the first level `about/` page URL was created using a directory named "about" with a single `_index.md` file inside.
There are times where you may need more control over your content. In these cases, there are fields that can be specified in the front matter to determine the destination of a specific piece of content.
The following items are defined in this order for a specific reason: latter items in the list will override earlier items, and not all of these items can be defined in front matter:
The following items are defined in this order for a specific reason: items explained further down in the list will override earlier items, and not all of these items can be defined in front matter:
### `filename`
@@ -171,7 +170,7 @@ slug: "new-post"
```
{{% /code %}}
This will render to the following destination:
This will render to the following destination according to Hugo's default behavior:
```
yoursite.com/posts/new-post/
@@ -201,123 +200,29 @@ layout: mylayout
### `url`
A complete URL can be provided. This will override all the above as it pertains to the end destination. This must be the path from the baseURL (starting with a `/`). `url` will be used exactly as it provided in the front matter and will ignore the `--uglyURLs` setting in your site configuration.
A complete URL can be provided. This will override all the above as it pertains to the end destination. This must be the path from the baseURL (starting with a `/`). `url` will be used exactly as it provided in the front matter and will ignore the `--uglyURLs` setting in your site configuration:
## \_index.md and "Everything is a Page"
As of version v0.18, Hugo now treats "[everything as a page](http://bepsays.com/en/2016/12/19/hugo-018/)". This allows you to add content and front matter to any page, including list pages like [sections][sectiontemplates], [taxonomy list pages][taxonomytemplates], [taxonomy terms pages](/templates/terms/) and even to potential "special case" pages like the [homepage][].
In order to take advantage of this behavior, you need to do a few things.
1. Create an `_index.md` file that contains the front matter and content you would like to apply.
2. Place the `_index.md` file in the correct place in the directory structure.
3. Ensure that the respective template is configured to display `{{ .Content }}` if you wish for the content of the `_index.md` file to be rendered on the respective page.
### How `_index.md` Works
Before continuing, it's important to know that this page must reference certain templates to describe how the `_index.md` page will be rendered. Hugo has a multitude of possible templates that can be used and placed in various places (think theme templates for instance). For simplicity/brevity the default/top level template location will be used to refer to the entire range of places the template can be placed.
If this is confusing or you are unfamiliar with Hugo's template hierarchy, visit the various template pages listed below. You may need to find the 'active' template responsible for any particular page on your own site by going through the template hierarchy and matching it to your particular setup/theme you are using.
- [Homepage template](/templates/homepage/)
- [Content List templates](/templates/list/)
- [Single Content templates](/templates/content/)
- [Taxonomy Terms templates](/templates/terms/)
Now that you've got a handle on templates lets recap some Hugo basics to understand how to use an \_index.md file with a List page.
1. Sections and Taxonomies are 'List' pages, NOT single pages.
2. List pages are rendered using the template heirarchy found in the [Content - List Template](http://localhost:1313/templates/list/) docs.
3. The homepage, though technically a list page, can have [it's own template](/templates/homepage/) at layouts/index.html rather than \_default/list.html. Many themes exploit this behavior so you are likely to encounter this specific use case.
4. Taxonomy terms pages are "lists of metadata" and not lists of content and therefore [have their own templates](/templates/terms/).
Let's put all this information together:
* `_index.md` files are used in list pages, terms pages, or the homepage and are *not* rendered as single pages or with [single page templates][singles].
{{% note %}}
All pages, including List pages, can have front matter and front matter can have markdown content. Thus, `_index.md` files are the way to _provide_ front matter *and* content to the respective list, terms, and homepage templates.
{{% /note %}}
Here are a couple of examples to make it clearer...
```
| \_index.md location | Page affected | Rendered by |
| ------------------- | ------------ | ----------- |
| /content/post/\_index.md | site.com/post/ | /layouts/section/post.html |
| /content/categories/hugo/\_index.md | site.com/categories/hugo/ | /layouts/taxonomy/hugo.html |
```
### Why `_index.md` Files are Used
With a Single page such as a post it's possible to add the front matter and content directly into the .md page itself. With List/Terms/Homepages this is not possible so \_index.md files can be used to provide that front matter/content to them.
### How to Display Content From `_index.md`
From the information above it should follow that content within an \_index.md file won't be rendered in its own Single Page, instead it'll be made available to the respective list, terms, Homepage.
To **_actually render that content_** you need to ensure that the relevant template responsible for rendering the List/Terms/Homepage contains (at least) `{{ .Content }}`.
This is the way to actually display the content within the \_index.md file on the List/Terms/Homepage.
A very simple example is shown in the following default section list page:
{{% code file="layouts/_default/section.html" download="section.html" %}}
```html
{{ define "main" }}
<main>
{{ .Content }}
<ul class="contents">
{{ range .Paginator.Pages }}
<li>{{.Title}}
<div>
{{ partial "summary.html" . }}
</div>
</li>
{{ end }}
</ul>
{{ partial "pagination.html" . }}
</main>
{{ end }}
{{% code file="content/posts/old-url.md" %}}
```yaml
---
title: Old URL
url: /blog/new-url/
---
```
{{% /code %}}
You can see `{{ .Content }}` just after the `<main>` element. For this particular example, the content of the \_index.md file will show before the main list of summaries.
Assuming your `baseURL` is [configured][config] to `https://yoursite.com`, the addition of `url` to the front matter will make `old-url.md` render to the following destination:
### Where to Organize `_index.md` Files
To add content and front matter to the homepage, a section, a taxonomy or a taxonomy terms listing, add a markdown file with the base name \_index on the relevant place on the file system.
```bash
└── content
├── _index.md
├── categories
│ ├── _index.md
│ └── photo
│ └── _index.md
├── post
│ ├── _index.md
│ └── firstpost.md
└── tags
├── _index.md
└── hugo
└── _index.md
```
https://yoursite.com/blog/new-url/
```
In the above example, `_index.md` pages have been added to each section and taxonomy.
An `_index.md` file has also been added in the top level 'content' directory.
### Where to Place `_index.md` for the Homepage Template
Hugo themes are designed to use the 'content' directory as the root of the website, so adding an `_index.md` file here (like has been done in the example above) is how you would add front matter and content to the homepage.
You can see more information on how to control output paths in [URL Management][urls].
[config]: /getting-started/configuration/
[formats]: /content-management/formats/
[front matter]: /content-management/front-matter/
[getpage]: /functions/getpage/
[homepage template]: /templates/homepage/
[homepage]: /templates/homepage/
[lists]: /templates/lists/
content/content-management/sections.md
+1 -1
View File
@@ -9,7 +9,7 @@ categories: [content management]
tags: [lists,sections,content types,organization]
weight: 50
draft: false
aliases: [/content-management/sections/,/content/sections/]
aliases: [/content/sections/]
toc: true
---
content/content-management/taxonomies.md
+1 -1
View File
@@ -209,7 +209,7 @@ project_url: "https://github.com/spf13/hugo"
}
```
## Adding Taxonomic `weight` to Content
## Ordering Taxonomies with `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`.
content/content-management/toc.md
+15 -9
View File
@@ -11,18 +11,17 @@ weight: 130
draft: false
aliases: [/extras/toc/,/content-management/toc/]
toc: false
wip: true
---
Hugo can automatically parse Markdown content and create a Table of Contents you can leverage in your templates to guide readers to sections of longer pages.
{{% note "TOC Heading Levels are Fixed" %}}
Currently, the {{.TableOfContents}} [page variable](/variables/page-variables/) is fixed in its behavior; i.e., you do not have the option to set the heading level at which the TOC renders. This is a [known issue (#1778)](https://github.com/spf13/hugo/issues/1778), and as always, [contributions are welcome](/contribute/development/).
Currently, the {{.TableOfContents}} [page variable](/variables/page-variables/) is fixed in its behavior; i.e., you do not have the option to set the heading level at which the TOC renders. This is a [known issue (#1778)](https://github.com/spf13/hugo/issues/1778).
{{% /note %}}
## Usage
Create your markdown the way you normally would with the appropriate headers. Here is some example content:
Create your markdown the way you normally would with the appropriate headings. Here is some example content:
```md
<!-- Your front matter up here -->
@@ -42,18 +41,25 @@ His many legs, pitifully thin compared with the size of the rest of him, waved a
A collection of textile samples lay spread out on the table - Samsa was a travelling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops
```
Hugo will take this Markdown and create a table of contents from `## Introuduction`, `## My Heading`, and `### My Subheading`stored in the [content variable](/variables/page-variables/) `.TableOfContents`.
Hugo will take this Markdown and create a table of contents from `## Introduction`, `## My Heading`, and `### My Subheading` and then store it in the [page variable][pagevars]`.TableOfContents`.
## Template Example
This is example code of a [single.html template](/templates/single-page-templates/).
The following is an example of very basic [single page template][]:
```golang
{{ partial "header.html" . }}
<aside id="toc" class="well col-md-4 col-sm-6">
{{% code file="layout/partials/toc.html" download="toc.html" %}}
```html
{{ define "main" }}
<aside id="toc">
{{ .TableOfContents }}
</aside>
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ partial "footer.html" . }}
{{ end }}
```
{{% /code %}}
[pagevars]: /variables/page-variables/
[partials]: /templates/partials/
[single page template]: /templates/single-page-template/
content/content-management/urls.md
+72 -45
View File
@@ -4,19 +4,18 @@ linktitle: URL Management
description: Hugo provides native support for permalinks, aliases, link canonicalization, and multiple options for handling relative vs absolute URLs.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
lastmod: 2017-03-09
tags: [aliases,redirects,permalinks,urls]
categories: [content management]
weight: 110
draft: false
aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/]
toc: true
wip: true
---
## Permalinks
By default, Hugo target directory for your built website is `public/`. However, you can change this value by specifying a different `publishdir` in your [site configuration][config]. The directories created at build time for a section reflect the position of the content's directory within the `content` folder and namespace matching its layout within the `contentdir` hierarchy.
The default Hugo target directory for your built website is `public/`. However, you can change this value by specifying a different `publishdir` in your [site configuration][config]. The directories created at build time for a section reflect the position of the content's directory within the `content` folder and namespace matching its layout within the `contentdir` hierarchy.
The `permalinks` option in your [site configuration][config] allows you to adjust the directory paths (i.e., the URLs) on a per-section basis. This will change where the files are written to and will change the page's internal "canonical" location, such that template references to `.RelPermalink` will honor the adjustments made as a result of the mappings in this option.
@@ -24,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., `publish` and `content`, respectively. You can override the default values in your [site's `config` file](/getting-started/configuration/).
{{% /note %}}
For example, if one of your [sections][] is called `post` and you want to adjust the canonical path to be hierarchical based on the year and month, you could set up the following configurations in YAML and TOML, respectively.
For example, if one of your [sections][] is called `post` and you want to adjust the canonical path to be hierarchical based on the year, month, and post title, you could set up the following configurations in YAML and TOML, respectively.
### YAML Permalinks Configuration Example
@@ -44,29 +43,56 @@ permalinks:
```
{{% /code %}}
Only the content under `post/` will have the new URL structure. For example, the file `content/post/sample-entry` with `date: 2013-11-18T19:20:00-05:00` in its front matter will render to `public/2013/11/sample-entry/index.html` at build time and therefore be reachable at `http://yoursite.com/2013/11/sample-entry/`.
Only the content under `post/` will have the new URL structure. For example, the file `content/post/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `http://yoursite.com/2013/11/sample-entry/`.
### Permalink Configuration Values
The following is a list of values that can be used in a `permalink` definition in your site `config` file. All references to time are dependent on the content's date.
* `:year` = the 4-digit year
* `:month` = the 2-digit month
* `:monthname` = the name of the month
* `:day` = the 2-digit day
* `:weekday` = the 1-digit day of the week (Sunday = 0)
* `:weekdayname` = the name of the day of the week
* `:yearday` = the 1- to 3-digit day of the year
* `:section` = the content's section
* `:title` = the content's title
* `:slug` = the content's slug (or title if no slug is provided in the front matter)
* `:filename` = the content's filename (without extension)
`:year`
: the 4-digit year
## Example
`:month`
: the 2-digit month
Let's assume you create a new piece of content at `content/posts/my-awesome-blog-post.md`. The content is a revision of your previous post at `content/posts/my-original-url.md`. You can create an `aliases` field in the front matter of your new `my-awesome-blog-post.md` where you can add previous paths. The following show examples of creating this filed in TOML and YAML front matter, respectively.
`:monthname`
: the name of the month
### TOML Front Matter
`:day`
: the 2-digit day
`:weekday`
: the 1-digit day of the week (Sunday = 0)
`:weekdayname`
: the name of the day of the week
`:yearday`
: the 1- to 3-digit day of the year
`:section`
: the content's section
`:title`
: the content's title
`:slug`
: the content's slug (or title if no slug is provided in the front matter)
`:filename`
: the content's filename (without extension)
## Aliases
For people migrating existing published content to Hugo, there's a good chance you need a mechanism to handle redirecting old URLs.
Luckily, redirects can be handled easily with **aliases** in Hugo.
### Example: Aliases
Let's assume you create a new piece of content at `content/posts/my-awesome-blog-post.md`. The content is a revision of your previous post at `content/posts/my-original-url.md`. You can create an `aliases` field in the front matter of your new `my-awesome-blog-post.md` where you can add previous paths. The following examples show how to create this filed in TOML and YAML front matter, respectively.
#### TOML Front Matter
{{% code file="content/posts/my-awesome-post.md" copy="false" %}}
```toml
@@ -79,7 +105,7 @@ aliases = [
```
{{% /code %}}
### YAML Front Matter
#### YAML Front Matter
{{% code file="content/posts/my-awesome-post.md" copy="false" %}}
```yaml
@@ -91,9 +117,9 @@ aliases:
```
{{% /code %}}
Now when you visit any of the locations specified in aliases---i.e., *assuming the same site domain*---you'll be redirected to the page they are specified on. For example, a visitor to `yoursite.com/posts/my-original-url/` will be immediately redirected to `yoursite.com/posts/my-awesome-blog-post`.
Now when you visit any of the locations specified in aliases---i.e., *assuming the same site domain*---you'll be redirected to the page they are specified on. For example, a visitor to `yoursite.com/posts/my-original-url/` will be immediately redirected to `yoursite.com/posts/my-awesome-blog-post/`.
## Multilingual example
### Example: Aliases in Multilingual
On [multilingual sites][multilingual], each translation of a post can have unique aliases. To use the same alias across multiple languages, prefix it with the language code.
@@ -106,31 +132,34 @@ aliases:
---
```
## Aliases
For people migrating existing published content to Hugo, there's a good chance you need a mechanism to handle redirecting old URLs.
Luckily, redirects can be handled easily with **aliases** in Hugo.
### How Hugo Aliases Work
When aliases are specified, Hugo creates a directory to match the alias entry. Inside the directory, Hugo creates an `.html` file specifying the canonical URL for the page and the new redirect target.
Assuming a baseURL of `yoursite.com`, the contents of the html file will look something like:
For example, a content file at `posts/my-intended-url.md` with the following in the front matter:
```yaml
---
title: My New post
aliases: [/posts/my-old-url/]
---
```
Assuming a `baseURL` of `yoursite.com`, the contents of the auto-generated alias `.html` found at `https://yoursite.com/posts/my-old-url/ will contain the following:`
```html
<!DOCTYPE html>
<html>
<head>
<title>http://yoursite.com/posts/my-original-url</title>
<link rel="canonical" href="http://yoursite.com/posts/my-original-url"/>
<title>http://yoursite.com/posts/my-intended-url</title>
<link rel="canonical" href="http://yoursite.com/posts/my-intended-url"/>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<meta http-equiv="refresh" content="0; url=http://yoursite.com/posts/my-original-url"/>
<meta http-equiv="refresh" content="0; url=http://yoursite.com/posts/my-intended-url"/>
</head>
</html>
```
The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case.
The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case. If an end user of your website goes to `https://yoursite.com/posts/my-old-url`, they will now be automatically redirected to the newer, correct URL.
### Customizing
@@ -148,9 +177,7 @@ layouts folder of your site (i.e., `layouts/alias.html`). In this case, the data
1. Hugo makes no assumptions about aliases. They also do not change based
on your UglyURLs setting. You need to provide absolute paths to your web root
and the complete filename or directory.
2. Aliases are rendered *before* to any content and will be overwritten by
any content with the same location.
2. Aliases are rendered *before* any content are rendered and therefore will be overwritten by any content with the same location.
## Pretty URLs
@@ -162,16 +189,16 @@ The following demonstrates the concept:
content/posts/_index.md
=> yoursite.com/posts/index.html
content/posts/post-1.md
=> yoursite.com/
content/posts/post-2.md
content/posts/post-3.md
=> yoursite.com/posts/post-1/
```
## Ugly URLs
If you would like to have what we call "ugly URLs" (e.g.,&nbsp;http://example.com/extras/urls.html), set `uglyurls = true` or `uglyurls: true` to your site-wide `config.toml` or `config.yaml`, respectively. You can also use the `--uglyURLs=true` [flag from the command line][usage].
If you would like to have are often referred to as "ugly URLs" (e.g.,&nbsp;http://example.com/extras/urls.html), set `uglyurls = true` or `uglyurls: true` to your site's `config.toml` or `config.yaml`, respectively. You can also use the `--uglyURLs=true` [flag from the command line][usage] with `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 run with the default. See [Content Organization][contentorg] for more details.
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.
```bash
.
@@ -194,7 +221,7 @@ Here's the same organization run with `hugo --uglyURLs`:
.
└── content
└── about
| └── _index.md // <- http://yoursite.com/about/
| └── _index.md // <- http://yoursite.com/about/index.html
├── post
| ├── firstpost.md // <- http://yoursite.com/post/firstpost.html
| ├── happy
@@ -208,11 +235,11 @@ Here's the same organization run with `hugo --uglyURLs`:
## Canonicalization
By default, all relative URLs encountered in the input are left unmodified, e.g. `/css/foo.css` would stay as `/css/foo.css`, i.e. `canonifyURLs` defaults to `false`.
By default, all relative URLs encountered in the input are left unmodified, e.g. `/css/foo.css` would stay as `/css/foo.css`. The `canonifyURLs` field in your site `config` has a default value of `false`.
By setting `canonifyURLs` to `true`, all relative URLs would instead be *canonicalized* using `baseURL`. For example, assuming you have `baseURL = http://yoursite.com/` defined in the site-wide `config.toml`, the relative URL `/css/foo.css` would be turned into the absolute URL `http://yoursite.com/css/foo.css`.
By setting `canonifyURLs` to `true`, all relative URLs would instead be *canonicalized* using `baseURL`. For example, assuming you have `baseURL = https://yoursite.com/`, the relative URL `/css/foo.css` would be turned into the absolute URL `http://yoursite.com/css/foo.css`.
Benefits of canonicalization include fixing all URLs to be absolute, which may aid with some parsing tasks. Note, however, that all modern browsers handle this on the client without issues.
Benefits of canonicalization include fixing all URLs to be absolute, which may aid with some parsing tasks. Note, however, that all modern browsers handle this on the client without issue.
Benefits of non-canonicalization include being able to have scheme-relative resource inclusion; e.g., so that `http` vs `https` can be decided according to how the page was retrieved.
content/contribute/_index.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
title: Contribute to Hugo
title: Contributing to the Hugo Project
linktitle: Overview
description: Contribute to Hugo development and documentation.
date: 2017-02-01
content/contribute/development.md
+1 -3
View File
@@ -1,6 +1,6 @@
---
title: Contribute to Hugo Development
linktitle: Code
linktitle: Development
description: Hugo relies heavily on contributions from the open source community. You don't need to be a Golang guru to contribute to the project's development.
date: 2017-02-01
publishdate: 2017-02-01
@@ -12,8 +12,6 @@ weight: 10
draft: false
aliases: [/contribute/development/]
toc: true
wip: true
notesforauthors:
---
## Introduction
content/contribute/documentation.md
+44 -53
View File
@@ -1,6 +1,6 @@
---
title: Contribute to the Hugo Docs
linktitle: Docs
linktitle: Documentation
description: Documentation is an integral part of any open source project. The Hugo docs are as much a work in progress as the source it attempts to teach its users.
date: 2017-02-01
publishdate: 2017-02-01
@@ -11,16 +11,15 @@ weight: 20
draft: false
aliases: [/contribute/docs/]
toc: true
wip: true
---
Documentation is a critical component of any open-source project. The Hugo docs were completely reworked for the release of v0.19, but there is always room for improvement.
Documentation is a critical component of any open-source project. The Hugo docs were completely reworked for the release of v0.20, but there is always room for improvement.
## Create Your Fork
It's best to make changes to the Hugo docs on your local machine to check for consistent visual styling. Make sure you've created a fork of Hugo on GitHub and cloned the repository locally on your computer. For more information, you can use the [GitHub docs for "forking"][ghforking] or see [Hugo's extensive development contribution guide][hugodev].
It's best to make changes to the Hugo docs on your local machine to check for consistent visual styling. Make sure you've created a fork of Hugo on GitHub and cloned the repository locally on your machine. For more information, you can see [GitHub's documentation on "forking"][ghforking] or follow along with [Hugo's development contribution guide][hugodev].
You can then create a separate branch for your additions. Note that you can choose a different descriptive branch name that best fits the type of content. The following is an example of a branch name you might use for adding a new website to the showcase:
You can then create a separate branch for your additions. Be sure to choose a descriptive branch name that best fits the type of content. The following is an example of a branch name you might use for adding a new website to the showcase:
```git
git checkout -b jon-doe-showcase-addition
@@ -28,16 +27,16 @@ git checkout -b jon-doe-showcase-addition
## Adding New Content
The Hugo docs are built using Hugo and therefore make heavy use of Hugo's [archetypes][] feature to easily scaffold new instances of content types. All content sections in Hugo documentation have an assigned archetype ([see the Hugo docs archetype source][archsource]).
The Hugo docs make heavy use of Hugo's [archetypes][] feature. All content sections in Hugo documentation have an assigned archetype.
Adding new content follows the same pattern, regardless of the content section:
Adding new content to the Hugo docs follows the same pattern, regardless of the content section:
```
hugo new <docssection>/<newcontent-all-lowercase.md>
hugo new <DOCS-SECTION>/<new-content-lowercase>.md
```
{{% note "`title:`, `date:`, and Field Order" %}}
`title` and `date` fields are added automatically when using archetypes via `hugo new`. Do not be worried if the order of the new file's front matter fields on your local machine is different than that of the following examples. This is a [known issue (#452)](https://github.com/spf13/hugo/issues/452).
`title` and `date` fields are added automatically when using archetypes via `hugo new`. Do not be worried if the order of the new file's front matter fields on your local machine is different than that of the examples provided in the Hugo docs. This is a known issue [(#452)](https://github.com/spf13/hugo/issues/452).
{{% /note %}}
### Adding a New Function
@@ -56,36 +55,39 @@ The archetype for the `functions` content type is as follows:
```
{{% /code %}}
#### Function Required Fields
#### New Function Required Fields
Let's review some of the fields automatically generated for you using `hugo new functions/*`:
Here is a review of the front matter fields automatically generated for you using `hugo new functions/*`:
***`title`***
: This should be generated in all lowercase when you use `hugo new`.
: this will be auto-populated in all lowercase when you use `hugo new` generator.
***`linktitle`***
: Use the function's actual casing (e.g., `replaceRE` rather than `replacere`).
: the function's actual casing (e.g., `replaceRE` rather than `replacere`).
***`description`***
: Keep this really short. This is what's used to populate the [Functions Quick Reference](/functions/).
: a brief description used to populate the [Functions Quick Reference](/functions/).
`categories`
: This is populated with 'functions` for future-proofing and portability reasons only. Skip this field.'
: currently auto-populated with 'functions` for future-proofing and portability reasons only; ignore this field.
`tags`
: Only if you think it will help end users find other related functions
: only if you think it will help end users find other related functions
`signature`
: This is a signature/syntax definition for calling the function (e.g., `apply SEQUENCE FUNCTION [PARAM...]`)
: this is a signature/syntax definition for calling the function (e.g., `apply SEQUENCE FUNCTION [PARAM...]`).
`workson`
: Acceptable values include `lists`,`taxonomies`, `terms`, `groups`, and `files`
: acceptable values include `lists`,`taxonomies`, `terms`, `groups`, and `files`.
`hugoversion`
: The version of Hugo that will ship with this new function
: the version of Hugo that will ship with this new function.
`relatedfuncs`
: If you can, list some functions you think 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.
In the body of you function, expand the short description used in the front matter. Include as many examples as possible, and leverage the Hugo docs [code shortcodes](#adding-code-blocks). If you are unable to add examples but would like to solicit help from the Hugo community, add `needsexample: true` to your front matter.
@@ -108,16 +110,16 @@ The archetype for the `showcase` content type is as follows:
#### Showcase Required Fields
`sitelink`
: the *full* URL to your website
: the *full* URL to your website.
`title`
: the `<title>` of your website
: the `<title>` of your website.
`description`
: a general description of your website, preferably < 180 characters.
`image`
: the image (filename only) you want to associate with your website on the Showcase page. The image should be 600px x 400px.
: the image (filename only) you want to associate with your website on the Showcase page. The image should be 450px &times; 300px.
We also appreciate the addition of the remaining fields, specially `sourcelink` and `license` if you are willing to share your hard work with the open-source community. `tags` is optional, but we recommend adding at least 2 to 3 tags to improve discoverability.
@@ -166,14 +168,14 @@ Your options for languages are `xml`/`html`, `go`/`golang`, `md`/`markdown`/`mkd
The Hugo documentation comes with very robust shortcodes to help you add interactive code snippets.
{{% note %}}
With both `code` and `output` shortcodes, *you must include triple back ticks and language declaration*. This was done by design so that the shortcode wrappers were easily added to legacy documentation and will be that much easier to remove if needed in future versions of the Hugo docs. We assume that the triple-back-tick syntax will live longer than our current, pretty shortcode. {{< emo ":smile:" >}}
With the `code` shortcodes, *you must include triple back ticks and a language declaration*. This was done by design so that the shortcode wrappers were easily added to legacy documentation and will be that much easier to remove if needed in future versions of the Hugo docs. We assume that the triple-back-tick syntax will live longer than our current, pretty shortcode.
{{% /note %}}
#### `code`
### `code`
`code` is the code block shortcode you'll use most often. `code` requires at least a single `file` named parameter. Here is the signature:
`code` is the code block shortcode you'll use most often. `code` requires at least a single `file` named parameter. Here is the pattern:
````golang
````markdown
{{%/* code file="smart/file/name/with/path.html" download="download.html" copy="true" */%}}
```language
A whole bunch of coding going on up in here! Boo-yah!
@@ -192,14 +194,14 @@ These are the arguments passed into `code`
`copy`
: a copy button is added automatically to all `code` (i.e., default value = `true`). If you want to keep the filename and styling of `code` but don't want to encourage readers to copy the code (e.g., a "Do not do" snippet in a tutorial), pass the `copy` argument as `copy="false"`.
##### Example `code` Input
#### Example `code` Input
Here is an HTML code block in a case where we want to show the user of the Hugo docs the following:
This HTML code block tells Hugo users the following:
1. This type of file *could* live in `layouts/_default`.
2. This snippet is complete enough that it might be worth downloading as a standalone file.
1. This file *could* live in `layouts/_default`, as demonstrated by `layouts/_default/single.html`.
2. This snippet is complete enough to be downloaded an implement in a Hugo project, as demonstrated by `download="single.html".`
````html
````md
{{%/* code file="layouts/_default/single.html" download="single.html" */%}}
```html
{{ define "main" }}
@@ -251,7 +253,7 @@ The output of this example will render to the Hugo docs as follows:
Cool, right?
#### Output Code Block
<!-- #### Output Code Block
The `output` shortcode is almost identical to the `code` shortcode but only takes and requires `file`. The purpose of `output` is to show *rendered* HTML and therefore almost always follows another basic code block *or* and instance of the `code` shortcode:
@@ -271,7 +273,7 @@ The preceding `output` example will render as follows to the Hugo docs:
<h1>This is my First Hugo Blog Post</h1>
<p>I am excited to be using Hugo.</p>
```
{{% /output %}}
{{% /output %}} -->
## Blockquotes
@@ -288,7 +290,7 @@ The preceding blockquote will render as follows in the Hugo docs:
However, you can add a quick and easy `<cite>` element (added on the client via JavaScript) by separating your main blockquote and the citation with ` - `:
```markdown
> Without the threat of punishment, there is no joy in flight. - [Kobo Abe](https://en.wikipedia.org/wiki/K%C5%8Db%C5%8D_Abe)
> Without the threat of punishment, there is no joy in flight. - [Kobo Abe](https://en.wikipedia.org/wiki/Kobo_Abe)
```
Which will render as follows on the Hugo docs:
@@ -314,7 +316,7 @@ Use the `note` shortcode when you want to draw attention to information subtly.
#### Example `note` Input
{{% code file="note-with-heading.md" %}}
```golang
```markdown
{{%/* note "Example Note Admonition" */%}}
Here is a piece of information I would like to draw your **attention** to.
{{%/* /note */%}}
@@ -344,7 +346,7 @@ Use the `warning` shortcode when you want to draw the user's attention to someth
#### Example `warning` Input
{{% code file="warning-admonition-input.md" %}}
```golang
```markdown
{{%/* warning "Example Warning Admonition" */%}}
This is a warning, which should be reserved for *important* information like breaking changes.
{{%/* /warning */%}}
@@ -367,17 +369,6 @@ This is a warning, which should be reserved for *important* information like bre
This is a warning, which should be reserved for *important* information like breaking changes.
{{% /warning %}}
## Editorial Style Guide
{{% note %}}
It's more important to contribute *some* documentation than no documentation at all. We need your help!
{{% /note %}}
The Hugo docs are not especially prescriptive in terms of grammar and usage. We encourage everyone to contribute regardless of your writing style. That said, here are a few gotchas when writing your documentation that, if observed, will create a more consistent documentation experience for the Hugo community:
1. *Front matter* and *file system* are two words; *Homepage* is one word.
3. Add a `godocref` value to the front matter of content files whenever possible. We want to promote Hugo *and* Golang by demonstrating the inseparable wedding of the two.
## Ask for Code Examples
Sometimes you want to contribute to the docs but don't have enough time to provide lengthy examples. If you want to flag a piece of content as needing more examples, add the following field to your front matter:
@@ -388,20 +379,20 @@ needsexamples: true
## Places to Start
The preceding `needsexamples` is used to generate the following list of pages flagged for needing example. Links will take you directly to the edit URL for the file within the GitHub GUI:
The preceding `needsexamples` field is used to generate the following list of flagged content. Links will take you directly to the edit URL for the file within the GitHub GUI in the event that you are not comfortable cloning and editing the repository locally.
{{< needsexamples >}}
{{% note "Pull Requests and Branches" %}}
Similar to [contributing to Hugo development](/contribute/contribute-to-hugo-development), the Hugo team expects you to create a separate branch/fork when you make your generous contributions to the Hugo docs.
Similar to [contributing to Hugo development](/contribute/development/), the Hugo team expects you to create a separate branch/fork when you make your generous contributions to the Hugo docs.
{{% /note %}}
[abe]: https://en.wikipedia.org/wiki/K%C5%8Db%C5%8D_Abe
[abe]: https://en.wikipedia.org/wiki/Kobo_Abe
[archetypes]: /content-management/archetypes/
[archsource]: https://github.com/spf13/hugo/tree/master/docs/archetypes
[bqsyntax]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#blockquotes
[charcount]: http://www.lettercount.com/
[ghforking]: https://help.github.com/articles/fork-a-repo/
[hugodev]: /contribute/development/
[shortcodeparams]: content-management/shortcodes/#shortcodes-without-markdown
[sourceforge]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
[sourceforge]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
[templating function]: /functions/
content/functions/emojify.md
+5 -19
View File
@@ -19,30 +19,16 @@ deprecated: false
See the [Emoji cheat sheet][emojis] for available emoticons.
```
{{ "I :heart: Hugo" | emojify }}
```
The `emojify` function can be called in your templates but not directly in your content files by default. To add emojis directly into content without further templating or shortcode considerations, set `enableEmoji` to `true` in your site's [configuration][config].
The `emojify` function can be called in your templates but not directly in your content files. However, emojis are most often seen inline. The following is a very simple [shortcode template][sc] you can use to add emojis quickly while you write content. It is also the `emo` shortcode used for the Hugo docs. ([See Hugo Docs Shortcodes Source][scsource].)
## Example
{{% code file="layouts/shortcodes/emo.html" download="emo.html" %}}
```golang
{{< readfile file="layouts/shortcodes/emo.html" >}}
```
{{% /code %}}
When enabled, you can write emoji shorthand directly into your content files; e.g. <code>I :</code><code>heart</code><code>: Hugo!</code>:
You can then call the shortcode directly in your content using the following:
I :heart: Hugo!
{{% code file="content/functions/emojify.md" %}}
```golang
I {{</* emo ":heart:" */>}} Hugo!
```
{{% /code %}}
The preceding use of the `emo` shortcode called in content will display as follows:
I {{< emo ":heart:" >}} Hugo!
[config]: /getting-started/configuration/
[emojis]: http://www.emoji-cheat-sheet.com/
[sc]: /templates/shortcode-templates/
[scsource]: https://github.com/spf13/hugo/tree/master/docs/layouts/shortcodes
content/getting-started/_index.md
+1 -1
View File
@@ -13,7 +13,7 @@ aliases: [/overview/introduction/]
toc: false
---
The Hugo docs were completely reworked for the release of Hugo v0.19. If this is your first time using Hugo and you've [already installed Hugo on your machine][installed], we recommend the [quick start][].
The Hugo docs were completely reworked for the release of Hugo v0.20. If this is your first time using Hugo and you've [already installed Hugo on your machine][installed], we recommend the [quick start][].
[installed]: /getting-started/installing/
[quick start]: /getting-started/quick-start/
content/getting-started/configuration.md
+11 -2
View File
@@ -308,6 +308,15 @@ watch = true
```
{{% /code %}}
{{% note %}}
If you are developing your site on a \*nix machine, here is a handy shortcut for finding a configuration option from the command line:
```bash
~/sites/yourhugosite
hugo config | grep emoji
enableemoji: true
```
{{% /note %}}
## Environmental Variables
In addition to the 3 configuration file options already mentioned, website configuration can be accomplished through operating system environment variables.
@@ -333,7 +342,7 @@ ignoreFiles = [ "\\.foo$", "\\.boo$" ]
The above is a list of regular expressions. Note that the backslash (`\`) character is escaped in this example to keep TOML happy.
## Configuring Blackfriday Rendering
## Configuring Blackfriday
[Blackfriday](https://github.com/russross/blackfriday) is Hugo's built-in
Markdown rendering engine.
@@ -370,7 +379,7 @@ blackfriday:
```
{{% /code %}}
## Specs for Configuration Formats
## Configuration Format Specs
* [TOML Spec][toml]
* [YAML Spec][yaml]
content/getting-started/directory-structure.md
+6 -8
View File
@@ -1,10 +1,10 @@
---
title: Directory Structure
linktitle: Directory Structure
description: Hugo's CLI scaffolds a project's directory structure nearly instantly and then takes that single directory and uses it as the input for creating a complete website.
description: Hugo's CLI scaffolds a project directory structure and then takes that single directory and uses it as the input for creating a complete website.
date: 2017-01-02
publishdate: 2017-01-02
lastmod: 2017-01-02
publishdate: 2017-02-01
lastmod: 2017-03-09
categories: [project organization]
tags: [source, organization, directories,fundamentals]
weight: 50
@@ -14,12 +14,10 @@ aliases: [/overview/source-directory/]
toc: true
---
<!-- copied from old overview/source-directory -->
Hugo takes a single directory and uses it as the input for creating a complete
website.
## Directory Scaffolding in New Hugo Sites
## Directory Scaffolding in `new hugo site`
The top level of a source directory will typically have the following elements:
@@ -34,13 +32,13 @@ The top level of a source directory will typically have the following elements:
config.toml
```
Learn more about the different directories and what their purpose is:
You can learn more about each component of a newly scaffolded site in its respective documentation:
* [config](/getting-started/configuration/)
* [data](/templates/data-templates/)
* [i18n](/content-management/multilingual/)
* [archetypes](/content-management/archetypes/)
* [content](/content-managemt/organization/)
* [content](/content-management/organization/)
* [layouts](/templates/)
* [static](/themes/creating-a-theme/)
* [themes](/themes/)
content/getting-started/installing.md
+10 -13
View File
@@ -14,21 +14,19 @@ aliases: [/tutorials/installing-on-windows/,/tutorials/installing-on-mac/,/overv
toc: true
---
## Quick Install
Hugo is written in [Golang](https://golang.org/) with support for multiple platforms.
The latest release can be found at [Hugo Releases][releases].
Hugo is written in [Golang](https://golang.org/) with support for multiple platforms. The latest release can be found at [Hugo Releases][releases].
Hugo currently provides pre-built binaries for the following:
* <i class="fa fa-apple"></i> OS X (Darwin) for x64, i386, and ARM architectures
* <i class="fa fa-windows"></i> Windows
* <i class="fa fa-linux"></i> Linux
* <i class="icon-apple"></i> OS X (Darwin) for x64, i386, and ARM architectures
* <i class="icon-windows"></i> Windows
* <i class="icon-linux"></i> Linux
* <i class="icon-freebsd"></i> FreeBSD
Hugo may also be compiled from source wherever the Go compiler tool chain can run; e.g., for other operating systems, including DragonFly BSD, OpenBSD, Plan&nbsp;9 and Solaris. See <http://golang.org/doc/install/source> for the full set of supported combinations of target operating systems and compilation architectures.
## Quick Install
### Binary (Cross-platform)
Download the appropriate version for your platform from [Hugo Releases][releases]. Once downloaded, the binary can be run from anywhere. You don't need to install it into a global location. This works well for shared hosts and other systems where you don't have a privileged account.
@@ -45,7 +43,7 @@ brew update && brew install hugo
```
{{% /code %}}
For more detailed explanations, read the installation guides that follow for [Windows](#installing-hugo-on-windows) and [Mac OS X](#installing-hugo-on-mac-osx).
For more detailed explanations, read the installation guides that follow for installing on Mac OS X and Windows.
### Source
@@ -72,7 +70,7 @@ You may run `go get` with the `-u` option to update Hugo's dependencies:
go get -u -v github.com/spf13/hugo
```
## <i class="fa fa-apple"></i> OS X
## <i class="icon-apple"></i>OS X
### Assumptions
@@ -293,7 +291,7 @@ go build -o hugo main.go
Then place the `hugo` executable somewhere in your `$PATH`. You're now ready to start using Hugo.
## <i class="fa fa-windows"></i> Windows
## <i class="icon-windows"></i>Windows
The following aims to be a complete guide to installing Hugo on your Windows PC.
@@ -408,7 +406,7 @@ C:\Hugo\Sites\example.com&gt;dir
{{< youtube c8fJIRNChmU >}}
## <i class="fa fa-linux"></i> Linux
## <i class="icon-linux"></i>Linux
### Installing From Snap
@@ -426,7 +424,6 @@ Install Hugo from the [Arch user repository](https://aur.archlinux.org/) on Arch
Be aware that Hugo is built from source. This means that additional tools like Git and Go (the programming language Hugo is written in) will be installed as well.
{{% /note %}}
```bash
sudo pacman -S yaourt
yaourt -S hugo
content/getting-started/usage.md
+89 -113
View File
@@ -9,12 +9,13 @@ categories: [getting started]
tags: [usage,livereload,command line,flags]
weight: 40
draft: false
aliases: [/overview/usage/,/extras/livereload/,/doc/usage/]
aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/]
toc: true
wip: true
---
## Testing Installation with `hugo help`
The following is a description of the most command commands you will use while developing your Hugo project. See the [Command Line Reference][commands] for a comprehensive view of Hugo's CLI.
## Testing Installation
Once you have [installed Hugo][install], make sure it is in your `PATH`. You can test that Hugo has been installed correctly via the `help` command:
@@ -27,7 +28,8 @@ The output you see in your console should be similar to the following:
```bash
hugo is the main command, used to build your Hugo site.
Hugo is a Fast and Flexible Static Site Generator built with love by spf13 and friends in Go.
Hugo is a Fast and Flexible Static Site Generator
built with love by spf13 and friends in Go.
Complete documentation is available at http://gohugo.io/.
@@ -37,6 +39,7 @@ Usage:
Available Commands:
benchmark Benchmark Hugo by building a site a number of times.
check Contains some verification checks
config Print the site configuration
convert Convert your content to different formats
env Print Hugo version and environment info
@@ -49,51 +52,50 @@ Available Commands:
version Print the version number of Hugo
Flags:
-b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/
-D, --buildDrafts include content marked as draft
-E, --buildExpired include expired content
-F, --buildFuture include content with publishdate in the future
--cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
--canonifyURLs if true, all relative URLs will be canonicalized using baseURL
--cleanDestinationDir Remove files from destination not found in static directories
--config string config file (default is path/config.yaml|json|toml)
-c, --contentDir string filesystem path to content directory
-d, --destination string filesystem path to write files to
--disable404 Do not render 404 page
--disableRSS Do not build RSS files
--disableSitemap Do not build Sitemap file
--enableGitInfo Add Git revision, date and author info to the pages
--forceSyncStatic Copy all files when static is changed.
--i18n-warnings Print missing translations
--ignoreCache Ignores the cache directory
-l, --layoutDir string filesystem path to layout directory
--log Enable Logging
--logFile string Log File path (if set, logging enabled automatically)
--noChmod Don't sync permission mode of files
--noTimes Don't sync modification time of files
--pluralizeListTitles Pluralize titles in lists using inflect (default true)
--preserveTaxonomyNames Preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu")
--quiet build in quiet mode
--renderToMemory render to memory (only useful for benchmark testing)
-s, --source string filesystem path to read files relative from
--stepAnalysis display memory and timing of different steps of the program
-t, --theme string theme to use (located in /themes/THEMENAME/)
--uglyURLs if true, use /filename.html instead of /filename/
-v, --verbose verbose output
--verboseLog verbose logging
-w, --watch watch filesystem for changes and recreate as needed
Additional help topics:
hugo check Contains some verification checks
Use "hugo [command] --help" for more information about a command.
-b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/
-D, --buildDrafts include content marked as draft
-E, --buildExpired include expired content
-F, --buildFuture include content with publishdate in the future
--cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
--canonifyURLs if true, all relative URLs will be canonicalized using baseURL
--cleanDestinationDir Remove files from destination not found in static directories
--config string config file (default is path/config.yaml|json|toml)
-c, --contentDir string filesystem path to content directory
-d, --destination string filesystem path to write files to
--disable404 Do not render 404 page
--disableKinds stringSlice Disable different kind of pages (home, RSS etc.)
--disableRSS Do not build RSS files
--disableSitemap Do not build Sitemap file
--enableGitInfo Add Git revision, date and author info to the pages
--forceSyncStatic Copy all files when static is changed.
--i18n-warnings Print missing translations
--ignoreCache Ignores the cache directory
-l, --layoutDir string filesystem path to layout directory
--log Enable Logging
--logFile string Log File path (if set, logging enabled automatically)
--noChmod Don't sync permission mode of files
--noTimes Don't sync modification time of files
--pluralizeListTitles Pluralize titles in lists using inflect (default true)
--preserveTaxonomyNames Preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu")
--quiet build in quiet mode
--renderToMemory render to memory (only useful for benchmark testing)
-s, --source string filesystem path to read files relative from
--stepAnalysis display memory and timing of different steps of the program
-t, --theme string theme to use (located in /themes/THEMENAME/)
--themesDir string filesystem path to themes directory
--uglyURLs if true, use /filename.html instead of /filename/
-v, --verbose verbose output
--verboseLog verbose logging
-w, --watch watch filesystem for changes and recreate as needed
```
## Common Usage
## The `hugo` Command
The most common usage is probably to run `hugo` with your current directory being the input directory.
This generates your website to the `public/` directory by default---although [this can be configured to your needs via `publishDir`][configdir]---ready to be deployed to your web server.
This generates your website to the `public/` directory by default, although you can customize the output directory in your [site configuration][config] by changing the `publishDir` field.
The site Hugo renders into `public/` is ready to be deployed to your web server:
```bash
hugo
@@ -103,63 +105,49 @@ hugo
0 paginator pages created
16 tags created
0 groups created
in 120 ms
in 90 ms
```
## Instant Feedback During Development
## Draft, Future, and Expired Content
If you are working on things and want to see the changes immediately, by default Hugo will watch the file system for changes and rebuild your site as soon as a file is saved:
Hugo allows you to set `draft`, `publishdate`, and even `expirydate` in your content's [front matter][]. By default, Hugo will not publish:
```bash
hugo -s ~/Code/hugo/docs
0 draft content
0 future content
99 pages created
0 paginator pages created
16 tags created
0 groups created
in 120 ms
Watching for changes in /Users/spf13/Code/hugo/docs/content
Press Ctrl+C to stop
```
1. Content with a future `publishdate` value
2. Content with `draft: true` status
3. Content with a past `expirydate` value
Hugo can even run a server and create a site preview at the same time! Hugo implements [LiveReload](#LiveReload) technology to automatically reload any open pages in all JavaScript-enabled browsers, including mobile. This is the easiest and most common way to develop a Hugo web site:
All three of these can be overridden during both local development *and* deployment by adding the following flags to `hugo` and `hugo server`, respectively, or by changing the boolean values assigned to the fields of the same name (without `--`) in your [configuration][config]:
```bash
hugo server -ws ~/Code/hugo/docs
0 draft content
0 future content
99 pages created
0 paginator pages created
16 tags created
0 groups created
in 120 ms
Watching for changes in /Users/spf13/Code/hugo/docs/content
Serving pages from /Users/spf13/Code/hugo/docs/public
Web Server is available at http://localhost:1313/
Press Ctrl+C to stop
```
Hugo may not be the first static site generator to utilize LiveReload
technology, but it’s the first to do it right.
1. `--buildFuture`
2. `--buildDrafts`
3. `--buildExpired`
The combination of Hugo’s insane build speed and LiveReload make
crafting your content pure joy. Your updated content appears virtually instantly in your browser as soon as you save your changes.
## LiveReload
### LiveReload
Hugo comes with [LiveReload](https://github.com/livereload/livereload-js) built in. There are no additional packages to install. A common way to use Hugo while developing a site is to have Hugo run a server and watch for changes:
Hugo comes with [LiveReload](https://github.com/livereload/livereload-js) built in. There are no additional packages to install. A common way to use Hugo while developing a site is to have Hugo run a server with the `hugo server` command and watch for changes:
```bash
hugo server
0 draft content
0 future content
99 pages created
0 paginator pages created
16 tags created
0 groups created
in 120 ms
Watching for changes in /Users/yourname/sites/yourhugosite/{data,content,layouts,static}
Serving pages from /Users/yourname/sites/yourhugosite/public
Web Server is available at http://localhost:1313/
Press Ctrl+C to stop
```
This will run a fully functioning web server while simultaneously watching your file system for additions, deletions, or changes within the following the following areas of your [project organization][directorystructure]
This will run a fully functioning web server while simultaneously watching your file system for additions, deletions, or changes within the following areas of your [project organization][dirs]:
* `/static/*`
* `/content/*`
* `/data/*`
* `/layouts/*`
* `/themes/<only your current theme>/*`
* `/themes/<CURRENT-THEME>/*`
* `config`
Whenever you make changes, Hugo will simultaneously rebuild the site and continue to serve content. As soon as the build is finished, LiveReload tells the browser to silently reload the page.
@@ -167,26 +155,26 @@ Whenever you make changes, Hugo will simultaneously rebuild the site and continu
Most Hugo builds are so fast that you may not notice the change unless looking directly at the site in your browser. This means that keeping the site open on a second monitor (or another half of your current monitor) allows you to see the most up-to-date version of your website without the need to leave your text editor.
{{% note "Closing `</body>` Tag"%}}
You must have a closing `</body>` tag for LiveReload to work.
Hugo injects the LiveReload `<script>` before this tag.
Hugo injects the LiveReload `<script>` before the closing `</body>` in your templates and will therefore not work if this tag is not present..
{{% /note %}}
### Disabling LiveReload's Watch Feature
### Disabling LiveReload
LiveReload works by injecting JavaScript into the pages Hugo generates. The script creates a connection from the browser's web socket client to the
Hugo web socket server.
LiveReload works by injecting JavaScript into the pages Hugo generates. The script creates a connection from the browser's web socket client to the Hugo web socket server.
LiveReload is awesome for development. However, some Hugo users may use `hugo server` in production to instantly display updated content. As such, we’ve provided multiple methods made it easy to disable the LiveReload functionality:
LiveReload is awesome for development. However, some Hugo users may use `hugo server` in production to instantly display updated content. The following methods make it easy to disable LiveReload:
```bash
hugo server --watch=false
```
Or...
```bash
hugo server --disableLiveReload
```
The latter flag can be omitted by adding the following key-value to your `config` file:
The latter flag can be omitted by adding the following key-value to your `config.toml` or `config.yml` file, respectively:
```toml
disableLiveReload = true
@@ -198,17 +186,15 @@ disableLiveReload: true
## Deploying Your Website
After running `hugo server` for local web development, you need to do a final `hugo` run **without the `server` part of the command** to rebuild your site. You may then **deploy your site** by copying the `public/` directory (by FTP, SFTP, WebDAV, Rsync, `git push`, etc.) to your production web server.
After running `hugo server` for local web development, you need to do a final `hugo` run *without the `server` part of the command* to rebuild your site. You may then deploy your site by copying the `public/` directory to your production web server.
Since Hugo generates a static website, your site can be hosted anywhere, including [Heroku][], [GoDaddy][], [DreamHost][], [GitHub Pages][], [Amazon S3][] with [CloudFront][], [Firebase Hosting][], or any other cheap (or even free) static web hosting service.
[Apache][], [nginx][], [IIS][]...any web server software will work.
Since Hugo generates a static website, your site can be hosted *anywhere* using any web server. See [Hosting and Deployments][] for methods for hosting and automating deployments contributed by the Hugo community.
{{% warning "Generated Files are **NOT** Removed on Site Build" %}}
Running `hugo` *does not* remove generated files before building. This means that you should delete your `public/` directory (or the directory you specified with `-d`/`--destination`) before running the `hugo` command, or you run the risk of the wrong files (e.g., drafts or future posts) being left in the generated site.
Running `hugo` *does not* remove generated files before building. This means that you should delete your `public/` directory (or the publish directory you specified via flag or configuration file) before running the `hugo` command. If you do not remove these files, you run the risk of the wrong files (e.g., drafts or future posts) being left in the generated site.
{{% /warning %}}
### Destination Directories for Dev vs Deploy
### Dev vs Deploy Destinations
Hugo does not remove generated files before building. An easy workaround is to use different directories for development and production.
@@ -224,7 +210,7 @@ When the content is ready for publishing, use the default `public/` dir:
hugo -s ~/Code/hugo/docs
```
This prevents content you're not yet ready to share from accidentally becoming available.
This prevents draft content from accidentally becoming available.
### Using Hugo's Server in Production
@@ -234,14 +220,12 @@ No other web server software (e.g., Apache, nginx, IIS) is necessary.
Here is the command:
{{% code file="hugo-production-server.sh" %}}
```bash
hugo server --baseURL=http://yoursite.org/ \
--port=80 \
--appendPort=false \
--bind=87.245.198.50
```
{{% /code %}}
Note the `bind` option, which is the interface to which the server will bind (defaults to `127.0.0.1`: fine for most development use cases). Some hosts, such as Amazon Web Services, run NAT (network address translation); sometimes it can be hard to figure out the actual IP address. Using `--bind=0.0.0.0` will bind to all interfaces.
@@ -251,17 +235,9 @@ Interested? Here are some great tutorials contributed by Hugo users:
* [hugo, syncthing](http://fredix.xyz/2014/10/hugo-syncthing/) (French) by Frédéric Logier (@fredix)
[Amazon S3]: http://aws.amazon.com/s3/
[Apache]: http://httpd.apache.org/ "Apache HTTP Server"
[CloudFront]: http://aws.amazon.com/cloudfront/ "Amazon CloudFront"
[configdir]: /getting-started/configuration/
[directorystructure]: /getting-started/directory-structure/
[DreamHost]: http://www.dreamhost.com/
[Firebase Hosting]: https://firebase.google.com/docs/hosting/
[GitHub Pages]: https://pages.github.com/
[GitLab]: https://about.gitlab.com
[GoDaddy]: https://www.godaddy.com/
[Heroku]: https://www.heroku.com/
[IIS]: http://www.iis.net/
[install]: /getting-started/installing/
[nginx]: http://nginx.org/
[commands]: /commands/
[config]: /getting-started/configuration/
[dirs]: /getting-started/directory-structure/
[front matter]: /content-management/front-matter/
[hosting]: /hosting-and-deployments/
[install]: /getting-started/installing/
content/showcase/2626info.md
+1 -1
View File
@@ -7,7 +7,7 @@ sitelink: http://2626.info/
tags:
- personal
- blog
image: 2626info.png
image: 2626info.jpg
title: 2626.info
---
content/showcase/_index.md
+1 -1
View File
@@ -15,7 +15,7 @@ aliases: [/site-showcase/]
toc: false
---
The following sites have been built with {{< emo ":heart:" >}} and Hugo. If you're interested in adding your site to the showcase, [see how to contribute][addshowcase].
The following sites have been built with Hugo. If you've recently built a site with Hugo that you'd like to share with the community, please [contribute][addshowcase].
[addshowcase]: /contribute/documentation/#adding-to-the-showcase
content/showcase/appernetic.md
+1 -1
View File
@@ -10,6 +10,6 @@ tags:
- company
- blog
- bootstrap
image: apperneticioblog.png
image: apperneticioblog.jpg
title: Appernetic
---
content/showcase/arresteddevops.md
+1 -1
View File
@@ -9,7 +9,7 @@ sourcelink: https://github.com/arresteddevops/ado-hugo
tags:
- podcast
- bootstrap
image: arresteddevops.png
image: arresteddevops.jpg
title: arresteddevops
---
content/showcase/astrochili.md
+1 -1
View File
@@ -8,7 +8,7 @@ sourcelink: https://github.com/astrochili/astrochili.github.io
tags:
- personal
- blog
image: astrochili.png
image: astrochili.jpg
title: Roman Silin
---
content/showcase/aydoscom.md
+1 -1
View File
@@ -6,7 +6,7 @@ licenseLink: ""
sitelink: https://aydos.com/
tags:
- web applications
image: aydoscom.png
image: aydoscom.jpg
title: aydos.com
---
content/showcase/barricade.md
+1 -1
View File
@@ -7,7 +7,7 @@ sitelink: https://barricade.io
tags:
- company
- security
image: barricade.png
image: barricade.jpg
title: Barricade
---
content/showcase/bepsays.md
+1 -1
View File
@@ -9,7 +9,7 @@ sourcelink: "https://github.com/bep/bepsays.com"
tags:
- personal
- blog
image: bepsays.png
image: bepsays.jpg
title: bepsays.com
---
content/showcase/camunda-blog.md
+1 -1
View File
@@ -9,7 +9,7 @@ sourcelink: https://github.com/camunda/blog.camunda.org
tags:
- company
- blog
image: camunda-blog.png
image: camunda-blog.jpg
title: Camunda Blog
---
content/showcase/camunda-docs.md
+1 -1
View File
@@ -9,7 +9,7 @@ sourcelink: https://github.com/camunda/camunda-docs-theme
tags:
- company
- documentation
image: camunda-docs.png
image: camunda-docs.jpg
title: Camunda Docs
---
content/showcase/cdnoverview.md
+1 -1
View File
@@ -8,7 +8,7 @@ tags:
- bootstrap
- portfolio
- tech
image: cdnoverview.png
image: cdnoverview.jpg
title: cdnoverview.com
---
content/showcase/chinese-grammar.md
+1 -1
View File
@@ -7,6 +7,6 @@ sourcelink: https://github.com/hughgrigg/chineseboost-articles
tags:
- learning
- education
image: chinese-grammar.png
image: chinese-grammar.jpg
title: Chinese Grammar
---
content/showcase/chipsncookies.md
+1 -1
View File
@@ -9,7 +9,7 @@ sourcelink: https://github.com/SamuelDebruyn/chipsncookies-site
tags:
- personal
- blog
image: chipsncookies.png
image: chipsncookies.jpg
title: Chips 'n' Cookies
---
content/showcase/christianmendoza.md
+1 -1
View File
@@ -7,6 +7,6 @@ sitelink: https://christianmendoza.me/
tags:
- personal
- profile
image: christianmendoza.png
image: christianmendoza.jpg
title: christianmendoza.me
---
content/showcase/cinegyopen.md
+1 -1
View File
@@ -7,6 +7,6 @@ sitelink: https://open.cinegy.com/
sourcelink:
tags:
- documentation
image: cinegyopen.png
image: cinegyopen.jpg
title: Cinegy Open
---
content/showcase/clearhaus.md
+1 -1
View File
@@ -9,6 +9,6 @@ tags:
- fintech
- payments
- acquirer
image: clearhaus.png
image: clearhaus.jpg
title: Clearhaus
---
content/showcase/coding-journal.md
+1 -1
View File
@@ -9,6 +9,6 @@ sourcelink: https://github.com/igorkulman/coding-journal
tags:
- blog
- portfolio
image: codingjournal.png
image: codingjournal.jpg
title: Coding Journal
---
content/showcase/ctlcompiled.md
+1 -1
View File
@@ -8,7 +8,7 @@ tags:
- edtech
- technology
- blog
image: ctlcompiled.png
image: ctlcompiled.jpg
title: CompilED at CTL
---
content/showcase/davidrallen.md
+1 -1
View File
@@ -9,7 +9,7 @@ tags:
- personal
- blog
- tech
image: davidrallen.png
image: davidrallen.jpg
title: David Allen
---
content/showcase/davidyates.md
+1 -1
View File
@@ -7,7 +7,7 @@ sitelink: https://davidyat.es/
tags:
- personal
- blog
image: davidyates.png
image: davidyates.jpg
title: David Yates
---
content/showcase/dmitriid.com.md
+1 -1
View File
@@ -8,7 +8,7 @@ sourcelink: https://github.com/dmitriid/dmitriid.com
tags:
- personal
- blog
image: dmitriid.com.png
image: dmitriid.com.jpg
title: dmitriid.com
---
content/showcase/esolia-com.md
+1 -1
View File
@@ -11,6 +11,6 @@ tags:
- esolia
- rickcogley
- japan
image: esolia_com.png
image: esolia_com.jpg
title: eSolia.com
---
content/showcase/esolia-pro.md
+1 -1
View File
@@ -11,6 +11,6 @@ tags:
- esolia
- rickcogley
- japan
image: esolia_pro.png
image: esolia_pro.jpg
title: eSolia.pro
---
content/showcase/eurie.md
+1 -1
View File
@@ -6,6 +6,6 @@ licenseLink: ""
sitelink: https://docs.eurie.io
tags:
- documentation
image: docs.eurie.io.png
image: docs.eurie.io.jpg
title: eurie Desk docs
---
content/showcase/fale.md
+1 -1
View File
@@ -9,7 +9,7 @@ sourcelink: https://github.com/fale/fale.io
tags:
- personal
- blog
image: fale.png
image: fale.jpg
title: fale.io
---
content/showcase/fixatom.md
+1 -1
View File
@@ -7,7 +7,7 @@ sitelink: https://fixatom.com/
tags:
- personal
- blog
image: fixatom.png
image: fixatom.jpg
title: Atom
---
content/showcase/fxsitecompat.md
+1 -1
View File
@@ -10,7 +10,7 @@ tags:
- community
- documentation
- translation
image: fxsitecompat.png
image: fxsitecompat.jpg
title: Firefox Site Compatibility
---
content/showcase/gntech.md
+1 -1
View File
@@ -10,6 +10,6 @@ tags:
- projects
- music
- drawings
image: gntech.png
image: gntech.jpg
title: gntech.se
---
content/showcase/goin5minutes.md
+1 -1
View File
@@ -8,6 +8,6 @@ sitelink: http://www.goin5minutes.com/
sourcelink: https://github.com/arschles/go-in-5-minutes/tree/master/www
tags:
- screencasts
image: goin5minutes.png
image: goin5minutes.jpg
title: Go in 5 minutes
---
content/showcase/h10n.me.md
+1 -1
View File
@@ -6,6 +6,6 @@ sourcelink: https://github.com/zerok/h10n.me
tags:
- personal
- profile
image: h10n.me.png
image: h10n.me.jpg
title: h10n.me
---
content/showcase/jamescampbell.md
+1 -1
View File
@@ -8,7 +8,7 @@ sourcelink: https://github.com/jamesacampbell/causes-and-effects-hugo
tags:
- personal
- blog
image: jamescampbell.png
image: jamescampbell.jpg
title: jamescampbell.us
---
content/showcase/jorgennilsson.md
+1 -1
View File
@@ -7,6 +7,6 @@ sitelink: http://jorgennilsson.com/
tags:
- personal
- blog
image: jorgennilsson.png
image: jorgennilsson.jpg
title: jorgennilsson.com
---
content/showcase/klingt-net.md
+1 -1
View File
@@ -9,7 +9,7 @@ tags:
- personal
- blog
- programming
image: klingt-net.png
image: klingt-net.jpg
title: klingt net
---
content/showcase/leowkahman.md
+1 -1
View File
@@ -7,6 +7,6 @@ sitelink: https://www.leowkahman.com/
tags:
- personal
- blog
image: leowkahman.png
image: leowkahman.jpg
title: Leow Kah Man - Tech Blog
---
content/showcase/losslesslife.md
+1 -1
View File
@@ -10,6 +10,6 @@ tags:
- reviews
- education
- audiophile
image: losslesslife.png
image: losslesslife.jpg
title: LosslessLife
---
content/showcase/mayan-edms.md
+1 -1
View File
@@ -8,7 +8,7 @@ sourcelink: https://gitlab.com/mayan-edms/website
tags:
- paperless
- floss
image: mayan-edms.png
image: mayan-edms.jpg
title: Mayan EDMS
---
content/showcase/mongodb-eng-journal.md
+1 -1
View File
@@ -7,7 +7,7 @@ sitelink: http://engineering.mongodb.com/
tags:
- engineering
- blog
image: mongodb-eng.png
image: mongodb-eng.jpg
title: The Mongodb Engineering Journal
---
content/showcase/mtbhomer.md
+1 -1
View File
@@ -9,6 +9,6 @@ tags:
- personal
- portfolio
- design
image: mtbhomer.png
image: mtbhomer.jpg
title: mtbhomer.com
---
content/showcase/ninjaducks.in.md
+1 -1
View File
@@ -9,6 +9,6 @@ sourcelink: https://github.com/shivanshuag/shivanshuag.github.io/tree/new
tags:
- personal
- blog
image: ninjaducks.png
image: ninjaducks.jpg
title: ninjaducks.in
---
content/showcase/nodesk.md
+1 -1
View File
@@ -6,6 +6,6 @@ sitelink: http://nodesk.co/
tags:
- digital nomad
- web
image: nodesk.png
image: nodesk.jpg
title: nodesk.co
---
content/showcase/novelist-xyz.md
+1 -1
View File
@@ -8,6 +8,6 @@ sourcelink: https://github.com/peterychuang/peterychuang.github.io/tree/source
tags:
- personal
- blog
image: novelist-xyz.png
image: novelist-xyz.jpg
title: Peter Y. Chuang
---
content/showcase/promotive.md
+1 -1
View File
@@ -10,6 +10,6 @@ tags:
- spanish
- event management
- bootstrap
image: promotive.png
image: promotive.jpg
title: Promotive
---
content/showcase/rahulrai.md
+1 -1
View File
@@ -8,6 +8,6 @@ sourcelink: https://github.com/moonytheloony/Blog-Web
tags:
- personal
- blog
image: rahulrai_in.png
image: rahulrai_in.jpg
title: My Take on Cloud
---
content/showcase/rakutentech.md
+1 -1
View File
@@ -8,7 +8,7 @@ sitelink: http://techblog.rakuten.co.jp/
tags:
- company
- blog
image: rakutentech.png
image: rakutentech.jpg
title: Rakuten Tech Blog
---
content/showcase/rdegges.md
+1 -1
View File
@@ -8,7 +8,7 @@ sourcelink: https://github.com/rdegges/rdegges-www
tags:
- personal
- blog
image: rdegges.png
image: rdegges.jpg
title: Randall Degges
---
content/showcase/readtext.md
+1 -1
View File
@@ -6,7 +6,7 @@ sitelink: http://readtext.org/
tags:
- textfiles
- reading
image: readtext.png
image: readtext.jpg
title: ReadText
---
content/showcase/richardsumilang.md
+1 -1
View File
@@ -12,6 +12,6 @@ tags:
- technical
- electronics
- reviews
image: richardsumilang.png
image: richardsumilang.jpg
title: Richard Sumilang - Top Secret Labs
---
content/showcase/ridingbytes.md
+1 -1
View File
@@ -10,7 +10,7 @@ tags:
- website
- blog
- tech
image: ridingbytes.png
image: ridingbytes.jpg
title: RIDING BYTES
---
content/showcase/scottcwilson.md
+1 -1
View File
@@ -9,7 +9,7 @@ sourcelink: https://github.com/scottcwilson/hugosite
tags:
- personal
- blog
image: scottcwilson.png
image: scottcwilson.jpg
title: scottcwilson.com
---
content/showcase/shapeshed.md
+1 -1
View File
@@ -8,7 +8,7 @@ sourcelink: https://github.com/shapeshed/shapeshed.com
tags:
- personal
- blog
image: shapeshed.png
image: shapeshed.jpg
title: shapeshed.com
---
content/showcase/shelan.md
+1 -1
View File
@@ -9,6 +9,6 @@ sourcelink: https://github.com/shelan/my-hugo-site
tags:
- personal
- blog
image: shelan.png
image: shelan.jpg
title: shelan.org
---
content/showcase/softinio.md
+1 -1
View File
@@ -10,6 +10,6 @@ tags:
- personal
- technical
- blog
image: softinio.png
image: softinio.jpg
title: Salar Rahmanian
---
content/showcase/steambap.md
+1 -1
View File
@@ -8,6 +8,6 @@ sourcelink: https://github.com/steambap/weilinshi.org
tags:
- personal
- blog
image: steambap.png
image: steambap.jpg
title: weilinshi
---
content/showcase/stefano.chiodino.md
+1 -1
View File
@@ -8,7 +8,7 @@ sourcelink: https://github.com/Draga/go-web
tags:
- personal
- blog
image: stefano.chiodino.png
image: stefano.chiodino.jpg
title: stefano.chiodino.uk
---
content/showcase/stou.md
+1 -1
View File
@@ -9,7 +9,7 @@ sourcelink: "https://github.com/stou/stou.github.io"
tags:
- personal
- blog
image: stou.png
image: stou.jpg
title: stou.dk
---
content/showcase/szymonkatra.md
+1 -1
View File
@@ -9,7 +9,7 @@ sourcelink: https://github.com/SzymonKatra/SzymonKatra.github.io/tree/master/hug
tags:
- personal
- blog
image: szymonkatra.png
image: szymonkatra.jpg
title: szymonkatra.github.io
---
content/showcase/thecodeking.md
+1 -1
View File
@@ -7,7 +7,7 @@ sitelink: http://thecodeking.co.uk
tags:
- personal
- blog
image: thecodeking.png
image: thecodeking.jpg
title: thecodeking
---
content/showcase/thehome.md
+1 -1
View File
@@ -9,7 +9,7 @@ sourcelink: "https://github.com/tomhelmer/website-source"
tags:
- personal
- blog
image: thehome.png
image: thehome.jpg
title: thehome.dk
---
content/showcase/upbeat.md
+1 -1
View File
@@ -8,6 +8,6 @@ sourcelink:
tags:
- personal
- blog
image: upbeat.png
image: upbeat.jpg
title: upbeat
---
content/showcase/vamp.md
+1 -1
View File
@@ -10,7 +10,7 @@ tags:
- documentation
- company
- api
image: vamp_landingpage.png
image: vamp_landingpage.jpg
title: Vamp.io
---
content/showcase/viglug.org.md
+1 -1
View File
@@ -9,7 +9,7 @@ tags:
- tech
- linux
- user group
image: viglug.png
image: viglug.jpg
title: Viglug.org
---
content/showcase/yslow-rules.md
+1 -1
View File
@@ -10,7 +10,7 @@ tags:
- community
- documentation
- translation
image: yslow-rules.png
image: yslow-rules.jpg
title: YSlow Rules
---
content/showcase/ysqi.md
+1 -1
View File
@@ -8,6 +8,6 @@ sourcelink: https://github.com/ysqi/yushuangqi.com/
tags:
- personal
- blog
image: ysqi-blog.png
image: ysqi-blog.jpg
title: yushuangqi-blog
---
content/showcase/yulinling.net.md
+1 -1
View File
@@ -9,6 +9,6 @@ sourcelink: https://bitbucket.org/lynxiayel/yulinling_source_public
tags:
- blog
- documentation
image: yulinling.png
image: yulinling.jpg
title: <span lang="zh-CN">语林灵</span> (Yulinling)
---
content/templates/base.md
+33 -19
View File
@@ -12,34 +12,47 @@ weight: 20
draft: false
aliases: [/templates/blocks/,/templates/base-templates-and-blocks/]
toc: true
wip: true
---
Go 1.6 includes a powerful new keyword, `block`. This construct allows you to define the outer shell of your pages' one or more master template(s) and then fill in or override portions as necessary.
## Base Template Lookup Order
This is the order Hugo searches for your base template:
The [lookup order][lookup] for base templates is as follows:
1. `/layouts/<CURRENTPATH>/<TEMPLATENAME>-baseof.html`
2. `/layouts/<CURRENTPATH>/baseof.html`
3. `/layouts/_default/<TEMPLATENAME>-baseof.html`
4. `/layouts/_default/baseof.html`
1. `/layouts/section/<TYPE>-baseof.html`
2. `/themes/<THEME>/layouts/section/<TYPE>-baseof.html`
3. `/layouts/<TYPE>/baseof.html`
4. `/themes/<THEME>/layouts/<TYPE>/baseof.html`
5. `/layouts/section/baseof.html`
6. `/themes/<THEME>/layouts/section/baseof.html`
7. `/layouts/_default/post-baseof.html`
8. `/themes/<THEME>/layouts/_default/post-baseof.html`
9. `/layouts/_default/baseof.html`
10. `/themes/<THEME>/layouts/_default/baseof.html`
As an example, let's assume your site is using the theme when rendering the section list for the section `post`. Hugo picks the `section/post.html` as the template and this template has a `define` section that indicates it needs a base template. This is then the lookup order:
Variables are denoted by capitalized text set within `<>`. Note that Hugo's default behavior is for `type` to inherit from `section` unless otherwise specified.
### Example Base Template Lookup Order
As an example, let's assume your site is using a theme called "mytheme" when rendering the section list for a `post` section. Hugo picks `layout/section/post.html` as the template for [rendering the section][]. The `{{define}}` block in this template tells Hugo that the template is an extension of a base template.
Here is the lookup order for the `post` base template:
1. `/layouts/section/post-baseof.html`
2. `/themes/<THEME>/layouts/section/post-baseof.html`
3. `/layouts/section/baseof.html`
4. `/themes/<THEME>/layouts/section/baseof.html`
5. `/layouts/_default/post-baseof.html`
6. `/themes/<THEME>/layouts/_default/post-baseof.html`
7. `/layouts/_default/baseof.html`
8. `/themes/<THEME>/layouts/_default/baseof.html`
2. `/themes/mytheme/layouts/section/post-baseof.html`
3. `/layouts/post/baseof.html`
4. `/themes/mytheme/layouts/post/baseof.html`
5. `/layouts/section/baseof.html`
6. `/themes/mytheme/layouts/section/baseof.html`
7. `/layouts/_default/post-baseof.html`
8. `/themes/mytheme/layouts/_default/post-baseof.html`
9. `/layouts/_default/baseof.html`
10. `/themes/mytheme/layouts/_default/baseof.html`
## Defining the Base Template
The following defines a simple base template at `_default/baseof.html`). As a default template, it is the shell from which all our pages will start unless a more specific `*baseof.html` is defined.
The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will be rendered unless you specify another `*baseof.html` closer to the beginning of the lookup order..
{{% code file="layouts/_default/baseof.html" download="baseof.html" %}}
```html
@@ -54,7 +67,6 @@ The following defines a simple base template at `_default/baseof.html`). As a de
</head>
<body>
<!-- Code that all your templates share, like a header -->
{{ block "main" . }}
<!-- The part of the page that begins to differ between templates -->
{{ end }}
@@ -84,8 +96,8 @@ From the above base template, you can define a [default list template][hugolists
```
{{% /code %}}
{{% note "No Go Context \"Dot\" in Block Definitions" %}}
When using the `define` keyword, you do *not* need to use Go templates context reference (i.e., 'The Dot"). (Read more on ["The Dot" in the Go Template Primer](/templates/go-templates/).)
{{% note "No Go Context \"the dot\" in Block Definitions" %}}
When using the `define` keyword, you do *not* need to use Go templates context reference (i.e., "the dot"). (Read more on ["the dot" in the Go Template Primer](/templates/go-templates/).)
{{% /note %}}
This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a `"title"` block, so the contents from our base template remain unchanged in lists.
@@ -94,7 +106,7 @@ This replaces the contents of our (basically empty) "main" block with something
Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example:
```html
<!-- Harmless comment..that will break your layout at build -->
<!-- Seemingly harmless HTML comment..that will break your layout at build -->
{{ define "main" }}
...your code here
{{ end }}
@@ -118,4 +130,6 @@ The following shows how you can override both the `"main"` and `"title"` block a
{{% /code %}}
[hugolists]: /templates/lists
[lookup]: /templates/lookup-order/
[rendering the section]: /templates/section-templates/
[singletemplate]: /templates/single-page-templates/
content/templates/data-templates.md
+1 -1
View File
@@ -1,7 +1,7 @@
---
title: Data Templates
linktitle:
description: In addition to the Hugo's many built-in variables, you can specify your own custom data in templates or shortcodes that pull from both local and dynamic sources.
description: In addition to Hugo's built-in variables, you can specify your own custom data in templates or shortcodes that pull from both local and dynamic sources.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
content/templates/homepage.md
+7 -7
View File
@@ -25,18 +25,18 @@ The homepage template is the *only* required template for building a site and th
The [lookup order][lookup] for the homepage template is as follows:
* `/layouts/index.html`
* `/layouts/\_default/list.html`
* `/layouts/\_default/single.html`
* `/themes/<THEME>/layouts/index.html`
* `/themes/<THEME>/layouts/_default/list.html`
* `/themes/<THEME>/layouts/_default/single.html`
1. `/layouts/index.html`
2. `/layouts/\_default/list.html`
3. `/layouts/\_default/single.html`
4. `/themes/<THEME>/layouts/index.html`
5. `/themes/<THEME>/layouts/_default/list.html`
6. `/themes/<THEME>/layouts/_default/single.html`
## `.Data.Pages` on the Homepage
In addition to the standard [page variables][pagevars], the homepage template has access to *all* site content via `.Data.Pages`.
`.Data.Pages` usually refers to the list of pages available within a given section or taxonomy. However, since `index.html` is the homepage of your Hugo project (i.e., in essence, the top of the master section), `Data.Pages` for `layouts/index.html` is interchangeable with `.Site.Pages` when written on the homepage template.
`.Data.Pages` usually refers to the list of pages available within a given section or taxonomy. However, since `index.html` is the homepage of your Hugo project (i.e., in essence, the top or master section), `Data.Pages` for `layouts/index.html` is interchangeable with `.Site.Pages` when written on the homepage template.
Note that a homepage can also have a content file with front matter. This content file lives at `content/_index.md`. See [Content Organization][contentorg] for more information.
content/templates/lists.md
+6 -9
View File
@@ -1,6 +1,6 @@
---
title: Introduction to Lists in Hugo
linktitle: Hugo Lists
title: Introduction to Hugo Lists
linktitle: Hugo Lists Introduction
description: Lists have a specific meaning and usage in Hugo when it comes to rendering your site homepage, section page, taxonomy list, or taxonomy terms list.
date: 2017-02-01
publishdate: 2017-02-01
@@ -16,7 +16,7 @@ wip: true
## What is a List Page Template?
A list page template is a template used to render multiple pieces of content in a single HTML page (with the exception of the homepage, which has a [dedicated template][homepage]).
A list page template is a template used to render multiple pieces of content in a single HTML page. The exception to this rule is the homepage, which is still a list but has its own [dedicated template][homepage]).
Hugo uses the term *list* in its truest sense; i.e. a sequential arrangement of material, especially in alphabetical or numerical order. Hugo uses list templates on any output HTML page where content is traditionally listed:
@@ -45,16 +45,13 @@ Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][taxte
### Taxonomy RSS
A Taxonomy’s RSS will be rendered at /`PLURAL`/`TERM`/index.xml (e.g.&nbsp;http://spf13.com/topics/golang/index.xml)
A Taxonomy’s RSS will be rendered at `/<PLURAL>/<TERM>/index.xml` (e.g.&nbsp;http://spf13.com/topics/golang/index.xml).
{{% note %}}
Hugo ships with its own [RSS 2.0][] template. In most cases this will
be sufficient, and an RSS template will not need to be provided by the
user.
Most use cases will find that the [RSS 2.0][] template that ships with Hugo is sufficient for their needs.
{{% /note %}}
Hugo provides the ability for you to define any RSS type you wish, and
can have different RSS files for each section and taxonomy.
Hugo provides the ability for you to define any RSS type you wish. You can can have different RSS files for each section and taxonomy:
1. `/layouts/taxonomy/<SINGULAR>.rss.xml`
1. `/layouts/_default/rss.xml`
content/templates/lookup-order.md
+141 -7
View File
@@ -1,6 +1,6 @@
---
title: Template Lookup Order
linktitle: Template Lookup Order
title: Hugo's Lookup Order
linktitle: Lookup Order
description: The lookup order is a prioritized list used by Hugo as it traverses your files looking for the appropriate template to render your content.
godocref:
date: 2017-02-01
@@ -11,22 +11,153 @@ tags: [lookup,fundamentals]
weight: 15
draft: false
aliases: [/templates/lookup/]
wip: true
toc: true
---
Before creating your templates, it's important to know how Hugo looks for files within your project's [directory structure][].
Hugo uses a prioritized list called the **lookup order** as it traverses your files *looking* for the appropriate template to render your content.
Hugo uses a prioritized list called the **lookup order** as it traverses your `layouts` folder in your Hugo project *looking* for the appropriate template to render your content.
The template lookup order is an inverted cascade: if template A isn’t present or specified, Hugo will look to template B. If template B isn't present or specified, Hugo will look for template C...and so on until it reaches the `layouts/_default/` directory for your project, or in the case of themes, `themes/<THEME>/layouts/_default/`. In many ways, the lookup order is similar to the [control mechanism of a switch statement (i.e. without fallthrough)][switch] seen in many programming languages.
The template lookup order is an inverted cascade: if template A isn’t present or specified, Hugo will look to template B. If template B isn't present or specified, Hugo will look for template C...and so on until it reaches the `_default/` directory for your project or theme. In many ways, the lookup order is similar to the control mechanism of a [switch statement (i.e. without fallthrough)][switch] seen in many programming languages.
The power of the lookup order is that it enables you to craft specific layouts as needed without creating more templating than necessary, thereby keeping your templating [DRY][].
The power of the lookup order is that it enables you to craft specific layouts and keep your templating [DRY][].
{{% note %}}
Most Hugo websites will only need the default template files at the end of the lookup order (i.e. `_default/*.html`).
{{% /note %}}
See examples of the lookup order for each of the Hugo template types:
## Single Page Template Lookup Examples
The lookup order is best illustrated by example. The following shows you the process Hugo uses for finding the appropriate template to render your [single content][], but the concept holds true for all templates in Hugo.
1. The project is using the theme `mytheme`, which would be specified as `theme: mytheme` or `theme = "mytheme` in the project's [`config.toml` or `config.yaml`][config], respectively.
2. The layouts and content directories for the project are as follows:
```bash
.
├── content
│   ├── events
│   │   ├── _index.md
│   │   └── my-first-event.md
│   └── posts
│   ├── my-first-post.md
│   └── my-second-post.md
├── layouts
│   ├── _default
│   │   └── single.html
│   ├── posts
│   │   └── single.html
│   └── reviews
│   └── reviewarticle.html
└── themes
└── mytheme
└── layouts
├── _default
│   ├── list.html
│   └── single.html
└── posts
├── list.html
└── single.html
```
Now we can look at the front matter for the three single-page content (i.e.`.md`) files.
{{% note %}}
You may notice there are four markdown files but we are only going to review three for the *single* page lookup order. `_index.md` may seem like a single page of content but is actually a specific `kind` in Hugo. Whereas `my-first-post.md`, `my-second-post.md`, and `my-first-event.md` are all of kind `page`, all `_index.md` files in a Hugo project are used to add content and front matter to list pages. `events/_index.md` will render according to its [section template](/templates/section-templates/) and respective lookup order.
{{% /note %}}
### Example: `my-first-post.md`
{{% code file="content/posts/my-first-post.md" copy="false" %}}
```yaml
---
title: My First Post
date: 2017-02-19
description: This is my first post.
---
```
{{% /code %}}
When it comes time for Hugo to render the content to the page, it will go through the single page template lookup order until it finds what it needs for `my-first-post.md`:
1. ~~`/layouts/UNSPECIFIED/UNSPECIFIED.html`~~
2. ~~`/layouts/posts/UNSPECIFIED.html`~~
3. ~~`/layouts/UNSPECIFIED/single.html`~~
4. <span class="yes">`/layouts/posts/single.html`</span>
<br><span class="break">BREAK</span>
5. <span class="na">`/layouts/_default/single.html`</span>
6. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
7. <span class="na">`/themes/<THEME>/layouts/posts/UNSPECIFIED.html`</span>
8. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/single.html`</span>
9. <span class="na">`/themes/<THEME>/layouts/posts/single.html`</span>
10. <span class="na">`/themes/<THEME>/layouts/_default/single.html`</span>
Notice the term `UNSPECIFIED` rather than `UNDEFINED`. If you don't tell Hugo the specific type and layout, it makes assumptions based on sane defaults. `my-first-post.md` does not specify a content `type` in its front matter. Therefore, Hugo assumes the content `type` and `section` (i.e. `posts`, which is defined by file location) are one in the same. ([Read more on sections][sections].)
`my-first-post.md` also does not specify a `layout` in its front matter. Therefore, Hugo assumes that `my-first-post.md`, which is of type `page` and a *single* piece of content, should default to the next occurrence of a `single.html` template in the lookup (#4).
### Example: `my-second-post.md`
{{% code file="content/posts/my-second-post.md" copy="false" %}}
```yaml
---
title: My Second Post
date: 2017-02-21
description: This is my second post.
type: review
layout: reviewarticle
---
```
{{% /code %}}
Here is the way Hugo's traverses the single-page lookup order for `my-second-post.md`:
1. <span class="yes">`/layouts/review/reviewarticle.html`</span>
<br><span class="break">BREAK</span>
2. <span class="na">`/layouts/posts/reviewarticle.html`</span>
3. <span class="na">`/layouts/review/single.html`</span>
4. <span class="na">`/layouts/posts/single.html`</span>
5. <span class="na">`/layouts/_default/single.html`</span>
6. <span class="na">`/themes/<THEME>/layouts/review/reviewarticle.html`</span>
7. <span class="na">`/themes/<THEME>/layouts/posts/reviewarticle.html`</span>
8. <span class="na">`/themes/<THEME>/layouts/review/single.html`</span>
9. <span class="na">`/themes/<THEME>/layouts/posts/single.html`</span>
10. <span class="na">`/themes/<THEME>/layouts/_default/single.html`</span>
The front matter in `my-second-post.md` specifies the content `type` (i.e. `review`) as well as the `layout` (i.e. `reviewarticle`). Hugo finds the layout it needs at the top level of the lookup (#1) and does not continue to search through the other templates.
{{% note "Type and not Types" %}}
Notice that the directory for the template for `my-second-post.md` is `review` and not `reviews`. This is because *type is always singular when defined in front matter*.
{{% /note%}}
### Example: `my-first-event.md`
{{% code file="content/events/my-first-event.md" copy="false" %}}
```yaml
---
title: My First
date: 2017-02-21
description: This is an upcoming event..
---
```
{{% /code %}}
Here is the way Hugo traverses the single-page lookup order for `my-first-event.md`:
1. ~~`/layouts/UNSPECIFIED/UNSPECIFIED.html`~~
2. ~~`/layouts/events/UNSPECIFIED.html`~~
3. ~~`/layouts/UNSPECIFIED/single.html`~~
4. ~~`/layouts/events/single.html`~~
5. <span class="yes">`/layouts/_default/single.html`</span>
<br><span class="break">BREAK</span>
6. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
7. <span class="na">`/themes/<THEME>/layouts/events/UNSPECIFIED.html`</span>
8. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/single.html`</span>
9. <span class="na">`/themes/<THEME>/layouts/events/single.html`</span>
10. <span class="na">`/themes/<THEME>/layouts/_default/single.html`</span>
The respective lookup order for each of Hugo's templates has been defined throughout the Hugo docs:
* [Homepage Template][home]
* [Base Templates][base]
@@ -37,11 +168,14 @@ See examples of the lookup order for each of the Hugo template types:
* [RSS Templates][rsslookup]
[base]: /templates/base/#base-template-lookup-order
[config]: /getting-started/configuration/
[directory structure]: /getting-started/directory-structure/
[DRY]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
[home]: /templates/homepage/#homepage-template-lookup-order
[rsslookup]: /templates/rss/#rss-template-lookup-order
[sections]: /content-management/sections/
[sectionlookup]: /templates/section-templates/#section-template-lookup-order
[single content]: /templates/single-page-templates/
[singlelookup]: templates/single-page-templates/#single-page-template-lookup-order
[switch]: https://en.wikipedia.org/wiki/Switch_statement#Fallthrough
[taxonomylookup]: /templates/taxonomy-templates/#taxonomy-list-template-lookup-order
content/templates/rendering-lists.md → content/templates/ordering-and-grouping.md
+7 -5
View File
@@ -1,7 +1,7 @@
---
title: Ordering and Grouping Lists
linktitle: Rendering Hugo Lists
description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site, but
title: Ordering and Grouping Hugo Lists
linktitle: List Ordering and Grouping
description: You can group or order your content in both your templating and content front matter.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
@@ -14,7 +14,6 @@ toc: true
wip: true
---
## Understanding `.Data.Pages`
From this image, we can assume that the "homepage" for Section A---presumably, `/section-a/index.html`---is going to list the content pages 1,2,3. In this way, pages 1,2,3 are *data* made available to the template that renders to the .
@@ -46,7 +45,7 @@ This content template is used for [spf13.com](http://spf13.com/). It makes use o
### Example Taxonomy Template
This content template is used for [spf13.com](http://spf13.com/). It makes use of [partial templates](/templates/partials/). All examples use a [view](/templates/views/) called either "li" or "summary" which this example site defined.
The following taxonomy template uses a [content view template][views] called either "li" or "summary" which this example site defined.
{{% code file="layouts/_default/taxonomies.html" download="taxonomies.html" %}}
```html
@@ -379,3 +378,6 @@ Using `first` and `where` together can be very powerful:
{{ end }}
```
{{% /code %}}
[views]: /templates/views/
content/templates/robots.md
+7 -3
View File
@@ -16,7 +16,7 @@ wip: true
Hugo can generate a customized [robots.txt][robots] in the same way as any other template.
To enable creating your robots.txt as a template, set the `enableRobotsTXT` value to `true` in your [project's configuration file][config]. By default, this option generates a robots.txt with the following content, which tells search engines that they are allowed to crawl everything:
To create your robots.txt as a template, first set the `enableRobotsTXT` value to `true` in your [configuration file][config]. By default, this option generates a robots.txt with the following content, which tells search engines that they are allowed to crawl everything:
```http
User-agent: *
@@ -29,9 +29,13 @@ The [lookup order][lookup] for the `robots.txt` template is as follows:
* `/layouts/robots.txt`
* `/themes/<THEME>/layout/robots.txt`
## Robots. txt Template Example
{{% note %}}
If you do not want Hugo to create a default `robots.txt` or leverage the `robots.txt` template, you can hand code your own and place the file in `static`. Remember that everything in the [static directory](/getting-started/directory-structure/) is copied over as-is when Hugo builds your site.
{{% /note %}}
The following is an example`robots.txt` layout:
## Robots.txt Template Example
The following is an example `robots.txt` layout:
{{% code file="layouts/robots.txt" download="robots.txt" %}}
```http
content/templates/section-templates.md
+33 -14
View File
@@ -1,6 +1,6 @@
---
title: Section Page Templates
linktitle: Section Page Templates
linktitle: Section Templates
description: Templates used for section pages are lists and therefore have all the variables and methods available to list pages.
date: 2017-02-01
publishdate: 2017-02-01
@@ -11,7 +11,6 @@ weight: 40
draft: false
aliases: [/templates/sections/]
toc: true
wip: true
---
Templates used for section pages are *lists* and therefore have all the variables and methods available to [list pages][lists].
@@ -22,16 +21,16 @@ To effectively leverage section page templates, you should first understand Hugo
## Section Template Lookup Order
The [lookup order][lookup] for section pages is as follows:
The [lookup order][lookup] for section templates is as follows:
1. `/layouts/section/<SECTION>.html`
2. `/layouts/<SECTION>/list.html`
2. `/layouts/_default/section.html`
3. `/layouts/_default/list.html`
4. `/themes/<THEME>/layouts/section/<SECTION>.html`
5. `/themes/<THEME>/layouts/<SECTION>/list.html`
5. `/themes/<THEME>/layouts/_default/section.html`
6. `/themes/<THEME>/layouts/_default/list.html`
3. `/layouts/_default/section.html`
4. `/layouts/_default/list.html`
5. `/themes/<THEME>/layouts/section/<SECTION>.html`
6. `/themes/<THEME>/layouts/<SECTION>/list.html`
7. `/themes/<THEME>/layouts/_default/section.html`
8. `/themes/<THEME>/layouts/_default/list.html`
## `.Site.GetPage` with Sections
@@ -40,7 +39,7 @@ Every `Page` in Hugo has a `.Kind` attribute. `Kind` can easily be combined with
The [`.GetPage` function][getpage] looks up an index page of a given `Kind` and `path`.
{{% note %}}
`.GetPage` is only supported in section page templates but *may* be supported in [single page templates](/templates/single-page-templates/) in the future.
`.GetPage` is not currently supported to grab single content files but *may* be supported in the future.
{{% /note %}}
You can call `.Site.GetPage` with two arguments: `kind` and `kind value`.
@@ -52,6 +51,29 @@ These are the valid values for 'kind':
3. `taxonomy`
4. `taxonomyTerm`
## Example: Creating a Default Section Template
{{% code file="layouts/_default/section.html" download="section.html" %}}
```html
{{ define "main" }}
<main>
{{ .Content }}
<ul class="contents">
{{ range .Paginator.Pages }}
<li>{{.Title}}
<div>
{{ partial "summary.html" . }}
</div>
</li>
{{ end }}
</ul>
{{ partial "pagination.html" . }}
</main>
{{ end }}
```
{{% /code %}}
### Example: Using `.Site.GetPage`
The `.Site.GetPage` example that follows assumes the following project directory structure:
@@ -87,15 +109,12 @@ If we try the same code with the `events` section, however, Hugo will default to
<h1>{{ with .Site.GetPage "section" "events" }}{{ .Title }}{{ end }}</h1>
```
Which then returns
Which then returns the following:
```html
<h1>Events</h1>
```
## Nested Sections
**Content forthcoming**
[contentorg]: /content-management/organization/
[getpage]: /functions/getpage/
content/templates/single-page-templates.md
+2 -133
View File
@@ -22,147 +22,16 @@ You can specify `type` (i.e., [content type][]) and `layout` in a single content
Hugo assumes your content section and content type are the same unless you tell Hugo otherwise by providing a `type` directly in the front matter of a content file. This is why #1 and #3 come before #2 and #4, respectively, in the following lookup order. Values in angle brackets (`<>`) are variable.
1. `/layouts/<TYPE>/<LAYOUT>.html`
2. `/layouts/<SECTION>/<LAYOUT>.html`
2. `/layouts/<SECTION>>/<LAYOUT>.html`
3. `/layouts/<TYPE>/single.html`
4. `/layouts/<SECTION>/single.html`
5. `/layouts/_default/single.html`
6. `/themes/<THEME>/layouts/<TYPE>/<LAYOUT.html`
7. `/themes/<THEME>/layouts/<SECTION/LAYOUT.html`
7. `/themes/<THEME>/layouts/<SECTION>/LAYOUT.html`
8. `/themes/<THEME>/layouts/<TYPE>/single.html`
9. `/themes/<THEME>/layouts/<SECTION>/single.html`
10. `/themes/<THEME>/layouts/_default/single.html`
## Single Page Template Lookup Examples
The following examples assume two things:
1. The project is using the theme `mytheme`, which would be specified as `theme: mytheme` or `theme = "mytheme` in the project's [`config.toml` or `config.yaml`][config], respectively.
2. The layouts and content directories for the project are as follows:
```bash
.
├── content
│   ├── events
│   │   ├── _index.md
│   │   └── my-first-event.md
│   └── posts
│   ├── my-first-post.md
│   └── my-second-post.md
├── layouts
│   ├── _default
│   │   └── single.html
│   ├── posts
│   │   └── single.html
│   └── reviews
│   └── reviewarticle.html
└── themes
└── mytheme
└── layouts
├── _default
│   ├── list.html
│   └── single.html
└── posts
├── list.html
└── single.html
```
Now we can look at the front matter for the three single-page content (i.e.`.md`) files.
{{% note "Three Content Pages but *Four* Markdown Files?" %}}
`_index.md` may seem like a single page of content but is actually a specific `kind` in Hugo. Whereas `my-first-post.md`, `my-second-post.md`, and `my-first-event.md` are all of kind `page`, all `_index.md` files in a Hugo project are of kind `section` and therefore do not submit themselves to the *single* page template lookup. Instead, `events/_index.md` will render according to its [section template](/templates/section-templates/) and respective lookup order.
{{% /note %}}
### `my-first-post.md`
{{% code file="content/posts/my-first-post.md" %}}
```yaml
---
title: My First Post
date: 2017-02-19
description: This is my first post.
---
```
{{% /code %}}
When it comes time for Hugo to render the content to the page, it will go through the single page template lookup order until it finds what it needs for `my-first-post.md`:
1. <span class="no">`/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
2. <span class="no">`/layouts/posts/UNSPECIFIED.html`</span>
3. <span class="no">`/layouts/UNSPECIFIED/single.html`</span>
4. <span class="yes">`/layouts/posts/single.html`</span>
<br><span class="break">BREAK</span>
5. <span class="na">`/layouts/_default/single.html`</span>
6. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
7. <span class="na">`/themes/<THEME>/layouts/posts/UNSPECIFIED.html`</span>
8. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/single.html`</span>
9. <span class="na">`/themes/<THEME>/layouts/posts/single.html`</span>
10. <span class="na">`/themes/<THEME>/layouts/_default/single.html`</span>
Notice the term `UNSPECIFIED` rather than `UNDEFINED`. If you don't tell Hugo the specific type and layout, it makes assumptions based on sane defaults. `my-first-post.md` does not specify a content `type` in its front matter. Therefore, Hugo assumes the content `type` and `section` (i.e. `posts`, which is defined by file location) are one in the same. ([Read more on sections][section].)
`my-first-post.md` also does not specify a `layout` in its front matter. Therefore, Hugo assumes that `my-first-post.md`, which is of type `page` and a *single* piece of content, should default to the next occurrence of a `single.html` template in the lookup (#4).
### `my-second-post.md`
{{% code file="content/posts/my-second-post.md" %}}
```yaml
---
title: My Second Post
date: 2017-02-21
description: This is my second post.
type: review
layout: reviewarticle
---
```
{{% /code %}}
Here is the way Hugo's traverses the single-page lookup order for `my-second-post.md`:
1. <span class="yes">`/layouts/review/reviewarticle.html`</span>
<br><span class="break">BREAK</span>
2. <span class="na">`/layouts/posts/reviewarticle.html`</span>
3. <span class="na">`/layouts/review/single.html`</span>
4. <span class="na">`/layouts/posts/single.html`</span>
5. <span class="na">`/layouts/_default/single.html`</span>
6. <span class="na">`/themes/<THEME>/layouts/review/reviewarticle.html`</span>
7. <span class="na">`/themes/<THEME>/layouts/posts/reviewarticle.html`</span>
8. <span class="na">`/themes/<THEME>/layouts/review/single.html`</span>
9. <span class="na">`/themes/<THEME>/layouts/posts/single.html`</span>
10. <span class="na">`/themes/<THEME>/layouts/_default/single.html`</span>
The front matter in `my-second-post.md` specifies the content `type` (i.e. `review`) as well as the `layout` (i.e. `reviewarticle`). Hugo finds the layout it needs at the top level of the lookup (#1) and does not continue to search through the other templates.
{{% note "Type and not Types" %}}
Notice that the directory for the template for `my-second-post.md` is `review` and not `reviews`. This is because *type is always singular*.
{{% /note%}}
### `my-first-event.md`
{{% code file="content/events/my-first-event.md" %}}
```yaml
---
title: My First
date: 2017-02-21
description: This is an upcoming event..
---
```
{{% /code %}}
Here is the way Hugo's traverses the single-page lookup order for `my-first-event.md`:
1. <span class="no">`/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
2. <span class="no">`/layouts/events/UNSPECIFIED.html`</span>
3. <span class="no">`/layouts/UNSPECIFIED/single.html`</span>
4. <span class="no">`/layouts/events/single.html`</span>
5. <span class="yes">`/layouts/_default/single.html`</span>
<br><span class="break">BREAK</span>
6. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
7. <span class="na">`/themes/<THEME>/layouts/events/UNSPECIFIED.html`</span>
8. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/single.html`</span>
9. <span class="na">`/themes/<THEME>/layouts/events/single.html`</span>
10. <span class="na">`/themes/<THEME>/layouts/_default/single.html`</span>
{{% note %}}
`my-first-event.md` is significant because it demonstrates the role of the lookup order in Hugo themes. Both the root project directory *and* the `mytheme` themes directory have a file at `_default/single.html`. Understanding this order allows you to [customize Hugo themes](/themes/customizing/) by creating template files with identical names in your project directory that step in front of theme template files in the lookup. This allows you to customize the look and feel of your website while maintaining compatibility with the theme's upstream.
{{% /note %}}
content/templates/template-debugging.md
+17 -19
View File
@@ -10,7 +10,7 @@ categories: [templates]
tags: [debugging,troubleshooting]
weight: 180
draft: false
aliases: [/templates/debugging/]
aliases: []
toc: false
---
@@ -22,32 +22,30 @@ These snippets use the `printf` function available in all Go templates. This fu
You can use the template syntax, `$.`, to get the top-level template context from anywhere in your template. This will print out all the values under, `.Site`.
{{% code file="get-top-level-syntax.sh" %}}
```golang
```html
{{ printf "%#v" $.Site }}
```
{{% /code %}}
This will print out the value of `.Permalink`:
{{% code file="get-permalink.sh" %}}
```golang
```html
{{ printf "%#v" .Permalink }}
```
{{% /code %}}
This will print out a list of all the variables scoped to the current context
(aka [The dot, "`.`"][primer]).
(`.`, aka ["the dot"][primer]).
{{% code file="get-all-vars-current-context.sh" %}}
```golang
```html
{{ printf "%#v" . }}
```
{{% /code %}}
When writing a [Homepage][hometemplate], what does one of the pages you're looping through look like?
```golang
When developing a [homepage][], what does one of the pages you're looping through look like?
```html
{{ range .Data.Pages }}
{{/* The context, ".", is now each one of the pages as it goes through the loop */}}
{{ printf "%#v" . }}
@@ -55,24 +53,24 @@ When writing a [Homepage][hometemplate], what does one of the pages you're loopi
```
{{% note "`.Date.Pages` on the Homepage" %}}
Using `.Data.Pages` on the homepage is the equivalent of writing `.Site.Pages`.
`.Data.Pages` on the homepage is equivalent to `.Site.Pages`.
{{% /note %}}
## Why Am I Showing No Defined Variables?
Check that you are passing variables in the `partial` function:
```
```html
{{ partial "header" }}
```
This example will render the header partial, but the header partial will not have access to any contextual variables. You need to pass variables explicitly. For example note the addition of [the dot][primer].
This example will render the header partial, but the header partial will not have access to any contextual variables. You need to pass variables explicitly. For example, note the addition of ["the dot"][primer].
```
```html
{{ partial "header" . }}
```
The dot (`.`) is considered fundamental to understand Hugo templating. For more information, see the [Go Template Primer][primer].
The dot (`.`) is considered fundamental to understanding Hugo templating. For more information, see the [Go Template Primer][primer].
[hometemplate]: /templates/homepage/
[homepage]: /templates/homepage/
[primer]: /templates/go-templates/
content/templates/content-view-templates.md → content/templates/views.md
+16 -32
View File
@@ -9,27 +9,20 @@ categories: [templates]
tags: [views]
weight: 70
draft: false
aliases: [/templates/views/]
aliases: []
toc: true
wip: true
---
In addition to the [single page content template][singletemplates], Hugo can render alternative views of your content. These are especially useful in [list templates][listtemplates].
Hugo's flexibility allows you to render alternative views for specific content. These alternative **content views** are especially useful in [list templates][lists].
Content views are appropriate for cases like the following:
The following are common use cases for content views:
* You want content of every type to be shown on the homepage but only with limited [summary views][summaries].
* You only want a bulleted list of your content on a [taxonomy list page][taxonomylists]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself.
## Creating a Content View
To create a new view, simply create a template in each of your different
content type directories with the view name. In the following example, we
have created a "li" view and a "summary" view for our two content types
of post and project. As you can see, these sit next to the [single
content view](/templates/content/) template "single.html". You can even
provide a specific view for a given type and continue to use the
\_default/single.html for the primary view.
To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `post` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view.
```bash
▾ layouts/
@@ -43,7 +36,7 @@ provide a specific view for a given type and continue to use the
summary.html
```
Hugo also has support for a default content template to be used in the event that a specific template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as layouts for other types who eventually fall trickle down to this directory.
Hugo also has support for a default content template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order.
```bash
@@ -58,40 +51,35 @@ Hugo also has support for a default content template to be used in the event tha
The following is the [lookup order][lookup] for content views:
* `/layouts/<TYPE>/<VIEW>.html`
* `/layouts/\_default/<VIEW>.html`
* `/themes/<THEME>/layouts/<TYPE>/<VIEW>.html`
* `/themes/<THEME>/layouts/\_default/<VIEW>.html`
1. `/layouts/<TYPE>/<VIEW>.html`
2. `/layouts/_default/<VIEW>.html`
3. `/themes/<THEME>/layouts/<TYPE>/<VIEW>.html`
4. `/themes/<THEME>/layouts/_default/<VIEW>.html`
## Example: Content View Inside a List
The following example demonstrates how to use content views inside of your [list page templates][listtemplates].
The following example demonstrates how to use content views inside of your [list templates][lists].
### `list.html`
In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument.
This `list.html` content view template is part of a larger `section.html` default template used for [spf13.com][spf]. ([See source on GitHub][spfsourcesection].)
In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows:
{{% code file="layouts/_default/list.html" download="list.html" %}}
```
<section id="main">
<main id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
</main>
```
{{% /code %}}
### `summary.html`
Hugo will pass the entire page object to the view template. See [page
variables](/templates/variables/) for a complete list.
This `summary.html` content view template is used for [spf13.com][spf]. ([See source on GitHub][spfsourcesummary].)
Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.)
{{% code file="layouts/_default/summary.html" download="summary.html" %}}
```html
@@ -110,12 +98,8 @@ This `summary.html` content view template is used for [spf13.com][spf]. ([See so
### `li.html`
Hugo will pass the entire page object to the view template. See [Page Variables][pagevars] for a complete list of variables Hugo makes available to you.
Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`).
This `li.html` content view template is used for [spf13.com][spf]. ([See source on GitHub][spfsourceli].)
{{% code file="layouts/_default/li.html" download="li.html" %}}
```html
<li>
@@ -125,11 +109,11 @@ This `li.html` content view template is used for [spf13.com][spf]. ([See source
```
{{% /code %}}
[listtemplates]: /templates/lists/
[lists]: /templates/lists/
[lookup]: /templates/lookup-order/
[pagevars]: /variables/page-variables/
[render]: /functions/render/
[singletemplates]: /templates/single-page-templates/
[single]: /templates/single-page-templates/
[spf]: http://spf13.com
[spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html
[spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html
dev-and-design-resources/about.afdesign → design-resources/about.afdesign
View File
dev-and-design-resources/cloud.afdesign → design-resources/cloud.afdesign
View File
dev-and-design-resources/commands.afdesign → design-resources/commands.afdesign
View File

Some files were not shown because too many files have changed in this diff Show More