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

Update content changes in concept document

Browse Source
This commit is contained in:
Ryan Watters
2017-02-26 22:23:06 -06:00
parent 6cf783469e
commit 72e1b60244
63 changed files with 427 additions and 371 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/about-hugo/features.md
+1 -1
View File
@@ -65,7 +65,7 @@ See what's coming next in the [Hugo roadmap][].
[functions]: /functions/
[Golang]: http://golang.org/pkg/html/template/
[Google Analytics]: https://google-analytics.com/
[homepage]: /templates/homepage-template/
[homepage]: /templates/homepage/
[Host your site anywhere]: /hosting-and-deployment/
[Hugo roadmap]: /about-hugo/roadmap
[Linux]: /getting-started/install-on-mac/
content/concept.md
+46 -14
View File
@@ -183,7 +183,7 @@ The preceding analytics and metrics are separate from usage statics re: Hugo dow
- [X] Abstracted typefaces (multiple open-source fonts available)
## Content Changes
## Annotated Content Changes
The following is an *abbreviated* listing of *substantive* changes made to the current documentation's source content and organization. Sections here are ordered according to the current site navigation. The changes delimited here do not include copy edits for consistent or preferred usage, improvements in semantics, etc, all of which easily numbers in the thousands, likely more.
@@ -210,10 +210,16 @@ Site showcase has stayed more or less as is, including styling, etc. However...
### Content
* This section has been renamed "Content Management" to facilitate elimination of the ["extras"](http://gohugo.io) section. **Note**: this section does *not* include any templating. The convention is `content-management/shortcodes.md` (for explanation and usage) and then `content-management/shortcode-templates.md`
* This section has been renamed "Content Management" to facilitate elimination of the ["extras"](http://gohugo.io) section. **Note**: this section does *not* include any templating. The convention is `content-management/concept.md` (for explanation and usage) `templates/concept-templates.md` (for examples, functions, etc), and then `variables/concept-variables.md`.
* That said, I'm working on refactoring a series of shortcodes for variables so that it's only a matter of referencing them once and having them update everywhere.
### Themes
Themes section organization has only changed slightly in that the 6 content pages have been consolidated to just 4.
* "Installing a theme" and "Using a Theme" have been combined since one largely dovetails with the other. The current [using a theme page](http://gohugo.io/themes/usage/) is pretty skimpy. An alias for `themes/usage` has been set up accordingly.
*
### Templates
* Reworked considerably. Page titles have all been changed to reflect their obvious connection to *templating*.
@@ -222,6 +228,8 @@ Site showcase has stayed more or less as is, including styling, etc. However...
### Taxonomies
*Taxonomies* is no longer an independent section. Similar to shortcodes and menus, taxonomies is broken into two equal pages: one under Content Management, and the other under Templates.
### Extras
@@ -236,23 +244,48 @@ Site showcase has stayed more or less as is, including styling, etc. However...
### Community
The "Community" section has been removed as a site navigation item because `/contribute` is now it's own section.
* There are now more calls than ever for contributing to Hugo throughout the Hugo docs.
*
### Tutorials
* Original page: <http://gohugo.io/tutorials>
* All installation guides have been consolidated under [/getting-started/installing/]
* Installing Hugo shouldn't be considered a separate tutorial
* "Tutorials" is not an intuitive place for end-users to look for this kind of documentation
* All content moved from `/tutorials` edited to reflect a less tutorial-ish style of language (e.g., remove of lines starting with "In this tutorial...")
* All installation guides have been consolidated under [/getting-started/installing/](/getting-started/installing/)
* Why? Installing Hugo shouldn't be considered a separate tutorial
* "Tutorials" is not an intuitive place for end users to look for this kind of documentation
* All content moved from `/tutorials` has been edited to reflect a less tutorial-ish style of language (e.g., removal of lines starting with "In this tutorial...")
* Aliases added to new pages and in-page links updated throughout
* Michael Henderson's "Creating a Theme" website ([current][],[concept][]) has been copy edited and content edited to include the new code block shortcodes.
* Remaining Tutorials
* Are these worth keeping in their entirety if they reflect (sometimes much) older versions of Hugo?
* Michael Henderson's "Creating a Theme" website ([current][],[concept][]) has been copy edited and content edited to include the new code block shortcodes. Michael did an *amazing* job with this tutorial, and it must have taken him *forever*, but much of the information included in the tutorial is now spread throughout the documentation in more appropriate places. Also, because this is an older tutorial, some of the paradigms aren't quite as up to date.
* Rick Cogley's still needs to be copy edited a bit, but overall looks good. That said, this tutorial was put together before Hugo began implementing it's international features.
* **Guidelines for New Tutorials**
* To keep the content in tutorials maintainable, it's important to set standards on what should be contained within said tutorials when published directly to the Hugo docs. (Of course, listing beginning-to-end tutorials in other areas of the website [i.e., press and articles] is a very good idea). The following pieces of information should be omitted from full-text tutorials in the Hugo docs because they are better delimited and kept current in other areas:
* Explanations directory structure or content organization
* Explanations of content formats (namely, `.md`) or front matter
* Explanations of how to set up hosting, deployments, or automated deployments (although these make excellent additions to the "Hosting and Deployments" section)
* "Using Hugo Shortcodes with Google Sheets or Data-Driven Content" is a better tutorial example than "Getting Up and Running with Hugo" or "Deploying Your Hugo Website with an Apache Server"
### Troubleshooting
* This section still only contains the same two troubleshooting content pages from the current site.
* Both pages have been copy edited, and the markdown has been cleaned up for consistency.
### Tools
* Rather than a single-page list, a full "developer tools" section is part of the main navigation and includes the following pages:
* Migrate to Hugo. List of project-descriptions of community-developed migration tools
* Syntax highlighting. This builds on the syntax highlighting shortcode used in [/shortcodes/#highlight](/shortcodes/#highlight).
* Starter Kits. Only two items for now, but this should remain a community-aggregated (and edited) list of kits developed to help new users get up and running.
* Frontends. Same frontends material previously under "tools." Copy edited for consistency.
* Editor Plug-ins. Same editor plug-ins material found in current documentation. Copy edited for consistency.
* Search. Same search material under "tools" in current documentation. Copy edited for consistency.
* Other projects. This might be worth restructuring since I'm not a fan of catch-all sections or pages.
### Hugo Cmd Reference
This hasn't been touched. I'll make the necessary style changes once/if the site is integrated into the Hugo GH repo since these pages are pulled automatically using Viper.
This hasn't been touched. I'll make the necessary style changes once/if the site is integrated into the Hugo GH repo. I believe these pages are pulled automatically using Viper.
### Issues & Help
@@ -329,7 +362,7 @@ Apache License - 60
### "functions" Ordering (`.OrderByTitle`)
### "variables-and-Params" Ordering (`.OrderByWeight`)
### "variables" Ordering (`.OrderByWeight`)
* _index.md - 01
* Site Variables - 10
@@ -355,12 +388,11 @@ Apache License - 60
* Creating a Theme - 30
* Theme Showcase - 40
### "site-showcase" Ordering (`.OrderByPublishDate`)
### "showcase" Ordering (`.OrderByPublishDate`)
### "Troubleshooting" Ordering
### "troubleshooting" Ordering (`.OrderByTitle`)
**Ordered by title**
## Current Content (Source)
@@ -377,7 +409,7 @@ If the Hugo Team finds the improvements to the Hugo documentation acceptable, I'
3. **2017-03-6** Pull request/add to Hugo Rep
3. **2017-??-??** Add to Hugo repo for release with v19?
[^1]: As this point, the URL structure has changed considerably. I've been fastidious about adding aliases wherever possible and trying to retain URLs for related content on the current site if applicable. That said, the [current list of aliases is quite large](/contribute/documentation/#be-mindful-of-aliases).
[^1]: At this point, not too much of the URL structure has changed that considerably. I've been fastidious about adding aliases wherever possible and trying to retain URLs whenever still applicable. That said, the [current list of aliases is quite large](/contribute/documentation/#be-mindful-of-aliases).
[admonitions]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
[designresources]: https://github.com/rdwatters/hugo-docs-concept/tree/master/dev-and-design-resources
@@ -389,5 +421,5 @@ If the Hugo Team finds the improvements to the Hugo documentation acceptable, I'
[patch1]: http://gohugo.io/taxonomies/templates/
[patch2]: https://github.com/spf13/hugo/commit/eaabecf586fd0375585e27c752e05dd8cb4c72b4
[Quick Start]: https://hugodocsconcept.netlify.com/getting-started/quick-start/
[showcasefiles]:
[showcasefiles]: https://github.com/rdwatters/hugo-docs-concept/tree/master/content/showcase
[tagspage]: https://hugodocsconcept.netlify.com/tags/
content/content-management/multilingual.md
+1 -1
View File
@@ -243,7 +243,7 @@ If there is more than one language defined, the`LanguagePrefix` variable will eq
[abslangurl]: /functions/abslangurl
[contenttemplate]: /templates/single-page-template/
[homepage]: /templates/homepage-template/
[homepage]: /templates/homepage/
[hugoconfig]: /getting-started/configuration/
[i18func]: /functions/i18n/
[RFC 5646]: https://tools.ietf.org/html/rfc5646
content/content-management/organization.md
+1 -1
View File
@@ -259,7 +259,7 @@ An `_index.md` file has also been added in the top level 'content' directory.
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/content to the homepage.
[front matter]: /content-management/front-matter/
[homepage]: /templates/homepage-template/
[homepage]: /templates/homepage/
[section]: /content-management/section/
[formats]: /content-management/formats/
[singles]: /templates/single-page-templates/
content/developer-tools/syntax-highlighting.md
+1 -1
View File
@@ -5,7 +5,7 @@ description: Hugo provides server-side syntax highlighting via Pygments and, lik
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: [highlighting,pygments,code blocks]
tags: [highlighting,pygments,code blocks,syntax]
categories: [developer tools]
weight: 20
draft: false
content/functions/GetPage.md
+26 -7
View File
@@ -1,20 +1,18 @@
---
title: getpage
linktitle: GetPage
description:
description: Looks up the index page (`_index.md`) of a given `Kind` and `path`.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: []
categories: [functions]
toc:
tags: [sections,lists,indexes]
signature:
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
draft: false
aliases: []
---
@@ -22,13 +20,34 @@ Every `Page` has a `Kind` attribute that shows what kind of page it is. While th
`GetPage` looks up an index page of a given `Kind` and `path`. This method may support regular pages in the future, but currently it is a convenient way of getting the index pages, such as the home page or a section, from a template:
{{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}
```
{{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}
```
This method wil return `nil` when no page could be found, so the above will not print anything if the blog section isn't found.
The valid page kinds are: *home, section, taxonomy and taxonomyTerm.*
**The following is a good example of `.GetPage`**:
## `.GetPage` Example
<https://discuss.gohugo.io/t/problem-with-loop-and-scratch/5597
This code snippet---in the form of a [partial template][partials]---allows you to do the following:
1. Grab the index object of your `tags` [taxonomy][].
2. Assign this object to a variable, `$t`
3. Sort the terms associated with the taxonomy by popularity.
4. Grab the top two most popular terms in the taxonomy (i.e., the two most popular tags assigned to content.
{{% code file="grab-top-two-tags.html" %}}
```html
<ul class="most-popular-tags">
{{ $t := $.Site.GetPage("taxonomyTerm", "tags") }}
{{ range first 2 $t.Data.Terms.ByCount }}
<li>{{.}}</li>
{{ end }}
</ul>
```
{{% /code %}}
[partials]: /templates/partials/
[taxonomy]: /content-management/taxonomies/
content/functions/_index.md
+2 -2
View File
@@ -2,11 +2,11 @@
title: Functions Quick Reference
linktitle: Quick Reference
description: Comprehensive list of Hugo templating functions, including basic and advanced usage examples.
godocref: http://golang.org/pkg/text/template/#hdr-Functions
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: [functions,templating]
tags: []
weight: 01
draft: false
aliases: [/layout/functions/]
content/functions/abslangurl-and-rellangurl.md → content/functions/abslangurl.md
+4 -4
View File
@@ -1,13 +1,13 @@
---
title: abslangurl and rellangurl
linktitle: absLangURL and relLangURL
description: Similar to absURL, but adds the absolute URL with correct language prefix according to site configuration for multilingual and baseURL.
title: abslangurl
linktitle: absLangURL
description: Adds the absolute URL with correct language prefix according to site configuration for multilingual.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: [multilingual,i18n,urls]
categories: [functions]
tags: [multilingual,i18n,urls]
signature:
workson: []
hugoversion:
content/functions/chomp.md
+1 -1
View File
@@ -1,7 +1,7 @@
---
title: chomp
linktitle: chomp
description:
description: Removes any trailing newline characters.
godocref: Removes any trailing newline characters.
date: 2017-02-01
publishdate: 2017-02-01
content/functions/countrunes.md
+26
View File
@@ -0,0 +1,26 @@
---
title: countrunes
linktitle: countrunes
description: Determines the number of runes in a string and excludes any whitespace.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [functions]
tags: [counting, word count]
signature:
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
aliases: [/functions/countrunes/,/functions/countwords/]
---
In contrast with `countwords` function, which counts every word in a string, the `countrunes` function determines the number of runes in the content and excludes any whitespace. This has specific utility if you are dealing with CJK-like languages.
```html
{{ "Hello, 世界" | countrunes }}
<!-- outputs a content length of 8 runes. -->
```
[pagevars]: /variables/page-variables/
content/functions/countrunes-and-countwords.md → content/functions/countwords.md
+4 -11
View File
@@ -1,7 +1,7 @@
---
title: countrunes and countwords
linktitle: countrunes and countwords
description: countrunes and countwords both serve as a means to quantify the total the length of your content.
title: countwords
linktitle: countwords
description: Counts the number of words in a string that has been passed to it.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
@@ -11,7 +11,7 @@ tags: [counting, word count]
signature:
workson: []
hugoversion:
relatedfuncs: []
relatedfuncs: [countrunes]
deprecated: false
aliases: [/functions/countrunes/,/functions/countwords/]
---
@@ -24,11 +24,4 @@ aliases: [/functions/countrunes/,/functions/countwords/]
```
In contrast with counting every word, the `countrunes` function determines the number of runes in the content and excludes any whitespace. This has specific utility if you are dealing with CJK-like languages.
```html
{{ "Hello, 世界" | countrunes }}
<!-- outputs a content length of 8 runes. -->
```
[pagevars]: /variables/page-variables/
content/functions/dateformat.md
+4 -3
View File
@@ -1,7 +1,7 @@
---
title: dateFormat
linktitle:
description:
description: Converts the textual representation of the `datetime` into the specified format.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
@@ -11,7 +11,7 @@ tags: [dates,time,strings]
signature:
workson: []
hugoversion:
relatedfuncs: []
relatedfuncs: [now,Unix]
deprecated: false
---
@@ -19,4 +19,5 @@ deprecated: false
```
{{ dateFormat "Monday, Jan 2, 2006" "2015-01-21" }} → "Wednesday, Jan 21, 2015"
```
```
content/functions/default.md
+2 -2
View File
@@ -1,7 +1,7 @@
---
title: default
linktitle: default
description:
description: Allows setting a default value that can be returned if a first value is not set.
qref: "Returns a default value if a value is not set when checked."
godocref:
date: 2017-02-01
@@ -20,7 +20,7 @@ aliases: [/functions/default/]
needsexamples: false
---
Checks whether a given value is set and returns a default value if it is not. *Set* in this context means different things depending on date type:
`default` checks whether a given value is set and returns a default value if it is not. *Set* in this context means different things depending on date type:
* non-zero for numeric types and times
* non-zero length for strings, arrays, slices, and maps
content/functions/dict.md
+11 -13
View File
@@ -1,30 +1,28 @@
---
title: dict
linktitle:
description:
linktitle: dict
description: Creates a dictionary `(map[string, interface{})` that expects parameters added in a value:object fashion.
godocref:
workson: []
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: []
lastmod: 2017-02-26
categories: [functions]
toc:
tags: [dictionary]
signature:
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
draft: false
aliases: []
needsexamples: true
---
Creates a dictionary `(map[string, interface{})`, expects parameters added in value:object fasion.
Invalid combinations like keys that are not strings or uneven number of parameters, will result in an exception thrown.
Useful for passing maps to partials when adding to a template.
`dict` creates a dictionary `(map[string, interface{})` that expects parameters added in a value:object fashion.
e.g. Pass into "foo.html" a map with the keys "important, content"
Invalid combinations---e.g., keys that are not strings or an uneven number of parameters---will result in an exception being thrown. `dict` is especially useful for passing maps to partials being added to a template.
For example, the following snippet passes a map with the keys "important, content" into "foo.html"
{{% code file="dict-example.html" %}}
```html
@@ -35,14 +33,14 @@ e.g. Pass into "foo.html" a map with the keys "important, content"
```
{{% /code %}}
And then in `foo.html`:
These keys can then be called in `foo.html` as follows:
```golang
Important {{.important}}
{{.content}}
```
`dict` also allows you to create a map on the fly to pass into
`dict` also allows you to create a map on the fly to pass into your [partial templates][partials]
{{% code file="dict-create-map.html" %}}
```golang
@@ -50,4 +48,4 @@ Important {{.important}}
```
{{% /code %}}
[partials]: /templates/partials/
content/functions/emojify.md
+2 -2
View File
@@ -1,7 +1,7 @@
---
title: emojify
linktitle:
description:
description: Runs a string through the Emoji emoticons processor.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
@@ -15,7 +15,7 @@ relatedfuncs: []
deprecated: false
---
Runs the string through the Emoji emoticons processor. The result will be declared as "safe" to prevent Go templates from filtering it as unsafe HTML.
`emoji` runs a passed string through the Emoji emoticons processor. The result will be declared as "safe" to prevent Go templates from filtering it as unsafe HTML.
See the [Emoji cheat sheet][emojis] for available emoticons.
content/functions/get.md
+13 -3
View File
@@ -1,20 +1,30 @@
---
title: get
linktitle: Get
description:
description: Accesses positional and ordered parameters in shortcode declaration.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [functions]
tags: [shortcodes]
toc:
signature:
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
draft: false
aliases: []
needsexample: true
---
`.Get` is specifically used when creating your own [shortcode template][sc].
[sc]: /templates/shortcode-templates/
content/functions/haschildren.md
+1 -1
View File
@@ -14,7 +14,7 @@ workson: []
hugoversion:
relatedfuncs: []
deprecated: false
draft: false
draft: true
aliases: []
---
content/functions/hasmenucurrent.md
+4 -2
View File
@@ -14,6 +14,8 @@ workson: []
hugoversion:
relatedfuncs: []
deprecated: false
draft: false
draft: true
aliases: []
---
---
**Needs examples?**
content/functions/highlight.md
+3 -3
View File
@@ -1,13 +1,13 @@
---
title: highlight
linktitle:
description:
linktitle: highlight
description: Takes a string of code and language declaration and uses Pygments to return syntax-highlighted HTML with inline-styles.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [functions]
tags: []
tags: [highlighting,pygments,code blocks,syntax]
signature:
workson: []
hugoversion:
content/functions/index-function.md
+8 -5
View File
@@ -1,25 +1,28 @@
---
title: index
linktitle: index
description:
description: Looks up the index(es) or key(s) of the data structure passed into it.
godocref: https://golang.org/pkg/text/template/#hdr-Functions
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: []
categories: [functions]
toc:
tags: []
signature:
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
draft: false
aliases: []
needsexample: true
---
`index` looks up the index(es) or key(s) of the data structure passed into it.
From the godocs:
> Returns the result of indexing its first argument by the following arguments. Thus "index x 1 2 3" is, in Go syntax, x[1][2][3]. Each indexed item must be a map, slice, or array.
## Example
In Go templates, you can't access array, slice, or map elements directly the same way you would in Go. For example, `$.Site.Data.authors[.Params.authorkey]` isn't supported syntax.
Instead, you have to use `index`, a function that handles the lookup for you.
content/functions/ismenucurrent.md
+1 -2
View File
@@ -8,12 +8,11 @@ publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [functions]
tags: [menus]
toc:
signature:
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
draft: false
draft: true
aliases: []
---
content/functions/math.md
+1 -1
View File
@@ -1,7 +1,7 @@
---
title: math
linktitle: Math
description:
description: Hugo provides six mathematical operators in templates.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
content/functions/now.md
+2 -2
View File
@@ -1,7 +1,7 @@
---
title: now
linktitle: now
description:
description: Returns the current local time as a [`time.Time`]
godocref: https://godoc.org/time#Time
date: 2017-02-01
publishdate: 2017-02-01
@@ -11,7 +11,7 @@ tags: [dates,time]
signature:
workson: []
hugoversion:
relatedfuncs: []
relatedfuncs: [Unix,dateFormat]
deprecated: false
aliases: []
needsexamples: true
content/functions/param.md
+15 -1
View File
@@ -1,7 +1,7 @@
---
title: param
linktitle: Param
description:
description: Calls page or site variables into your template.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
@@ -16,5 +16,19 @@ relatedfuncs: []
deprecated: false
draft: false
aliases: []
needsreview: true
---
In Hugo, you can declare [site-wide params][sitevars] (i.e. in your [configuration][]), as well as params for [individual pages][pagevars].
A common use case is to have a general value for the site and a more specific value for some of the pages (e.g., an image).
You can use the `.Param` method to call these values into your template:
```
$.Param "image"
```
[configuration]: /getting-started/configuration/
[pagevars]: /variables/page-variables/
[sitevars]: /variables/site-variables/
content/functions/partialCached.md
+3 -7
View File
@@ -1,25 +1,21 @@
---
title: partialCached
linktitle:
description:
linktitle: partialCached
description: Allows for caching of partials that do not need to be re-rendered on every invocation.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: []
categories: [functions]
toc:
tags: []
signature:
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
draft: false
aliases: []
---
### partialCached
The `partialCached` template function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. Here is the simplest usage:
```golang
content/functions/printf.md
+3 -4
View File
@@ -1,13 +1,13 @@
---
title: printf
linktitle: printf
description:
description: Formats a string using the standard `fmt.Sprintf` function.
godocref: https://golang.org/pkg/fmt/
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [functions]
tags: []
tags: [strings]
signature:
workson: []
hugoversion:
@@ -16,8 +16,7 @@ deprecated: false
needsexamples: true
---
Format a string using the standard `fmt.Sprintf` function. See [the go
doc](https://golang.org/pkg/fmt/) for additional information.
`printf` formats a string using the standard `fmt.Sprintf` function. See [the go doc](https://golang.org/pkg/fmt/) for additional information.
```golang
{{ i18n ( printf "combined_%s" $var ) }}
content/functions/querify.md
+1 -1
View File
@@ -1,7 +1,7 @@
---
title: querify
linktitle: querify
description:
description: Takes a set of key-value pairs and returns a query string to be appended to URLs.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
content/functions/range.md
+4 -6
View File
@@ -1,14 +1,13 @@
---
title: range
linktitle:
description:
description: Iterates over a map, array, or slice.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: [iteration,fundamentals]
categories: [functions]
toc:
tags: [iteration,fundamentals]
signature:
workson: []
hugoversion:
@@ -18,7 +17,6 @@ draft: false
aliases: []
---
## Example
## Advanced Example
Just like in the Go programming language, Go and Hugo templates make heavy use of `range` to iterate over a map, array or slice.
`range` is fundamental to templating in Hugo. (See the [Go Template Primer](/templates/go-templates/) for more examples.
content/functions/readdir-and-readfile.md → content/functions/readdir.md
+6 -19
View File
@@ -1,23 +1,21 @@
---
title: readdir and readfile
linktitle:
description:
title: readdir
linktitle: readDir
description: Gets a directory listing from a directory relative to the current working directory.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: [files]
categories: [functions]
tags: [files]
signature:
workson: []
hugoversion:
relatedfuncs: []
relatedfuncs: [readFile]
deprecated: false
aliases: [/functions/readdir/,/functions/readfile/]
aliases: []
---
## `readDir`
`readDir` gets a directory listing from a directory relative to the current project working directory.
If your current project working directory has a single file named `README.txt`:
@@ -26,18 +24,7 @@ If your current project working directory has a single file named `README.txt`:
{{ range (readDir ".") }}{{ .Name }}{{ end }} → "README.txt"
```
## `readFile`
Reads a file from disk and converts it into a string. Note that the filename must be relative to the current project working directory.
So, if you have a file with the name `README.txt` in the root of your project with the content `Hugo Rocks!`:
```
{{readFile "README.txt"}} → "Hugo Rocks!"
```
For more information on using `readDir` and `readFile` in your templates, see [Local File Templates][local].
[local]: /templates/local-file-templates/
content/functions/readfile.md
+29
View File
@@ -0,0 +1,29 @@
---
title: readfile
linktitle: readFile
description: Reads a file from disk relative to the current project working directory and converts it into a string.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [functions]
tags: [files]
signature:
workson: []
hugoversion:
relatedfuncs: [readDir]
deprecated: false
aliases: []
---
`readFile` reads a file from disk and converts it into a string. Note that the filename must be relative to the current project working directory.
So, if you have a file with the name `README.txt` in the root of your project with the content `Hugo Rocks!`:
```
{{readFile "README.txt"}} → "Hugo Rocks!"
```
For more information on using `readDir` and `readFile` in your templates, see [Local File Templates][local].
[local]: /templates/local-file-templates/
content/functions/ref-and-relref.md → content/functions/ref.md
+5 -5
View File
@@ -1,7 +1,7 @@
---
title: ref and relref
linktitle: ref and relref
description: Looks up a content page by relative path or logical name to return the content page's permalink.
title: ref
linktitle: ref
description: Looks up a content page by logical name.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
@@ -13,10 +13,10 @@ workson: []
hugoversion:
relatedfuncs: [relref]
deprecated: false
aliases: [/functions/ref/,/functions/relref/]
aliases: []
---
These two functions looks up a content page by relative path (`relref`) or logical name (`ref`) to return the permalink. Both functions require a `Page` object (usually satisfied with a "`.`"):
`ref` and `relRef` look up a content page by relative path (`relref`) or logical name (`ref`) to return the permalink. Both functions require a `Page` object (usually satisfied with a "`.`"):
```golang
{{ relref . "about.md" }}
content/functions/rel.md
-24
View File
@@ -1,24 +0,0 @@
---
title: rel
linktitle:
description:
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: []
categories: [functions]
toc:
signature:
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
draft: false
aliases: []
---
## Example
## Advanced Example
content/functions/relref.md
+27
View File
@@ -0,0 +1,27 @@
---
title: relref
linktitle: relref
description: Looks up a content page by relative path.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [functions]
tags: [cross references, anchors]
signature:
workson: []
hugoversion:
relatedfuncs: [relref]
deprecated: false
aliases: []
---
`ref` and `relRef` look up a content page by relative path (`relref`) or logical name (`ref`) to return the permalink. Both functions require a `Page` object (usually satisfied with a "`.`"):
```golang
{{ relref . "about.md" }}
```
These functions are used in two of Hugo's built-in shortcodes. You can see basic usage examples of both `ref` and `relref` in the [shortcode documentation](/content-management/shortcodes/#ref-and-relref).
For an extensive explanation of how to leverage `ref` and `relref` for content management, see [Cross References](/content-management/cross-references/).
content/functions/render.md
+7 -7
View File
@@ -1,26 +1,24 @@
---
title: render
linktitle: Render
description:
description: Takes a view to apply when rendering content.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: [views]
categories: [functions]
toc:
tags: [views]
signature:
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
draft: false
aliases: []
---
Takes a view to render the content with. The view is an alternate layout, and should be a file name that points to a template in one of the locations specified in the documentation for [Content Views](/templates/views).
`Render` takes a view to apply when rendering content. The view is an alternative layout and should be a file name that points to a template in one of the locations specified in the documentation for [Content Views](/templates/views).
This function is only available on a piece of content, and in list context.
This function is only available when applied to a single piece of content within a [list context][].
This example could render a piece of content using the content view located at `/layouts/_default/summary.html`:
@@ -28,4 +26,6 @@ This example could render a piece of content using the content view located at `
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
```
```
[list context]: /templates/lists/
content/functions/scratch.md
+2 -2
View File
@@ -1,7 +1,7 @@
---
title: scratch
linktitle: Scratch
description:
description: Acts as a "scratchpad" to allow for writable page-scoped variables.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
@@ -18,7 +18,7 @@ draft: false
aliases: [/extras/scratch/,/doc/scratch/]
---
**`Scratch`** is a "scratchpad" for your [page-scoped variables][pagevars]. In most cases you can do well without `Scratch`, but there are some use cases that aren't solvable with Go's templates without `Scratch`'s help, due to scoping issues.
`Scratch` is a "scratchpad" for your [page-scoped variables][pagevars]. In most cases you can do well without `Scratch`, but there are some use cases that aren't solvable with Go's templates without `Scratch`'s help, due to scoping issues.
`Scratch` is added to both `Page` and `Shortcode` -- with following methods:
content/functions/sha.md
+2 -2
View File
@@ -1,13 +1,13 @@
---
title: sha
linktitle: sha
description:
description: Hashes the given input and returns either an SHA1 or SHA256 checksum.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [functions]
tags: []
tags: [sha,checksum]
signature:
workson: []
hugoversion:
content/functions/shuffle.md
+1 -5
View File
@@ -1,15 +1,13 @@
---
title: shuffle
linktitle:
description:
description:
description: Returns a random permutation of a given array or slice.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: [ordering]
categories: [functions]
toc:
signature:
workson: []
hugoversion:
@@ -20,8 +18,6 @@ aliases: []
needsexamples: true
---
### shuffle
`shuffle` returns a random permutation of a given array or slice:
{{% code file="shuffle-input.html" %}}
content/functions/slice.md
+2 -2
View File
@@ -1,7 +1,7 @@
---
title: slice
linktitle: slice
description:
description: Creates an array (`[]interface{}``) of all passed arguments.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
@@ -23,7 +23,7 @@ needsexamples: true
One use case is the concatenation of elements in combination with the [`delimit` function][]:
{{% code "slice.html" %}}
{{% code file="slice.html" %}}
```html
{{ delimit (slice "foo" "bar" "buzz") ", " }}
<!-- returns the string "foo, bar, buzz" -->
content/functions/the-dot.md
-20
View File
@@ -1,20 +0,0 @@
---
title: thedot
linktitle: The Dot (.)
description:
godocref: https://golang.org/pkg/text/template/#hdr-Variables
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: [fundamentals,iteration]
categories: [functions]
weight:
toc:
signature:
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
draft: false
aliases: []
---
content/functions/time.md
+1 -1
View File
@@ -1,7 +1,7 @@
---
title: time
linktitle:
description:
description: Converts a timestamp string into a `time.Time` structure.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
content/functions/trim.md
+2 -2
View File
@@ -1,7 +1,7 @@
---
title: trim
linktitle:
description:
description: Returns a slice of a passed string with all leading and trailing characters from cutset removed.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
@@ -15,7 +15,7 @@ relatedfuncs: []
deprecated: false
---
Trim returns a slice of the string with all leading and trailing characters contained in cutset removed.
`trim` returns a slice of the string with all leading and trailing characters contained in cutset removed.
```
{{ trim "++Batman--" "+-" }} → "Batman"
content/functions/unix.md
+24 -5
View File
@@ -1,8 +1,8 @@
---
title: unix
linktitle: Unix
description:
godocref:
description: Unix returns the local Time corresponding to the given Unix time, sec seconds and nsec nanoseconds since January 1, 1970 UTC.
godocref: https://golang.org/search?q=Unix#Functions
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
@@ -18,9 +18,28 @@ draft: false
aliases: []
---
## Example
`Unix` returns t as a Unix time; i.e., the number of seconds elapsed since January 1, 1970 UTC.
refer to http://gohugo.io/templates/go-templates/#template-example-show-only-upcoming-events
## `Unix` Example: Show Only Upcoming Events
## Advanced Example
The following assumes you have a content section called `events` (i.e., `content/events/*.md`). The following [partial template][] allows you to only list events that haven't occurred yet.
{{% code file="layouts/partials/upcoming-events.html" download="upcoming-events.html" %}}
```html
<h4>Upcoming Events</h4>
<ul class="upcoming-events">
{{ range where .Data.Pages.ByDate "Section" "events" }}
{{ if ge .Date.Unix .Now.Unix }}
<li><span class="event-type">{{ .Type | title }} —</span>
{{ .Title }}
on <span class="event-date">
{{ .Date.Format "2 January at 3:04pm" }}</span>
at {{ .Params.place }}
</li>
{{ end }}
{{ end }}
</ul>
```
{{% /code %}}
[partial template]: /templates/partials/
content/functions/with.md
-19
View File
@@ -1,19 +0,0 @@
---
title: with
linktitle: with
description:
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: [fundamentals]
categories: [functions]
toc:
signature:
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
draft: false
aliases: []
---
content/templates/additional-templating-languages.md
+2 -2
View File
@@ -1,7 +1,7 @@
---
title: Additional Templating Languages
linktitle: Additional Templating
description: In addition to Go templates and Amber templates, Hugo supports the powerful Ace templating from @yosssi and Amber templating from @eknkc.
description: In addition to Go templates, Hugo supports the powerful Ace templating from @yosssi and Amber templating from @eknkc.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
@@ -70,5 +70,5 @@ For Amber template documentation, follow the links from the [Amber project][].
[aceinheritance]: https://github.com/yosssi/ace/tree/master/examples/base_inner_template
[Amber Project]: https://github.com/eknkc/amber
[template functions]: /functions/
[Go templates]: /templates/go-template-primer/
[Go templates]: /templates/go-templates/
[Go base templates]: /templates/base-templates-and-blocks/
content/templates/base-templates-and-blocks.md
+1 -1
View File
@@ -85,7 +85,7 @@ 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 [Go Context Dot](/functions/the-dot/).)
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.
content/templates/go-template-primer.md → content/templates/go-templates.md
+13 -12
View File
@@ -10,7 +10,7 @@ categories: [templates]
tags: [go,fundamentals]
weight: 10
draft: false
aliases: [/templates/go-templates/,/layouts/go-templates/,/layout/go-templates/]
aliases: [/templates/go-template-primer/,/layouts/go-templates/,/layout/go-templates/]
toc: true
needsreview: true
---
@@ -112,7 +112,7 @@ the /layout/ directory within Hugo.
{{ template "partials/header.html" . }}
```
And, starting with Hugo v0.12, you may also use the `partial` call
Starting with Hugo v0.12, you may also use the `partial` call
for [partial templates][partials]:
```golang
@@ -129,7 +129,7 @@ Just like in Go, the Go templates make heavy use of `range` to iterate over
a map, array or slice. The following are different examples of how to use
range.
**Example 1: Using Context**
#### Example 1: Using Context**
```golang
{{ range array }}
@@ -137,7 +137,7 @@ range.
{{ end }}
```
**Example 2: Declaring value variable name**
#### Example 2: Declaring Value=>Variable name
```golang
{{range $element := array}}
@@ -145,7 +145,7 @@ range.
{{ end }}
```
**Example 2: Declaring key and value variable name**
#### Example 3: Declaring Key-Value Variable Name
```golang
{{range $index, $element := array}}
@@ -164,13 +164,13 @@ Go Templates treat the following values as false:
* 0
* any array, slice, map, or string of length zero
**Example 1: `if`**
#### Example 1: `if`
```golang
{{ if isset .Params "title" }}<h4>{{ index .Params "title" }}</h4>{{ end }}
```
**Example 2: `if` … `else`**
#### Example 2: `if` … `else`
```golang
{{ if isset .Params "alt" }}
@@ -180,13 +180,13 @@ Go Templates treat the following values as false:
{{ end }}
```
**Example 3: `and` & `or`**
#### Example 3: `and` & `or`
```golang
{{ if and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}}
```
**Example 4: `with`**
#### Example 4: `with`
An alternative way of writing "`if`" and then referencing the same value
is to use "`with`" instead. `with` rebinds the context `.` within its scope,
@@ -196,7 +196,7 @@ The first example above could be simplified as:
{{ with .Params.title }}<h4>{{ . }}</h4>{{ end }}
**Example 5: `if` … `else if`**
#### Example 5: `if` … `else if`
```golang
{{ if isset .Params "alt" }}
@@ -455,8 +455,8 @@ Finally, you can pull "magic constants" out of your layouts as well. The followi
Go allows you to do more than what's shown here. Using Hugo's [`where` function](/functions/where/) and Go built-ins, we can list only the items from `content/events/` whose date (set in a content file's [front matter][]) is in the future. The following is an example [partial template][partials]:
{{% code file="layouts/partials/show-upcoming-dates.html" download="show-upcoming-dates.html" %}}
```golang
{{% code file="layouts/partials/upcoming-events.html" download="upcoming-events.html" %}}
```html
<h4>Upcoming Events</h4>
<ul class="upcoming-events">
{{ range where .Data.Pages.ByDate "Section" "events" }}
@@ -469,6 +469,7 @@ Go allows you to do more than what's shown here. Using Hugo's [`where` function]
</li>
{{ end }}
{{ end }}
</ul>
```
{{% /code %}}
content/templates/homepage-template.md → content/templates/homepage.md
+3 -3
View File
@@ -1,6 +1,6 @@
---
title: Homepage Template
linktitle:
title: The Homepage Template
linktitle: Homepage Template
description:
date: 2017-02-01
publishdate: 2017-02-01
@@ -9,7 +9,7 @@ categories: [templates]
tags: [homepage]
weight: 30
draft: false
aliases: [/layout/homepage/,/templates/homepage/]
aliases: [/layout/homepage/,/templates/homepage-template/]
toc: false
---
content/templates/lists.md
+2 -40
View File
@@ -29,29 +29,6 @@ The idea of a list page comes from the [hierarchical mental model of the web][me
![Image demonstrating a hierarchical website sitemap.](/images/site-hierarchy.svg)
```yaml
---
aliases:
- /doc/using-index-md/
lastmod: 2017-02-22
date: 2017-02-22
linktitle: Using _index.md
menu:
main:
parent: content
prev: /content/example
next: /themes/overview
notoc: true
title: Using _index.md
weight: 70
---
```
## List Defaults
### Default Templates
@@ -65,21 +42,6 @@ Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][]) ar
3. `layouts/_default/section.html`
4. `layouts/_default/list.html`
### Understanding `.Data.Pages`
### Taxonomy Lists
A Taxonomy will be rendered at /`PLURAL`/`TERM`/ (e.g.&nbsp;http://spf13.com/topics/golang/) from:
* /layouts/taxonomy/`SINGULAR`.html (e.g.&nbsp;`/layouts/taxonomy/topic.html`)
* /layouts/\_default/taxonomy.html
* /layouts/\_default/list.html
* /themes/`THEME`/layouts/taxonomy/`SINGULAR`.html
* /themes/`THEME`/layouts/\_default/taxonomy.html
* /themes/`THEME`/layouts/\_default/list.html
Note that a taxonomy list page can also have a content file with front matter, see [Source Organization](/overview/source-directory/).
### Taxonomy RSS
@@ -114,8 +76,8 @@ If `where` or `first` receives invalid input or a field name that doesn’t exis
[directorystructure]: /getting-started/directory-structure/
[homepage]: /templates/homepage-template/
[homepage]: /templates/homepage-template/
[homepage]: /templates/homepage/
[homepage]: /templates/homepage/
[limitkeyword]: https://www.techonthenet.com/sql/select_limit.php
[mentalmodel]: http://webstyleguide.com/wsg3/3-information-architecture/3-site-structure.html
[partials]: /templates/partials/
content/templates/lookup-order.md
+1 -1
View File
@@ -39,7 +39,7 @@ See examples of the lookup order for each of the Hugo template types:
[base]: /templates/base-templates-and-blocks/#base-template-lookup-order
[directory structure]: /getting-started/directory-structure/
[DRY]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
[home]: /templates/homepage-template/#homepage-template-lookup-order
[home]: /templates/homepage/#homepage-template-lookup-order
[rsslookup]: /templates/rss-templates/#rss-template-lookup-order
[sectionlookup]: /templates/section-templates/#section-template-lookup-order
[singlelookup]: templates/single-page-templates/#single-page-template-lookup-order
content/templates/taxonomy-templates.md
+9
View File
@@ -30,6 +30,15 @@ Taxonomy list page templates are lists and therefore have all the variables and
### Taxonomy List Template Lookup Order
A Taxonomy will be rendered at /`PLURAL`/`TERM`/ (e.g.&nbsp;http://spf13.com/topics/golang/) from:
* /layouts/taxonomy/`SINGULAR`.html (e.g.&nbsp;`/layouts/taxonomy/topic.html`)
* /layouts/\_default/taxonomy.html
* /layouts/\_default/list.html
* /themes/`THEME`/layouts/taxonomy/`SINGULAR`.html
* /themes/`THEME`/layouts/\_default/taxonomy.html
* /themes/`THEME`/layouts/\_default/list.html
## Taxonomy Terms Template
### Taxonomy Terms Templates Lookup Order
content/templates/template-debugging.md
+4 -6
View File
@@ -14,7 +14,6 @@ aliases: [/templates/debugging/]
toc: false
---
Here are some snippets you can add to your template to answer some common questions.
These snippets use the `printf` function available in all Go templates. This function is an alias to the Go function, [fmt.Printf](http://golang.org/pkg/fmt/).
@@ -38,7 +37,7 @@ This will print out the value of `.Permalink`:
{{% /code %}}
This will print out a list of all the variables scoped to the current context
(aka [The dot, "`.`"][thedot]).
(aka [The dot, "`.`"][primer]).
{{% code file="get-all-vars-current-context.sh" %}}
```golang
@@ -67,7 +66,7 @@ Check that you are passing variables in the `partial` function:
{{ 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][thedot].
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].
```
{{ partial "header" . }}
@@ -75,6 +74,5 @@ This example will render the header partial, but the header partial will not hav
The dot (`.`) is considered fundamental to understand Hugo templating. For more information, see the [Go Template Primer][primer].
[hometemplate]: /templates/homepage-template/
[primer]: /templates/go-template-primer/
[thedot]: /functions/the-dot/
[hometemplate]: /templates/homepage/
[primer]: /templates/go-templates/
content/themes/_index.md
+1 -1
View File
@@ -19,5 +19,5 @@ The Hugo community has created a large number of diverse themes, all of which ar
Hugo themes are powered by the excellent Go template library. If you are new to Go templates, see our [primer on Go templates][goprimer] and are structured in such a way to eliminate code duplication. They are easy to simultaneously customize while retaining upgradability with the upstream theme.
[goprimer]: /templates/go-template-primer/
[goprimer]: /templates/go-templates/
[hugothemes]: http://themes.gohugo.io/
content/tree.txt
+38 -32
View File
@@ -2,8 +2,8 @@
├── _index.md
├── about-hugo
│   ├── _index.md
│   ├── benefits-of-static.md
│   ├── hugo-features.md
│   ├── benefits.md
│   ├── features.md
│   ├── license.md
│   ├── roadmap.md
│   ├── what-is-hugo.md
@@ -15,27 +15,31 @@
│   ├── _index.md
│   ├── archetypes.md
│   ├── comments.md
│   ├── content-organization.md
│   ├── content-summaries.md
│   ├── content-types.md
│   ├── cross-references.md
│   ├── formats.md
│   ├── front-matter.md
│   ├── menus.md
│   ├── multilingual-mode.md
│   ├── multilingual.md
│   ├── organization.md
│   ├── sections.md
│   ├── shortcodes.md
│   ├── supported-content-formats.md
│   ├── table-of-contents.md
│   ├── taxonomies.md
│   └── url-management.md
├── contribute-to-hugo
│   ├── toc.md
│   └── urls.md
├── contribute
│   ├── _index.md
│   ├── add-your-site-to-the-showcase.md
│   ├── contribute-to-hugo-development.md
│   └── contribute-to-the-hugo-docs.md
│   ├── development.md
│   └── documentation.md
├── developer-tools
│   ├── _index.md
│   ├── editor-plugins.md
│   ├── frontends.md
│   ├── migrate-to-hugo.md
│   ├── other.md
│   ├── search.md
│   ├── starter-kits.md
│   └── syntax-highlighting.md
├── functions
│   ├── _index.md
@@ -43,10 +47,8 @@
│   ├── absurl.md
│   ├── after.md
│   ├── apply.md
│   ├── base64decode.md
│   ├── base64encode.md
│   ├── base64.md
│   ├── chomp.md
│   ├── count.md
│   ├── countrunes.md
│   ├── countwords.md
│   ├── dateformat.md
@@ -55,6 +57,7 @@
│   ├── dict.md
│   ├── echoparam.md
│   ├── emojify.md
│   ├── eq.md
│   ├── findre.md
│   ├── first.md
│   ├── get.md
@@ -81,6 +84,7 @@
│   ├── markdownify.md
│   ├── math.md
│   ├── md5.md
│   ├── now.md
│   ├── param.md
│   ├── partialcached.md
│   ├── plainify.md
@@ -90,12 +94,13 @@
│   ├── range.md
│   ├── readdir.md
│   ├── readfile.md
│   ├── rel.md
│   ├── rellangurl.md
│   ├── ref.md
│   ├── relLangURL.md
│   ├── relref.md
│   ├── relurl.md
│   ├── render.md
│   ├── replace.md
│   ├── replacere.md
│   ├── safecss.md
│   ├── safehtml.md
│   ├── safehtmlattr.md
@@ -103,8 +108,7 @@
│   ├── safeurl.md
│   ├── scratch.md
│   ├── seq.md
│   ├── sha1.md
│   ├── sha256.md
│   ├── sha.md
│   ├── shuffle.md
│   ├── singularize.md
│   ├── slice.md
@@ -113,7 +117,6 @@
│   ├── split.md
│   ├── string.md
│   ├── substr.md
│   ├── the-dot.md
│   ├── time.md
│   ├── title.md
│   ├── trim.md
@@ -121,15 +124,14 @@
│   ├── unix.md
│   ├── upper.md
│   ├── urlize.md
│   ├── where.md
│   └── with.md
│   └── where.md
├── getting-started
│   ├── _index.md
│   ├── basic-usage.md
│   ├── configuration.md
│   ├── directory-structure.md
│   ├── install-hugo.md
│   ├── installing.md
│   ├── quick-start.md
│   ├── usage.md
│   └── using-the-hugo-docs.md
├── hosting-and-deployment
│   ├── _index.md
@@ -137,7 +139,8 @@
│   ├── deployment-with-wercker.md
│   ├── hosting-on-bitbucket.md
│   ├── hosting-on-github.md
│   └── hosting-on-gitlab.md
│   ├── hosting-on-gitlab.md
│   └── hosting-on-netlify.md
├── mailing-list.md
├── news
│   ├── _index.md
@@ -247,13 +250,16 @@
│   ├── content-view-templates.md
│   ├── custom-404-page.md
│   ├── data-templates.md
│   ├── go-template-primer.md
│   ├── homepage-template.md
│   ├── lists-in-hugo.md
│   ├── go-templates.md
│   ├── homepage.md
│   ├── lists.md
│   ├── local-file-templates.md
│   ├── lookup-order.md
│   ├── menu-templates.md
│   ├── pagination.md
│   ├── partial-templates.md
│   ├── partials.md
│   ├── rendering-lists.md
│   ├── robots.md
│   ├── rss-templates.md
│   ├── section-templates.md
│   ├── shortcode-templates.md
@@ -263,8 +269,8 @@
│   └── template-debugging.md
├── themes
│   ├── _index.md
│   ├── creating-a-theme.md
│   ├── customizing-a-theme.md
│   ├── creating.md
│   ├── customizing.md
│   ├── installing-and-using-themes.md
│   └── theme-showcase.md
├── tree.txt
@@ -277,7 +283,7 @@
│   ├── creating-a-multilingual-site.md
│   ├── creating-a-new-theme.md
│   └── migrate-from-jekyll-to-hugo.md
└── variables-and-params
└── variables
├── _index.md
├── file-variables.md
├── other-variables.md
@@ -285,4 +291,4 @@
├── site-variables.md
└── taxonomy-variables.md
15 directories, 270 files
15 directories, 276 files
content/tutorials/creating-a-multilingual-site.md
-1
View File
@@ -12,7 +12,6 @@ authors: ["Rick Cogley"]
aliases: [/tutorials/create-a-multilingual-site/]
draft: false
hugoversion: 16
needsreview: true
---
{{% note %}}
content/tutorials/creating-a-new-theme.md
+36 -37
View File
@@ -12,7 +12,6 @@ aliases: []
hugoversion: 18.1
draft: false
toc: true
needsreview: true
---
## Introduction
@@ -105,7 +104,7 @@ Note that you can use this tutorial to create your set of non-content files unde
### Home
The home page, or landing page, is the first page that many visitors to a website will see. Often this is `/index.html`, located at the root URL of the website. Since Hugo writes files into the `./public/` tree, your home page will reside in file `./public/index.html`.
The homepage, or landing page, is the first page that many visitors to a website will see. Often this is `/index.html`, located at the root URL of the website. Since Hugo writes files into the `./public/` tree, your homepage will reside in file `./public/index.html`.
### Configure
@@ -155,7 +154,7 @@ A _Single_ template is used to render one piece of content. For example, an arti
A _List_ template renders a group of related content items. This could be a summary of recent postings, or all of the articles in a category. List templates can contain multiple groups (or categories).
The home page template is a special kind of List template. This is because Hugo assumes that your home page will act as a portal to all of the remaining content on your website.
The homepage template is a special kind of List template. This is because Hugo assumes that your homepage will act as a portal to all of the remaining content on your website.
#### Partial
@@ -203,7 +202,7 @@ Started building site
WARN: {date} {source} Unable to locate layout for homepage: [index.html _default/list.html]
WARN: {date} {source} "/" is rendered empty
=============================================================
Your rendered home page is blank: /index.html is zero-length
Your rendered homepage is blank: /index.html is zero-length
* Did you specify a theme on the command-line or in your
"config.toml" file? (Current theme: "")
=============================================================
@@ -257,7 +256,7 @@ If you look back at the output from the `hugo server` command, you'll notice tha
0 pages created
```
That's because Hugo doesn't count the home page, the 404 error page, or the RSS feed files as pages.
That's because Hugo doesn't count the homepage, the 404 error page, or the RSS feed files as pages.
### Serve
@@ -274,7 +273,7 @@ INFO: {date} {source} syncing static files to /
WARN: {date} {source} Unable to locate layout for homepage: [index.html _default/list.html]
WARN: {date} {source} "/" is rendered empty
=============================================================
Your rendered home page is blank: /index.html is zero-length
Your rendered homepage is blank: /index.html is zero-length
* Did you specify a theme on the command-line or in your
"config.toml" file? (Current theme: "")
=============================================================
@@ -310,9 +309,9 @@ WARN: {date} {source} Unable to locate layout for homepage: [index.html _default
The 404 warning is easy to explain &mdash; it's because we haven't created the template file `layouts/404.html`. Hugo uses this to render an HTML file which serves "page not found" errors. However, the 404 page is a topic for a separate tutorial.
Regarding the home page warning: the first layout Hugo looked for was `layouts/index.html`. Note that Hugo uses this file for the home page only.
Regarding the homepage warning: the first layout Hugo looked for was `layouts/index.html`. Note that Hugo uses this file for the homepage only.
It's good that Hugo lists the files it seeks, when we give it the verbose flag. For the home page, these files are `layouts/index.html` and `layouts/_default/list.html`. Later, we'll cover some rules which explain these paths (including their basenames). For now, just remember that Hugo couldn't find a template to use for the home page, and it said so.
It's good that Hugo lists the files it seeks, when we give it the verbose flag. For the homepage, these files are `layouts/index.html` and `layouts/_default/list.html`. Later, we'll cover some rules which explain these paths (including their basenames). For now, just remember that Hugo couldn't find a template to use for the homepage, and it said so.
All right! So, now &mdash; after these few steps &mdash; you have a working installation, and a website foundation you can build upon. All that's left is to add some content, as well as a theme to display it.
@@ -394,7 +393,7 @@ INFO: {date} {source} syncing static files to /tmp/mySite/public/
Started building site
WARN: {date} {source} "/" is rendered empty
=============================================================
Your rendered home page is blank: /index.html is zero-length
Your rendered homepage is blank: /index.html is zero-length
* Did you specify a theme on the command-line or in your
"config.toml" file? (Current theme: "zafta")
=============================================================
@@ -412,7 +411,7 @@ in 4 ms
Did you notice the output is different?
Two previous warning messages have disappeared, which contained the words "Unable to locate layout" for your home page and the 404 page. And, a new informational message tells us Hugo is accessing your theme's tree (`./themes/zafta/`).
Two previous warning messages have disappeared, which contained the words "Unable to locate layout" for your homepage and the 404 page. And, a new informational message tells us Hugo is accessing your theme's tree (`./themes/zafta/`).
Let's check the `./public/` directory to see what Hugo rendered:
@@ -438,20 +437,20 @@ drwxr-xr-x 2 {user} {group} 68 {date} js
#### Home
In a Hugo website, each kind of page is informed (primarily) by just one of the many different kinds of templates available; yet the home page is special, because it gets its own kind of template, and its own template file.
In a Hugo website, each kind of page is informed (primarily) by just one of the many different kinds of templates available; yet the homepage is special, because it gets its own kind of template, and its own template file.
Hugo uses template file `layouts/index.html` to render the home page's HTML. Although Hugo's documentation may state that this file is the home page's only required template, Hugo's earlier warning message showed it actually
Hugo uses template file `layouts/index.html` to render the homepage's HTML. Although Hugo's documentation may state that this file is the homepage's only required template, Hugo's earlier warning message showed it actually
looks for two different templates:
```bash
WARN: {date} {source} Unable to locate layout for homepage: [index.html _default/list.html]
```
#### Empty
When Hugo generated your theme, it included an empty home page template.
When Hugo generated your theme, it included an empty homepage template.
Whenever Hugo renders your website, it seeks that same template and uses it
to render the HTML for the home page. Currently, the template file is empty,
to render the HTML for the homepage. Currently, the template file is empty,
so the output HTML file is empty, too. Whenever we add rules to that template,
Hugo will use them in rendering the home page:
Hugo will use them in rendering the homepage:
```bash
$ find * -name index.html | xargs ls -l
-rw-r--r-- 1 {user} {group} 0 {date} public/index.html
@@ -542,7 +541,7 @@ $ hugo server --verbose
Press Ctrl+C to stop
```
Below is some sample output showing Hugo detecting a change in the home page template. (Actually, the change is the edit we're about to do.) Once it's rendered again, the web browser automatically reloads the page.
Below is some sample output showing Hugo detecting a change in the homepage template. (Actually, the change is the edit we're about to do.) Once it's rendered again, the web browser automatically reloads the page.
As I said above &mdash; it's amazing:)
@@ -558,7 +557,7 @@ INFO: {date} {source} syncing static files to /
Started building site
WARN: {date} {source} "/" is rendered empty
=============================================================
Your rendered home page is blank: /index.html is zero-length
Your rendered homepage is blank: /index.html is zero-length
* Did you specify a theme on the command-line or in your
"config.toml" file? (Current theme: "")
=============================================================
@@ -594,7 +593,7 @@ in 3 ms
```
## Home Template
The home page is one of the few special pages Hugo renders automatically. As mentioned earlier, it looks in your theme's `layouts/` tree for one of two files:
The homepage is one of the few special pages Hugo renders automatically. As mentioned earlier, it looks in your theme's `layouts/` tree for one of two files:
1. `index.html`
1. `_default/list.html`
@@ -603,7 +602,7 @@ We could edit the default template, but a good design principle is to edit the m
### Static
Right now, your home page is empty because you've added no content, and because its template includes no logic. Let's change that by adding some text to your home page template (`layouts/index.html`):
Right now, your homepage is empty because you've added no content, and because its template includes no logic. Let's change that by adding some text to your homepage template (`layouts/index.html`):
```html
$ vi themes/zafta/layouts/index.html
@@ -653,13 +652,13 @@ $ cat public/index.html
### Dynamic
A ***dynamic*** home page? Because Hugo is a _static website_ generator, the word _dynamic_ seems odd, doesn't it? But this means arranging for your home page to reflect the content in your website automatically, each time Hugo renders it.
A ***dynamic*** homepage? Because Hugo is a _static website_ generator, the word _dynamic_ seems odd, doesn't it? But this means arranging for your homepage to reflect the content in your website automatically, each time Hugo renders it.
To accomplish that, later we'll add an iterator to your home page template.
To accomplish that, later we'll add an iterator to your homepage template.
## Article
Now that Hugo is successfully rendering your home page with static content, let's add more pages to your website. We'll display some new articles as a list on your home page; and we'll display each article on its own page, too.
Now that Hugo is successfully rendering your homepage with static content, let's add more pages to your website. We'll display some new articles as a list on your homepage; and we'll display each article on its own page, too.
Hugo has a command to generate an entry skeleton for new content,
just as it does for websites and themes:
@@ -773,7 +772,7 @@ $ find public -type f -name '*.html' | xargs ls -l
```
The new pages are empty, because Hugo rendered their HTML from empty
template files. The home page doesn't show us the new content, either:
template files. The homepage doesn't show us the new content, either:
```html
$ cat public/index.html
@@ -789,16 +788,16 @@ So, we have to edit the templates, in order to pick up the articles.
### Single & List
Here again I'll discuss three kinds of Hugo templates. One kind is the home page template we edited previously; it's applicable only to the home page. Another kind is Single templates, which render output for just one content file. The third kind are List templates, which group multiple pieces of content before rendering output.
Here again I'll discuss three kinds of Hugo templates. One kind is the homepage template we edited previously; it's applicable only to the homepage. Another kind is Single templates, which render output for just one content file. The third kind are List templates, which group multiple pieces of content before rendering output.
It's important to note that, generally, List templates (except the home page template) are named `list.html`; and Single templates are named `single.html`.
It's important to note that, generally, List templates (except the homepage template) are named `list.html`; and Single templates are named `single.html`.
Hugo also has three other kinds of templates: Partials, _Content Views_, and _Terms_. We'll give examples of some Partial templates; but otherwise,
we won't go into much detail about these.
### Home
You'll want your home page to list the articles you just created. So, let's alter its template file (`layouts/index.html`) to show them. Hugo runs each template's logic whenever it renders that template's web page (of course):
You'll want your homepage to list the articles you just created. So, let's alter its template file (`layouts/index.html`) to show them. Hugo runs each template's logic whenever it renders that template's web page (of course):
```html
$ vi themes/zafta/layouts/index.html
@@ -892,9 +891,9 @@ $ cat public/index.html
### All Done
Congratulations! Your home page shows the titles of your two articles, along with the links to them. The articles themselves are still empty. But, let's take a moment to appreciate what we've done, so far!
Congratulations! Your homepage shows the titles of your two articles, along with the links to them. The articles themselves are still empty. But, let's take a moment to appreciate what we've done, so far!
Your home page template (`layouts/index.html`) now renders output dynamically. Believe it or not, by inserting the range command inside those doubled curly braces, you've learned everything you need to know &mdash; essentially &mdash; about developing a theme.
Your homepage template (`layouts/index.html`) now renders output dynamically. Believe it or not, by inserting the range command inside those doubled curly braces, you've learned everything you need to know &mdash; essentially &mdash; about developing a theme.
All that's left is understanding which of your templates renders each content file, and becoming more familiar with the commands for the template engine.
@@ -1047,13 +1046,13 @@ lobortis risus id nisi rutrum, at iaculis.</p>
</html>
```
Again, notice that your rendered article files have content. You can run `hugo server` and use your browser to confirm this. You should see your home page, and it should contain the titles of both articles. Each title should be a link to its respective article.
Again, notice that your rendered article files have content. You can run `hugo server` and use your browser to confirm this. You should see your homepage, and it should contain the titles of both articles. Each title should be a link to its respective article.
Each article should be displayed fully on its own page. And at the bottom of each article, you should see a link which takes you back to your home page.
Each article should be displayed fully on its own page. And at the bottom of each article, you should see a link which takes you back to your homepage.
### Article List
Your home page still lists your most recent articles. However &mdash; remember, from above, that I mentioned an empty file,
Your homepage still lists your most recent articles. However &mdash; remember, from above, that I mentioned an empty file,
`./public/article/index.html`?
Let's make that show a list of *all* of your articles rather than just the most recent ten.
@@ -1214,7 +1213,7 @@ Oh, well. &mdash; Did you notice that your page wasn't rendered at the top level
### Home
One other thing &mdash; let's take a look at your home page:
One other thing &mdash; let's take a look at your homepage:
```html
$ cat public/index.html
@@ -1229,7 +1228,7 @@ $ cat public/index.html
```
Did you notice that the About link is listed with your articles?
That's not exactly where we want it; so, let's edit your home page template
That's not exactly where we want it; so, let's edit your homepage template
(`layouts/index.html`):
```html
@@ -1291,11 +1290,11 @@ $ cat public/index.html
</html>
```
Good! This time, your home page has two Sections: "article" and "page", and each Section contains the correct set of headings and links.
Good! This time, your homepage has two Sections: "article" and "page", and each Section contains the correct set of headings and links.
## Template Sharing
If you've been following along on your computer, you might've noticed that your home page doesn't show its title in your browser, although both of your article pages do. That's because we didn't add your home page's title to its template (`layouts/index.html`). That would be easy to do &mdash; but instead, let's look at a better option.
If you've been following along on your computer, you might've noticed that your homepage doesn't show its title in your browser, although both of your article pages do. That's because we didn't add your homepage's title to its template (`layouts/index.html`). That would be easy to do &mdash; but instead, let's look at a better option.
We can put the common information into a shared template. These reside in the `layouts/partials/` directory.
@@ -1330,7 +1329,7 @@ Any `partial` is called relative to its conventional location `layouts/partials/
#### From Home
Let's change your home page template (`layouts/index.html`) in order to use the new header Partial we just created:
Let's change your homepage template (`layouts/index.html`) in order to use the new header Partial we just created:
```html
$ vi themes/zafta/layouts/index.html
@@ -1352,7 +1351,7 @@ $ vi themes/zafta/layouts/index.html
:wq
```
Render your website and verify the results. Now, the title on your home page should be "My New Hugo Site". This comes from the "title" variable in the `./config.toml` file.
Render your website and verify the results. Now, the title on your homepage should be "My New Hugo Site". This comes from the "title" variable in the `./config.toml` file.
#### From Default
content/variables/_index.md
+1 -1
View File
@@ -15,4 +15,4 @@ toc: false
[Go templates][], the backbone of Hugo templating, are context based, and Hugo makes a large number of values available to you as you're creating views for your website. The following variables and params provide convenient means to displaying your content with Hugo's powerful templating engine.
[Go templates]: /templates/go-template-primer/ "Understand context in Go templates by learning the language's fundamental templating functions."
[Go templates]: /templates/go-templates/ "Understand context in Go templates by learning the language's fundamental templating functions."
content/variables/file-variables.md
+2 -2
View File
@@ -17,7 +17,7 @@ notesforauthors:
Hugo provides the ability to traverse your website's files on your server, including the local `Hugo server`. You can access file-system-related data for a piece of content via the `.File` variable.
{{% note "Local File Templates" %}}
{{% note "Rendering Local Files" %}}
For information on creating shortcodes and templates that tap into Hugo's file-related feature set, see [Local File Templates](/templates/local-file-templates/).
{{% /note %}}
@@ -39,7 +39,7 @@ The `.File` object contains the following fields:
: The file extension of the content file (e.g., `md`). This can also be called using `.File.Extension`.
`.File.Lang`
: The language associated with the given file if Hugo's [Multilingual][] features are enabled (e.g., `en`)
: The language associated with the given file if Hugo's [Multilingual features][multilingual] are enabled (e.g., `en`)
`.File.Dir`
: Given the path `content/posts/dir1/dir2/`, the relative directory path of the content file will be returned (e.g., `posts/dir1/dir2/`)
content/variables/other-variables.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
title: Shortcode, Git, and Hugo Variables
title: Shortcode, Git, Menu, and Hugo Variables
linktitle: Shortcode, Git, and Hugo Variables
description:
date: 2017-02-01
content/variables/page-variables.md
+1 -1
View File
@@ -46,7 +46,7 @@ See [`.Scratch`](/functions/scratch/) for page-scoped writable variables.
: see [Hugo Variables](/variables/other/).
`.IsHome`
: `true` in the context of the [home page](/templates/homepage-template/).
: `true` in the context of the [home page](/templates/homepage/).
`.IsNode`
: always `false` for regular content pages.
content/variables/taxonomy-variables.md
+2 -3
View File
@@ -1,7 +1,7 @@
---
title: Taxonomy Variables
linktitle:
description:
description: Taxonomy pages are of type `Page` and have all page-, site-, and list-level variables available to them. However, taxonomy terms templates have additional variables available to their templates.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
@@ -12,7 +12,6 @@ weight: 30
aliases: []
toc: true
needsreview: true
notesforauthors:
---
### Taxonomy Terms Page Variables
@@ -44,7 +43,7 @@ Note that `.Data.Terms.Alphabetical` and `.Data.Terms.ByCount` can also be rever
### Using `.Site.Taxonomies` Outside of Taxonomy Templates
The `.Site.Taxonomies` variable holds all the taxonomies that defined site-wide. It is a map of the taxonomy name to a list of its values (e.g., "tags" -> ["tag1", "tag2", "tag3"]). Each value, though, is not a string but rather a **Taxonomy variable**.
The `.Site.Taxonomies` variable holds all the taxonomies defined site-wide. `.Site.Taxonomies` is a map of the taxonomy name to a list of its values (e.g., `"tags" -> ["tag1", "tag2", "tag3"]``). Each value, though, is not a string but rather a *Taxonomy variable*.
### The Taxonomy Variable
themes/hugodocs/layouts/_default/section.html
+5 -2
View File
@@ -12,10 +12,13 @@
</header>
<div class="body-copy">
{{.Content}}
{{partial "contents-list.html" .}}
{{ if ne .Section "functions"}}
{{- partial "contents-list.html" . -}}
{{ else }}
{{- partial "functions-quick-reference.html" . -}}
{{ end }}
</div>
</div>
{{partial "content-footer.html" . }}
{{partial "table-of-contents.html" . }}
</main>
{{ end }}
themes/hugodocs/layouts/partials/functions-quick-reference.html
+6
View File
@@ -0,0 +1,6 @@
<dl class="quick-reference">
{{ range .Data.Pages }}
<dt><code><a href="{{.Permalink}}">{{.LinkTitle}}</a></code></dt>
<dd>{{.Description}}</dd>
{{ end }}
</dl>
themes/hugodocs/layouts/section/functions.html
-11
View File
@@ -1,11 +0,0 @@
{{define "main"}}
<main class="main showcase-list">
<div class="content">
<header class="content-header">
{{partial "breadcrumb.html" . }}
<h1 class="page-title" id="{{ .Title | urlize }}">{{ .Title | markdownify }}</h1>
{{.Content}}
</header>
</div>
</main>
{{end}}