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 2015-08-04 12:00:08 -06:00
parent b0416e9bef
commit 5505ac0d72
29 changed files with 217 additions and 206 deletions

View file

@ -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 # include content with publishdate in the future
buildFuture: false buildFuture: false
# enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. # 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 canonifyURLs: false
# config file (default is path/config.yaml|json|toml) # config file (default is path/config.yaml|json|toml)
config: "config.toml" config: "config.toml"

View file

@ -15,7 +15,9 @@ weight: 100
--- ---
When using Hugo with [GitHub Pages](http://pages.github.com/), you can provide 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 404 pages are of the type **"node"** and have all the [node
variables](/layout/variables/) available to use in the templates. 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: 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. * _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. * _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. * _Amazon AWS S3_ - when setting a bucket up for static web serving, you can specify the error file.

View file

@ -52,13 +52,13 @@ e.g.
### echoParam ### 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 ### eq
Return true if the parameters are equal. Returns true if the parameters are equal.
e.g. e.g.
@ -66,7 +66,7 @@ e.g.
### first ### 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/) Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
@ -77,7 +77,7 @@ e.g.
{{ end }} {{ end }}
### last ### 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/) Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
@ -88,9 +88,8 @@ e.g.
{{ end }} {{ end }}
### after ### after
Slices an array to only the items after the Xth item. Use this in Slices an array to only the items after the <em>N</em>th item. Use this in combination
combination with `first` use both halves of an array split a item with `first` to use both halves of an array split at item _N_.
X.
Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/) Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
@ -114,7 +113,9 @@ e.g.
### in ### 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. e.g.
@ -126,9 +127,11 @@ or
### intersect ### 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. e.g.
@ -146,14 +149,14 @@ e.g.
### isset ### 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. 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 }}` e.g. `{{ if isset .Params "project_url" }} {{ index .Params "project_url" }}{{ end }}`
### seq ### 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: Some examples:
@ -164,7 +167,10 @@ Some examples:
* `1 -2` => `1, 0, -1, -2` * `1 -2` => `1, 0, -1, -2`
### sort ### 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/) 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 ### 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" e.g. `{{ dateFormat "Monday, Jan 2, 2006" "2015-01-21" }}` →"Wednesday, Jan 21, 2015"
### highlight ### 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 ### lower
Convert all characters in string to lowercase. Converts all characters in string to lowercase.
e.g. `{{lower "BatMan"}}` → "batman" e.g. `{{lower "BatMan"}}` → "batman"
### markdownify ### 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 }}` e.g. `{{ .Title | markdownify }}`
### replace ### 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" e.g. `{{ replace "Batman and Robin" "Robin" "Catwoman" }}` → "Batman and Catwoman"
@ -407,8 +415,9 @@ CSS or URL context.
### slicestr ### 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. Slicing in `slicestr` is done by specifying a half-open range with two indices, `start` and `end`.
The end index can be omitted, it defaults to the string's length. 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. e.g.
@ -417,18 +426,18 @@ e.g.
### substr ### substr
Substr extracts parts of a string, beginning at the character at the specified Extracts parts of a string, beginning at the character at the specified
position, and returns the specified number of characters. position, and returns the specified number of characters.
It normally takes two parameters: `start` and `length`. It normally takes two parameters: `start` and `length`.
It can also take one parameter: `start`, i.e. `length` is omitted, in which case 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. 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, 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 if `length` is given and is negative, then that many characters will be omitted from
the end of string. the end of string.
e.g. e.g.
@ -436,26 +445,26 @@ e.g.
* `{{substr "BatMan" 3 3}}` → "Man" * `{{substr "BatMan" 3 3}}` → "Man"
### title ### title
Convert all characters in string to titlecase. Converts all characters in string to titlecase.
e.g. `{{title "BatMan"}}` → "Batman" e.g. `{{title "BatMan"}}` → "Batman"
### trim ### 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" e.g. `{{ trim "++Batman--" "+-" }}` → "Batman"
### upper ### upper
Convert all characters in string to uppercase. Converts all characters in string to uppercase.
e.g. `{{upper "BatMan"}}` → "BATMAN" e.g. `{{upper "BatMan"}}` → "BATMAN"
## Urls ## URLs
### absURL, relURL ### absURL, relURL

View file

@ -92,9 +92,8 @@ can have different RSS files for each section and taxonomy.
## Variables ## Variables
List pages are of the type "node" and have all the [node List pages are of the type "node" and have all the [node variables](/templates/variables/)
variables](/templates/variables/) and [site and [site variables](/templates/variables/) available to use in the templates.
variables](/templates/variables/) available to use in the templates.
Taxonomy pages will additionally have: Taxonomy pages will additionally have:
@ -146,7 +145,7 @@ defined.
## Ordering Content ## 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. 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 Here are a variety of different ways you can order the content items in
@ -306,11 +305,11 @@ your list templates:
### Reversing Key Order ### Reversing Key Order
The ordering of the groups is performed by keys in alpha-numeric order (AZ, The ordering of the groups is performed by keys in alphanumeric order (AZ,
1100) and in reverse chronological order (newest first) for dates. 1100) and in reverse chronological order (newest first) for dates.
While these are logical defaults, they are not always the desired order. There 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
its really just a matter of preference. its really just a matter of preference.
#### Reverse method #### Reverse method
@ -334,7 +333,7 @@ its 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. Because Grouping returns a key and a slice of pages, all of the ordering methods listed above are available.
In this example Ive ordered the groups in chronological order and the content In this example, Ive ordered the groups in chronological order and the content
within each group in alphabetical order by title. within each group in alphabetical order by title.
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }} {{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
@ -352,38 +351,39 @@ within each group in alphabetical order by title.
## Filtering & Limiting Content ## Filtering & Limiting Content
Sometimes you only want to list a subset of the available content. A common 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. you can do just that.
### First ### `first`
`first` works like the `limit` keyword in SQL. It reduces the array to only the `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 }} {{ range first 10 .Data.Pages }}
{{ .Render "summary"}} {{ .Render "summary" }}
{{ end }} {{ end }}
### Where ### `where`
`where` works in a similar manner to the `where` keyword in SQL. It selects all `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 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 arguments: 'array or slice of maps or structs', 'key or field name' and 'match
value' value'.
{{ range where .Data.Pages "Section" "post" }} {{ range where .Data.Pages "Section" "post" }}
{{ .Content}} {{ .Content }}
{{ end }} {{ end }}
### First & Where Together ### `first` & `where` Together
Using both together can be very powerful. Using both together can be very powerful.
{{ range first 5 (where .Data.Pages "Section" "post") }} {{ range first 5 (where .Data.Pages "Section" "post") }}
{{ .Content}} {{ .Content }}
{{ end }} {{ end }}
If `where` or `first` receives invalid input or a field name that doesnt exist they will provide an error and stop site generation. If `where` or `first` receives invalid input or a field name that doesnt exist,
it will return an error and stop site generation.
These are both template functions and work on not only These are both template functions and work on not only
[lists](/templates/list/), but [taxonomies](/taxonomies/displaying/), [lists](/templates/list/), but [taxonomies](/taxonomies/displaying/),

View file

@ -55,7 +55,7 @@ compatibility.
Everything in the static directory will be copied directly into the final site 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 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 /css
/js /js

View file

@ -50,6 +50,6 @@ If the archetype that ships with the theme for a given content type (or all cont
## Beware of the default ## 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. It is usually better to override specific files rather than using the default in your working directory.