mirror of
https://github.com/gohugoio/hugo.git
synced 2024-07-04 16:21:57 +00:00
doc: Strip trailing whitespace; other revisions
Make some random and non-comprehensive changes to the template functions documentation to make them more consistent.
This commit is contained in:
Anthony Fok
parent
b0416e9bef
commit
5505ac0d72
|
|
@ -80,7 +80,7 @@ Following is a list of Hugo-defined variables that you can configure and their c
|
|||
# include content with publishdate in the future
|
||||
buildFuture: false
|
||||
# enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs.
|
||||
relativeURLs: false
|
||||
relativeURLs: false
|
||||
canonifyURLs: false
|
||||
# config file (default is path/config.yaml|json|toml)
|
||||
config: "config.toml"
|
||||
|
|
|
|||
|
|
@ -15,7 +15,9 @@ weight: 100
|
|||
---
|
||||
|
||||
When using Hugo with [GitHub Pages](http://pages.github.com/), you can provide
|
||||
your own template for a [custom 404 error page](https://help.github.com/articles/custom-404-pages/) by creating a 404.html template file in your `/layouts` folder. When Hugo generates your site, the `404.html` file will be placed in the root.
|
||||
your own template for a [custom 404 error page](https://help.github.com/articles/custom-404-pages/)
|
||||
by creating a 404.html template file in your `/layouts` folder.
|
||||
When Hugo generates your site, the `404.html` file will be placed in the root.
|
||||
|
||||
404 pages are of the type **"node"** and have all the [node
|
||||
variables](/layout/variables/) available to use in the templates.
|
||||
|
|
@ -45,7 +47,7 @@ This is a basic example of a 404.html template:
|
|||
|
||||
Your 404.html file can be set to load automatically when a visitor enters a mistaken URL path, dependent upon the web serving environment you are using. For example:
|
||||
|
||||
* _Github Pages_ - it's automatic.
|
||||
* _GitHub Pages_ - it's automatic.
|
||||
* _Apache_ - one way is to specify `ErrorDocument 404 /404.html` in an `.htaccess` file in the root of your site.
|
||||
* _Nginx_ - you might specify `error_page 404 = /404.html;` in your `nginx.conf` file.
|
||||
* _Amazon AWS S3_ - when setting a bucket up for static web serving, you can specify the error file.
|
||||
|
|
|
|||
|
|
@ -52,13 +52,13 @@ e.g.
|
|||
|
||||
|
||||
### echoParam
|
||||
If parameter is set, then echo it.
|
||||
Prints a parameter if it is set.
|
||||
|
||||
e.g. `{{echoParam .Params "project_url" }}`
|
||||
e.g. `{{ echoParam .Params "project_url" }}`
|
||||
|
||||
|
||||
### eq
|
||||
Return true if the parameters are equal.
|
||||
Returns true if the parameters are equal.
|
||||
|
||||
e.g.
|
||||
|
||||
|
|
@ -66,7 +66,7 @@ e.g.
|
|||
|
||||
|
||||
### first
|
||||
Slices an array to only the first X elements.
|
||||
Slices an array to only the first _N_ elements.
|
||||
|
||||
Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
|
||||
|
||||
|
|
@ -77,7 +77,7 @@ e.g.
|
|||
{{ end }}
|
||||
|
||||
### last
|
||||
Slices an array to only the last X elements.
|
||||
Slices an array to only the last _N_ elements.
|
||||
|
||||
Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
|
||||
|
||||
|
|
@ -88,9 +88,8 @@ e.g.
|
|||
{{ end }}
|
||||
|
||||
### after
|
||||
Slices an array to only the items after the Xth item. Use this in
|
||||
combination with `first` use both halves of an array split a item
|
||||
X.
|
||||
Slices an array to only the items after the <em>N</em>th item. Use this in combination
|
||||
with `first` to use both halves of an array split at item _N_.
|
||||
|
||||
Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
|
||||
|
||||
|
|
@ -114,7 +113,9 @@ e.g.
|
|||
|
||||
|
||||
### in
|
||||
Checks if an element is in an array (or slice) and returns a boolean. The elements supported are strings, integers and floats (only float64 will match as expected). In addition, it can also check if a substring exists in a string.
|
||||
Checks if an element is in an array (or slice) and returns a boolean.
|
||||
The elements supported are strings, integers and floats (only float64 will match as expected).
|
||||
In addition, it can also check if a substring exists in a string.
|
||||
|
||||
e.g.
|
||||
|
||||
|
|
@ -126,9 +127,11 @@ or
|
|||
|
||||
|
||||
### intersect
|
||||
Given two arrays (or slices), this function will return the common elements in the arrays. The elements supported are strings, integers and floats (only float64).
|
||||
Given two arrays (or slices), this function will return the common elements in the arrays.
|
||||
The elements supported are strings, integers and floats (only float64).
|
||||
|
||||
A useful example of this functionality is a 'similar posts' block. Create a list of links to posts where any of the tags in the current post match any tags in other posts.
|
||||
A useful example of this functionality is a 'similar posts' block.
|
||||
Create a list of links to posts where any of the tags in the current post match any tags in other posts.
|
||||
|
||||
e.g.
|
||||
|
||||
|
|
@ -146,14 +149,14 @@ e.g.
|
|||
|
||||
|
||||
### isset
|
||||
Return true if the parameter is set.
|
||||
Returns true if the parameter is set.
|
||||
Takes either a slice, array or channel and an index or a map and a key as input.
|
||||
|
||||
e.g. `{{ if isset .Params "project_url" }} {{ index .Params "project_url" }}{{ end }}`
|
||||
|
||||
### seq
|
||||
|
||||
Seq creates a sequence of integers. It's named and used as GNU's seq.
|
||||
Creates a sequence of integers. It's named and used as GNU's seq.
|
||||
|
||||
Some examples:
|
||||
|
||||
|
|
@ -164,7 +167,10 @@ Some examples:
|
|||
* `1 -2` => `1, 0, -1, -2`
|
||||
|
||||
### sort
|
||||
Sorts maps, arrays and slices, returning a sorted slice. A sorted array of map values will be returned, with the keys eliminated. There are two optional arguments, which are `sortByField` and `sortAsc`. If left blank, sort will sort by keys (for maps) in ascending order.
|
||||
Sorts maps, arrays and slices, returning a sorted slice.
|
||||
A sorted array of map values will be returned, with the keys eliminated.
|
||||
There are two optional arguments, which are `sortByField` and `sortAsc`.
|
||||
If left blank, sort will sort by keys (for maps) in ascending order.
|
||||
|
||||
Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
|
||||
|
||||
|
|
@ -321,30 +327,32 @@ e.g., `{{chomp "<p>Blockhead</p>\n"` → `"<p>Blockhead</p>"`
|
|||
|
||||
|
||||
### dateFormat
|
||||
Converts the textual representation of the datetime into the other form or returns it of Go `time.Time` type value. These are formatted with the layout string.
|
||||
Converts the textual representation of the datetime into the other form or returns it of Go `time.Time` type value.
|
||||
These are formatted with the layout string.
|
||||
|
||||
e.g. `{{ dateFormat "Monday, Jan 2, 2006" "2015-01-21" }}` →"Wednesday, Jan 21, 2015"
|
||||
|
||||
|
||||
### highlight
|
||||
Take a string of code and a language, uses Pygments to return the syntax highlighted code in HTML. Used in the [highlight shortcode](/extras/highlighting/).
|
||||
Takes a string of code and a language, uses Pygments to return the syntax highlighted code in HTML.
|
||||
Used in the [highlight shortcode](/extras/highlighting/).
|
||||
|
||||
|
||||
### lower
|
||||
Convert all characters in string to lowercase.
|
||||
Converts all characters in string to lowercase.
|
||||
|
||||
e.g. `{{lower "BatMan"}}` → "batman"
|
||||
|
||||
|
||||
### markdownify
|
||||
|
||||
This will run the string through the Markdown processesor. The result will be declared as "safe" so Go templates will not filter it.
|
||||
Runs the string through the Markdown processesor. The result will be declared as "safe" so Go templates will not filter it.
|
||||
|
||||
e.g. `{{ .Title | markdownify }}`
|
||||
|
||||
|
||||
### replace
|
||||
Replace all occurences of the search string with the replacement string.
|
||||
Replaces all occurrences of the search string with the replacement string.
|
||||
|
||||
e.g. `{{ replace "Batman and Robin" "Robin" "Catwoman" }}` → "Batman and Catwoman"
|
||||
|
||||
|
|
@ -407,8 +415,9 @@ CSS or URL context.
|
|||
|
||||
### slicestr
|
||||
|
||||
Slicing in Slicestr is done by specifying a half-open range with two indices, start and end. 1 and 4 creates a slice including elements 1 through 3.
|
||||
The end index can be omitted, it defaults to the string's length.
|
||||
Slicing in `slicestr` is done by specifying a half-open range with two indices, `start` and `end`.
|
||||
For example, 1 and 4 creates a slice including elements 1 through 3.
|
||||
The `end` index can be omitted; it defaults to the string's length.
|
||||
|
||||
e.g.
|
||||
|
||||
|
|
@ -417,18 +426,18 @@ e.g.
|
|||
|
||||
### substr
|
||||
|
||||
Substr extracts parts of a string, beginning at the character at the specified
|
||||
position, and returns the specified number of characters.
|
||||
Extracts parts of a string, beginning at the character at the specified
|
||||
position, and returns the specified number of characters.
|
||||
|
||||
It normally takes two parameters: `start` and `length`.
|
||||
It can also take one parameter: `start`, i.e. `length` is omitted, in which case
|
||||
the substring starting from start until the end of the string will be returned.
|
||||
It normally takes two parameters: `start` and `length`.
|
||||
It can also take one parameter: `start`, i.e. `length` is omitted, in which case
|
||||
the substring starting from start until the end of the string will be returned.
|
||||
|
||||
To extract characters from the end of the string, use a negative start number.
|
||||
To extract characters from the end of the string, use a negative start number.
|
||||
|
||||
In addition, borrowing from the extended behavior described at http://php.net/substr,
|
||||
if `length` is given and is negative, then that many characters will be omitted from
|
||||
the end of string.
|
||||
In addition, borrowing from the extended behavior described at http://php.net/substr,
|
||||
if `length` is given and is negative, then that many characters will be omitted from
|
||||
the end of string.
|
||||
|
||||
e.g.
|
||||
|
||||
|
|
@ -436,26 +445,26 @@ e.g.
|
|||
* `{{substr "BatMan" 3 3}}` → "Man"
|
||||
|
||||
### title
|
||||
Convert all characters in string to titlecase.
|
||||
Converts all characters in string to titlecase.
|
||||
|
||||
e.g. `{{title "BatMan"}}` → "Batman"
|
||||
|
||||
|
||||
### trim
|
||||
Trim returns a slice of the string with all leading and trailing characters contained in cutset removed.
|
||||
Returns a slice of the string with all leading and trailing characters contained in cutset removed.
|
||||
|
||||
e.g. `{{ trim "++Batman--" "+-" }}` → "Batman"
|
||||
|
||||
|
||||
### upper
|
||||
Convert all characters in string to uppercase.
|
||||
Converts all characters in string to uppercase.
|
||||
|
||||
e.g. `{{upper "BatMan"}}` → "BATMAN"
|
||||
|
||||
|
||||
|
||||
|
||||
## Urls
|
||||
## URLs
|
||||
|
||||
### absURL, relURL
|
||||
|
||||
|
|
|
|||
|
|
@ -92,9 +92,8 @@ can have different RSS files for each section and taxonomy.
|
|||
|
||||
## Variables
|
||||
|
||||
List pages are of the type "node" and have all the [node
|
||||
variables](/templates/variables/) and [site
|
||||
variables](/templates/variables/) available to use in the templates.
|
||||
List pages are of the type "node" and have all the [node variables](/templates/variables/)
|
||||
and [site variables](/templates/variables/) available to use in the templates.
|
||||
|
||||
Taxonomy pages will additionally have:
|
||||
|
||||
|
|
@ -146,7 +145,7 @@ defined.
|
|||
|
||||
## Ordering Content
|
||||
|
||||
In the case of Hugo each list will render the content based on metadata provided in the [front
|
||||
In the case of Hugo, each list will render the content based on metadata provided in the [front
|
||||
matter](/content/front-matter/). See [ordering content](/content/ordering/) for more information.
|
||||
|
||||
Here are a variety of different ways you can order the content items in
|
||||
|
|
@ -306,11 +305,11 @@ your list templates:
|
|||
|
||||
### Reversing Key Order
|
||||
|
||||
The ordering of the groups is performed by keys in alpha-numeric order (A–Z,
|
||||
The ordering of the groups is performed by keys in alphanumeric order (A–Z,
|
||||
1–100) and in reverse chronological order (newest first) for dates.
|
||||
|
||||
While these are logical defaults, they are not always the desired order. There
|
||||
are two different syntaxes to change the order, they both work the same way, so
|
||||
are two different syntaxes to change the order; they both work the same way, so
|
||||
it’s really just a matter of preference.
|
||||
|
||||
#### Reverse method
|
||||
|
|
@ -334,7 +333,7 @@ it’s really just a matter of preference.
|
|||
|
||||
Because Grouping returns a key and a slice of pages, all of the ordering methods listed above are available.
|
||||
|
||||
In this example I’ve ordered the groups in chronological order and the content
|
||||
In this example, I’ve ordered the groups in chronological order and the content
|
||||
within each group in alphabetical order by title.
|
||||
|
||||
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
|
||||
|
|
@ -352,38 +351,39 @@ within each group in alphabetical order by title.
|
|||
## Filtering & Limiting Content
|
||||
|
||||
Sometimes you only want to list a subset of the available content. A common
|
||||
request is to only display “Posts” on the homepage. Using the `where` function
|
||||
request is to only display “Posts” on the homepage. Using the `where` function,
|
||||
you can do just that.
|
||||
|
||||
### First
|
||||
### `first`
|
||||
|
||||
`first` works like the `limit` keyword in SQL. It reduces the array to only the
|
||||
first X elements. It takes the array and number of elements as input.
|
||||
first _N_ elements. It takes the array and number of elements as input.
|
||||
|
||||
{{ range first 10 .Data.Pages }}
|
||||
{{ .Render "summary"}}
|
||||
{{ .Render "summary" }}
|
||||
{{ end }}
|
||||
|
||||
### Where
|
||||
### `where`
|
||||
|
||||
`where` works in a similar manner to the `where` keyword in SQL. It selects all
|
||||
elements of the slice that match the provided field and value. It takes three
|
||||
arguments 'array or slice of maps or structs', 'key or field name' and 'match
|
||||
value'
|
||||
arguments: 'array or slice of maps or structs', 'key or field name' and 'match
|
||||
value'.
|
||||
|
||||
{{ range where .Data.Pages "Section" "post" }}
|
||||
{{ .Content}}
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
|
||||
### First & Where Together
|
||||
### `first` & `where` Together
|
||||
|
||||
Using both together can be very powerful.
|
||||
|
||||
{{ range first 5 (where .Data.Pages "Section" "post") }}
|
||||
{{ .Content}}
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
|
||||
If `where` or `first` receives invalid input or a field name that doesn’t exist they will provide an error and stop site generation.
|
||||
If `where` or `first` receives invalid input or a field name that doesn’t exist,
|
||||
it will return an error and stop site generation.
|
||||
|
||||
These are both template functions and work on not only
|
||||
[lists](/templates/list/), but [taxonomies](/taxonomies/displaying/),
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@ compatibility.
|
|||
|
||||
Everything in the static directory will be copied directly into the final site
|
||||
when rendered. No structure is provided here to enable complete freedom. It is
|
||||
common to organize the static content into
|
||||
common to organize the static content into:
|
||||
|
||||
/css
|
||||
/js
|
||||
|
|
|
|||
|
|
@ -50,6 +50,6 @@ If the archetype that ships with the theme for a given content type (or all cont
|
|||
|
||||
## Beware of the default
|
||||
|
||||
**Default** is a very powerful force in Hugo... Especially as it pertains to overwriting theme files. If a default is located in the local archetype directory or `/layouts/_default/` directory, it will be used instead of any of the similar files in the theme.
|
||||
**Default** is a very powerful force in Hugo, especially as it pertains to overwriting theme files. If a default is located in the local archetype directory or `/layouts/_default/` directory, it will be used instead of any of the similar files in the theme.
|
||||
|
||||
It is usually better to override specific files rather than using the default in your working directory.
|
||||
|
|
|
|||
Loading…
Reference in a new issue