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

Add review badge on incomplete pages

Browse Source
This commit is contained in:
Ryan Watters
2017-02-20 17:15:05 -06:00
parent 782004bafa
commit 1645c50123
55 changed files with 2770 additions and 318 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+2 -1
View File
@@ -1,3 +1,4 @@
themes/hugodocs/pipeline/node_modules
my-notes.md
notes-for-reviewers.md
notes-for-reviewers.md
features-log.md
content/about-hugo/benefits-of-static.md
+2 -2
View File
@@ -5,7 +5,7 @@ description: Learn why static site generators have become such a popular option
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: [ssg,static site generator]
tags: [ssg,static,performance, security]
weight: 20
draft: false
slug:
@@ -26,7 +26,7 @@ Not running a website generator on your HTTP server has many benefits. The most
sending files. So good that you can effectively serve the same number
of pages with a fraction of the memory and CPU needed for a dynamic site.
## Additional Resources
## Resources on Static Site Generators
* ["An Introduction to Static Site Generators", David Walsh][]
* ["Static Site Generators", O-Reilly][]
content/about-hugo/hugo-features.md
+2 -2
View File
@@ -36,7 +36,7 @@ notesforauthors:
## Content
* Native Markdown support, as well as other languages through *external helpers* (see [supported formats][])
* Support for TOML, YAML and JSON metadata in [front matter][]
* Support for TOML, YAML, and JSON metadata in [front matter][]
* Customizable [homepage][]
* Multiple [content types][]
* Automatic and user defined [content summaries][]
@@ -54,7 +54,6 @@ notesforauthors:
See what's coming next in the [Hugo roadmap][].
[pagevars]: /variables-and-params/page-variables/
[Ace]: /templates/ace-templating/
[aliases]: /content-management/url-management/#aliases
[Amber]: https://github.com/eknkc/amber
@@ -74,6 +73,7 @@ See what's coming next in the [Hugo roadmap][].
[LiveReload]: /getting-started/using-hugo/
[Mac OSX]: /getting-started/install-of-pc/
[organization for your projects]: /getting-started/directory-structure/
[pagevars]: /variables-and-params/page-variables/
[Permalink]: /content-management/url-management/#permalinks
[Powerful theming]: /themes/
[Pretty URLs]: /content-management/url-management/
content/about-hugo/why-i-built-hugo.md
+1 -1
View File
@@ -19,7 +19,7 @@ WordPress sites rendered slowly and required I be online to write posts. WordPre
I looked at existing static site generators like [Jekyll][], [Middleman][], and [Nanoc][]. All had complicated installation dependencies and an unacceptably long time to render my blog with hundreds of posts. I wanted a framework that would give me rapid feedback while making changes to the templates, and the 5-minute-plus render times were just too slow. In general, the static site generators were very blog-minded and didn't provide for other content types and flexible URLs.
I wanted to develop a fast and full-featured website framework without any dependencies. The [Go language][] seemed to have all the features I needed in a language. I began developing Hugo in Go and fell in love with the language. I hope you will enjoy using Hugo (and [contributing to it][]) as much as I have writing it.
I wanted to develop a fast and full-featured website framework without any dependencies. The [Go language][] seemed to have all the features I needed. I began developing Hugo in Go and fell in love with the language. I hope you will enjoy using Hugo (and [contributing to it][]) as much as I have writing it.
―Steve Francia ([@spf13][])
content/content-management/menus.md
+5 -87
View File
@@ -13,15 +13,14 @@ slug:
aliases: [/extras/menus/]
toc: false
needsreview: true
notesforauthors:
---
Hugo has a simple yet powerful menu system that permits content to be
placed in menus with a good degree of control without a lot of work.
*TIP:* If all you want is a simple menu for your sections, see [Section Menu for "the Lazy Blogger"](#section-menu-for-the-lazy-blogger).
{{% note "Lazy Blogger"%}}
If all you want is a simple menu for your sections, see [Section Menu for "the Lazy Blogger"](#section-menu-for-the-lazy-blogger).
{{% /note %}}
Some of the features of Hugo Menus:
@@ -154,87 +153,6 @@ In this example, the top level of the menu is defined in the config file
and all content entries are attached to one of these entries via the
`parent` field.
## Rendering menus
## Rendering Menus
Hugo makes no assumptions about how your rendered HTML will be
structured. Instead, it provides all of the functions you will need to be
able to build your menu however you want.
The following is an example:
<!--sidebar start-->
<aside>
<div id="sidebar" class="nav-collapse">
<!-- sidebar menu start-->
<ul class="sidebar-menu">
{{ $currentPage := . }}
{{ range .Site.Menus.main }}
{{ if .HasChildren }}
<li class="sub-menu{{if $currentPage.HasMenuCurrent "main" . }} active{{end}}">
<a href="javascript:;" class="">
{{ .Pre }}
<span>{{ .Name }}</span>
<span class="menu-arrow arrow_carrot-right"></span>
</a>
<ul class="sub">
{{ range .Children }}
<li{{if $currentPage.IsMenuCurrent "main" . }} class="active"{{end}}><a href="{{.URL}}"> {{ .Name }} </a> </li>
{{ end }}
</ul>
{{else}}
<li>
<a href="{{.URL}}">
{{ .Pre }}
<span>{{ .Name }}</span>
</a>
{{end}}
</li>
{{end}}
<li> <a href="https://github.com/spf13/hugo/issues" target="blank">Questions and Issues</a> </li>
<li> <a href="#" target="blank">Edit this Page</a> </li>
</ul>
<!-- sidebar menu end-->
</div>
</aside>
<!--sidebar end-->
> **Note**: use the `absLangURL` or `relLangURL` if your theme makes use of the [multilingual feature](/content-management/multilingual-mode/). In contrast to `absURL` and `relURL` it adds the correct language prefix to the url. [Read more](/functions/).
## Section Menu for "the Lazy Blogger"
To enable this menu, add this to your site config, i.e. `config.toml`:
```
SectionPagesMenu = "main"
```
The menu name can be anything, but take a note of what it is.
This will create a menu with all the sections as menu items and all the sections' pages as "shadow-members". The _shadow_ implies that the pages isn't represented by a menu-item themselves, but this enables you to create a top-level menu like this:
```
<nav class="sidebar-nav">
{{ $currentPage := . }}
{{ range .Site.Menus.main }}
<a class="sidebar-nav-item{{if or ($currentPage.IsMenuCurrent "main" .) ($currentPage.HasMenuCurrent "main" .) }} active{{end}}" href="{{.URL}}">{{ .Name }}</a>
{{ end }}
</nav>
```
In the above, the menu item is marked as active if on the current section's list page or on a page in that section.
The above is all that's needed. But if you want custom menu items, e.g. changing weight or name, you can define them manually in the site config, i.e. `config.toml`:
```
[[menu.main]]
name = "This is the blog section"
weight = -110
identifier = "blog"
url = "/blog/"
```
**Note** that the `identifier` must match the section name.
See [Menu Templates](/templates/menu-templates/).
content/developer-tools/syntax-highlighting.md
+2 -1
View File
@@ -10,8 +10,9 @@ categories: [developer tools]
weight:
draft: false
slug:
aliases: [/extras/highlighting/]
aliases: [/extras/highlighting/,/extras/highlight/]
toc: true
needsreview: true
notesforauthors:
---
content/functions/_index.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
title: Functions
title: Functions Quick Reference
linktitle: Overview
description: Comprehensive list of Hugo templating functions, including basic and advanced usage examples.
date: 2017-02-01
content/functions/index-function.md
+5 -1
View File
@@ -2,7 +2,7 @@
title: index
linktitle: index
description:
godocref:
godocref: https://golang.org/pkg/text/template/#hdr-Functions
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
@@ -14,6 +14,10 @@ aliases: []
notesforauthors:
---
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
## Advanced Example
content/getting-started/_index.md
+1 -1
View File
@@ -15,7 +15,7 @@ toc: false
notesforauthors:
---
The Hugo docs were completely reworked from the ground up in anticipation of v0.19. Included in the reboot was the concept of using a [single example site][] for code blocks and demo content in the documentation. Once you finish the [quick start][], be sure to read up on how [the Hugo docs have been optimized for rapid learning][].
The Hugo docs were completely reworked from the ground up in anticipation of v0.19. Included in the reboot was the concept of leveraging a [single example site][] from which to pull code blocks and demo content in the documentation. Once you finish the [quick start][], be sure to look into how [the Hugo docs have been optimized for rapid learning][].
[quick start]: /getting-started/quick-start/
[single example site]: /getting-started/using-the-hugo-docs/
content/getting-started/basic-usage.md
+249 -5
View File
@@ -1,7 +1,7 @@
---
title: Basic Usage
linktitle: Basic Usage
description:
description: Hugo's CLI is fully featured but simple. You do not need a high level of expertise on the command line to get up and running.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
@@ -9,10 +9,254 @@ categories: [getting started]
tags: [usage,livereload,command line]
weight: 40
draft: false
slug:
aliases: [/overview/usage/,/extras/livereload/,/getting-started/using-hugo/]
toc: false
aliases: [/overview/usage/,/extras/livereload/,/getting-started/using-hugo/,/doc/usage/]
toc: true
needsreview: true
notesforauthors:
---
## LiveReload
Once you have [installed Hugo][install] is in your `PATH` (or provide a path to it). Test this by:
```bash
hugo help
hugo is the main command, used to build your Hugo site.
Hugo is a Fast and Flexible Static Site Generator built with love by spf13 and friends in Go.
Complete documentation is available at http://gohugo.io/.
Usage:
hugo [flags]
hugo [command]
Available Commands:
benchmark Benchmark Hugo by building a site a number of times.
config Print the site configuration
convert Convert your content to different formats
env Print Hugo version and environment info
gen A collection of several useful generators.
import Import your site from others.
list Listing out various types of content
new Create new content for your site
server A high performance webserver
undraft Undraft changes the content's draft status from 'True' to 'False'
version Print the version number of Hugo
Flags:
-b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/
-D, --buildDrafts include content marked as draft
-E, --buildExpired include expired content
-F, --buildFuture include content with publishdate in the future
--cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
--canonifyURLs if true, all relative URLs will be canonicalized using baseURL
--cleanDestinationDir Remove files from destination not found in static directories
--config string config file (default is path/config.yaml|json|toml)
-c, --contentDir string filesystem path to content directory
-d, --destination string filesystem path to write files to
--disable404 Do not render 404 page
--disableRSS Do not build RSS files
--disableSitemap Do not build Sitemap file
--enableGitInfo Add Git revision, date and author info to the pages
--forceSyncStatic Copy all files when static is changed.
--i18n-warnings Print missing translations
--ignoreCache Ignores the cache directory
-l, --layoutDir string filesystem path to layout directory
--log Enable Logging
--logFile string Log File path (if set, logging enabled automatically)
--noChmod Don't sync permission mode of files
--noTimes Don't sync modification time of files
--pluralizeListTitles Pluralize titles in lists using inflect (default true)
--preserveTaxonomyNames Preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu")
--quiet build in quiet mode
--renderToMemory render to memory (only useful for benchmark testing)
-s, --source string filesystem path to read files relative from
--stepAnalysis display memory and timing of different steps of the program
-t, --theme string theme to use (located in /themes/THEMENAME/)
--uglyURLs if true, use /filename.html instead of /filename/
-v, --verbose verbose output
--verboseLog verbose logging
-w, --watch watch filesystem for changes and recreate as needed
Additional help topics:
hugo check Contains some verification checks
Use "hugo [command] --help" for more information about a command.
```
## Common Usage Example
The most common use is probably to run `hugo` with your current directory being the input directory:
```bash
hugo
0 draft content
0 future content
99 pages created
0 paginator pages created
16 tags created
0 groups created
in 120 ms
```
This generates your web site to the `public/` directory, ready to be deployed to your web server.
## Instant feedback as you develop your web site
If you are working on things and want to see the changes immediately, by default Hugo will watch the filesystem for changes, and rebuild your site as soon as a file is saved:
```bash
hugo -s ~/Code/hugo/docs
0 draft content
0 future content
99 pages created
0 paginator pages created
16 tags created
0 groups created
in 120 ms
Watching for changes in /Users/spf13/Code/hugo/docs/content
Press Ctrl+C to stop
```
Hugo can even run a server and create a site preview at the same time! Hugo implements [LiveReload](#LiveReload) technology to automatically reload any open pages in all JavaScript-enabled browsers, including mobile. This is the easiest and most common way to develop a Hugo web site:
```bash
hugo server -ws ~/Code/hugo/docs
0 draft content
0 future content
99 pages created
0 paginator pages created
16 tags created
0 groups created
in 120 ms
Watching for changes in /Users/spf13/Code/hugo/docs/content
Serving pages from /Users/spf13/Code/hugo/docs/public
Web Server is available at http://localhost:1313/
Press Ctrl+C to stop
```
Hugo may not be the first static site generator to utilize LiveReload
technology, but it’s the first to do it right.
The combination of Hugo’s insane build speed and LiveReload make
crafting your content pure joy. Virtually instantly after you hit save
your rebuilt content will appear in your browser.
## LiveReload
Hugo comes with [LiveReload](https://github.com/livereload/livereload-js) built in. There are no additional packages to install. A common way to use Hugo while developing a site is to have Hugo run a server and watch for changes:
```bash
hugo server
```
This will run a full functioning web server while simultaneously watching your file system for additions, deletions, or changes within the following
* `/static/*`
* `/content/*`
* `/data/*`
* `/layouts/*`
* `/themes/<only your current theme>/*`
* `config`
Whenever you make changes, Hugo will simultaneously rebuild the site and continue to serve content. As soon as the build is finished, LiveReload tells the browser to silently reload the page.
Most Hugo builds are so fast that you may not notice the change unless looking directly at the site in your browser. This means that keeping the site open on a second monitor (or another half of your current monitor) allows you to see the most up-to-date version of your website without the need to leave your text editor.
{{% note "Closing `</body>` Tag"%}}
You must have a closing `</body>` tag for LiveReload to work.
Hugo injects the LiveReload `<script>` before this tag.
{{% /note %}}
### Disabling LiveReload's Watch Feature
LiveReload works by injecting JavaScript into the pages Hugo generates. The script creates a connection from the browser's web socket client to the
Hugo web socket server.
LiveReload is awesome for development. However, some Hugo users may use `hugo server` in production to instantly display updated content. As such, we’ve provided multiple methods made it easy to disable the LiveReload functionality:
```bash
hugo server --watch=false
```
Or...
```bash
hugo server --disableLiveReload
```
The latter flag can be omitted by adding the following key-value to your `config` file:
```toml
disableLiveReload = true
```
```yaml
disableLiveReload: true
```
## Deploying Your Website
After running `hugo server` for local web development, you need to do a final `hugo` run **without the `server` part of the command** to rebuild your site. You may then **deploy your site** by copying the `public/` directory (by FTP, SFTP, WebDAV, Rsync, `git push`, etc.) to your production web server.
Since Hugo generates a static website, your site can be hosted anywhere, including [Heroku][], [GoDaddy][], [DreamHost][], [GitHub Pages][], [Amazon S3][] with [CloudFront][], [Firebase Hosting][], or any other cheap (or even free) static web hosting service.
[Apache][], [nginx][], [IIS][]... Any web server software would do!
[Apache]: http://httpd.apache.org/ "Apache HTTP Server"
[nginx]: http://nginx.org/
[IIS]: http://www.iis.net/
[Heroku]: https://www.heroku.com/
[GoDaddy]: https://www.godaddy.com/
[DreamHost]: http://www.dreamhost.com/
[GitHub Pages]: https://pages.github.com/
[GitLab]: https://about.gitlab.com
[Amazon S3]: http://aws.amazon.com/s3/
[CloudFront]: http://aws.amazon.com/cloudfront/ "Amazon CloudFront"
[Firebase Hosting]: https://firebase.google.com/docs/hosting/
{{% warning "Generated Files are **NOT** Removed on Site Build" %}}
{{% /warning %}}
### A Note About Deployment
Running `hugo` *does not* remove generated files before building. This means that you should delete your `public/` directory (or the directory you specified with `-d`/`--destination`) before running the `hugo` command, or you run the risk of the wrong files (e.g., drafts or future posts) being left in the generated site.
An easy way to work around this is to use different directories for development and production.
To start a server that builds draft content (helpful for editing), you can specify a different destination: the `dev/` dir.
```bash
hugo server -wDs ~/Code/hugo/docs -d dev
```
When the content is ready for publishing, use the default `public/` dir:
```bash
hugo -s ~/Code/hugo/docs
```
This prevents content you're not yet ready to share from accidentally becoming available.
### Using Hugo's Server in Production
Because Hugo is so blazingly fast both in web site creation *and* in web serving (thanks to its concurrent and multi-threaded design and its Golang heritage), some users prefer using Hugo itself to serve their website *on their production server*.
No other web server software (e.g., Apache, nginx, IIS) is necessary.
Here is the command:
```bash
hugo server --baseURL=http://yoursite.org/ \
--port=80 \
--appendPort=false \
--bind=87.245.198.50
```
Note the `bind` option, which is the interface to which the server will bind (defaults to `127.0.0.1`: fine for most development use cases). Some hosts, such as Amazon Web Services, run NAT (network address translation); sometimes it can be hard to figure out the actual IP address. Using `--bind=0.0.0.0` will bind to all interfaces.
By using Hugo's server in production, you are able to deploy just the source files. Hugo, running on your server, will generate the resulting website on the fly and serve them at the same time.
Interested? Here are some great tutorials contributed by Hugo users:
* [hugo, syncthing](http://fredix.xyz/2014/10/hugo-syncthing/) (French) by Frédéric Logier (@fredix)
[install]: /getting-started/install-hugo/
content/getting-started/directory-structure.md
+1 -1
View File
@@ -1,7 +1,7 @@
---
title: Directory Structure
linktitle: Directory Structure
description: Explanation of the directory structure in a typical Hugo project and how Hugo traverses the file system therein.
description: Hugo's CLI scaffolds a project's directory structure nearly instantly and then takes that single directory and uses it as the input for creating a complete website.
date: 2017-01-02
publishdate: 2017-01-02
lastmod: 2017-01-02
content/getting-started/install-hugo.md
+3 -3
View File
@@ -1,13 +1,13 @@
---
title: Install Hugo
linktitle: Install Hugo
description:
description: Install Hugo on Mac OSX, Windows, Linux, FreeBSD, and on any machine where the Go compiler tool chain can run.
date: 2016-11-01
publishdate: 2016-11-01
lastmod: 2016-11-01
lastmod: 2017-02-20
categories: [getting started]
authors: ["Michael Henderson"]
tags: [install,pc,windows,linux,mac,osx,binary,tarball]
tags: [install,fundamentals,pc,windows,linux,mac,osx,binary,tarball]
weight: 30
draft: false
aliases: [/tutorials/installing-on-windows/,/tutorials/installing-on-mac/,/overview/installing/,/getting-started/install,/install/]
content/getting-started/quick-start.md
+1 -2
View File
@@ -1,7 +1,7 @@
---
title: Quick Start
linktitle: Quick Start
description: Build an online bookshelf that lists books and their reviews. The Quick Start introduces you to HUGO's CLI, directory structure, configuration, theming, and even a simple deployment.
description: Build an online bookshelf that lists books and their reviews. The Quick Start introduces you to HUGO's CLI, directory structure, configuration, theming, and a simple deployment to GitHub Pages.
date: 2013-07-01
publishdate: 2013-07-01
lastmod: 2017-02-19
@@ -12,7 +12,6 @@ weight: 10
draft: false
aliases: [/overview/quickstart/]
toc: true
notesforauthors:
---
In this Quick Start, we will build an online bookshelf that lists books and their reviews. This quick start assumes you are using Hugo v0.15 or greater.
content/getting-started/using-the-hugo-docs.md
+11 -5
View File
@@ -1,15 +1,15 @@
---
title: Using the Hugo Docs
linktitle: Using the Hugo Docs
description:
description: The Hugo docs are optimized for consistency. Code samples and tutorials pull from a single example site, and content is grouped together to make learning Hugo easier and even more fun.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [getting started]
tags: [usage,docs]
tags: [usage,docs,fundamentals]
tags_weight: 01
weight: 20
draft: false
slug:
aliases: [/getting-started/using-the-docs/]
toc: true
needsreview: true
@@ -21,9 +21,15 @@ needsreview: true
## Code Samples
### Input Code Code Blocks
Throughout the docs, you'll see four different types of code blocks.
### Output Code Code Blocks
### Standard
This should be obvious.
### Input Code Blocks (Copyable)
### Output Code Blocks
### Example Site Code Blocks
content/news/press-and-articles.md
+3
View File
@@ -23,7 +23,10 @@ Hugo has been featured in the following Blog Posts, Press, and Media.
| Title | Author | Date |
| ----- | ------ | -----: |
| [How to Password Protect a Hugo Site](https://www.aerobatic.com/blog/password-protect-a-hugo-site/) | Aerobatic | 2017-02-19 |
| [Deploy a Hugo site to Aerobatic with CircleCI ](https://www.aerobatic.com/blog/hugo-github-circleci/) | Aerobatic | 2017-02-14 |
| [NPM scripts for building and deploying Hugo site]() | Aerobatic | 2017-02-12 |
| [Build a Hugo site using Cloud9 IDE and host on App Engine](https://loyall.ch/lab/2017/01/build-a-static-website-with-cloud9-hugo-and-app-engine/)| Pascal Aubort | 2017-02-05 |
| [Hugo Continuous Deployment with Bitbucket Pipelines and Aerobatic](https://www.aerobatic.com/blog/hugo-bitbucket-pipelines/) | Aerobatic | 2017-02-04 |
| [How to use Firebase to host a Hugo site](https://www.m0d3rnc0ad.com/post/static-site-firebase/) | Andrew Cuga | 2017-02-04 |
| [A publishing workflow for teams using static site generators](https://www.keybits.net/post/publishing-workflow-for-teams-using-static-site-generators/) | Tom Atkins | 2017-01-02 |
| [How To Dynamically Use Google Fonts In A Hugo Website](https://stoned.io/web-development/hugo/How-To-Dynamically-Use-Google-Fonts-In-A-Hugo-Website/) | Hash Borgir | 2016-10-27 |
content/templates/ace-templating.md
-1
View File
@@ -12,7 +12,6 @@ categories: [amber, templating options]
draft: false
aliases: []
toc: false
notesforauthors:
---
In addition to [Go templates][] and [Amber templates][], Hugo supports the powerful Ace templates.
content/templates/amber-templating.md
-1
View File
@@ -12,7 +12,6 @@ tags: [amber, templating options]
draft: false
aliases: [/templates/amber/]
toc: false
notesforauthors:
---
Hugo also supports the Amber templating engine in addition to [Go templates][] and [Ace templates][] templates.
content/templates/base-templates-and-blocks.md
+84 -1
View File
@@ -12,7 +12,90 @@ tags: [blocks,base,fundamentals]
draft: false
aliases: [/templates/blocks/]
toc: true
notesforauthors:
needsreview: true
---
Go 1.6 includes a powerful new keyword, `block`. This construct allows you to define the outer shell of your pages one or more master template(s), filling in or overriding portions as necessary.
## Base Template Lookup Order
This is the order Hugo searches for a base template:
1. /layouts/_current-path_/_template-name_-baseof.html, e.g. list-baseof.html.
2. /layouts/_current-path_/baseof.html
3. /layouts/_default/_template-name_-baseof.html e.g. list-baseof.html.
4. /layouts/_default/baseof.html
For each of the steps above, it will first look in the project, then, if theme is set, in the theme's layouts folder. Hugo picks the first base template found.
As an example, with a site using the theme `exampletheme`, when rendering the section list for the section `post`. Hugo picks the `section/post.html` as the template and this template has a `define` section that indicates it needs a base template. This is then the lookup order:
1. `/layouts/section/post-baseof.html`
2. `/themes/exampletheme/layouts/section/post-baseof.html`
3. `/layouts/section/baseof.html`
4. `/themes/exampletheme/layouts/section/baseof.html`
5. `/layouts/_default/post-baseof.html`
6. `/themes/exampletheme/layouts/_default/post-baseof.html`
7. `/layouts/_default/baseof.html`
8. `/themes/exampletheme/layouts/_default/baseof.html`
## Define the base template
Let's define a simple base template (`_default/baseof.html`), a shell from which all our pages will start.
```html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>{{ block "title" . }}
<!-- Blocks may include default content. -->
{{ .Site.Title }}
{{ end }}</title>
</head>
<body>
<!-- Code that all your templates share, like a header -->
{{ block "main" . }}
<!-- The part of the page that begins to differ between templates -->
{{ end }}
<!-- More shared code, perhaps a footer -->
</body>
</html>
```
## Overriding the Base Template
Your [default list template](/templates/list/)---`_default/list.html`---will inherit all of the code defined in the base template. It could then implement its own "main" block from the base template above like so:
```html
<!-- Note the lack of Go's context "dot" when defining blocks -->
{{ define "main" }}
<h1>Posts</h1>
{{ range .Data.Pages }}
<article>
<h2>{{ .Title }}</h2>
{{ .Content }}
</article>
{{ end }}
{{ end }}
```
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.
In our [default single template](/templates/content/)---`_default/single.html`---let's implement both blocks:
```html
{{ define "title" }}
{{ .Title }} &ndash; {{ .Site.Title }}
{{ end }}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ end }}
```
This overrides both block areas from the base template with code unique to our single template.
content/templates/content-view-templates.md
+114 -2
View File
@@ -9,8 +9,120 @@ weight:
categories: [templates]
tags: [views]
draft: false
slug:
aliases: [/templates/views/]
toc: false
notesforauthors:
needsreview: true
---
In addition to the [single content template](/templates/content/), Hugo can render alternative views of
your content. These are especially useful in [list templates](/templates/list/).
For example you may want content of every type to be shown on the
homepage, but only a summary view of it there. Perhaps on a taxonomy
list page you would only want a bulleted list of your content. Views
make this very straightforward by delegating the rendering of each
different type of content to the content itself.
## Creating a content view
To create a new view, simply create a template in each of your different
content type directories with the view name. In the following example, we
have created a "li" view and a "summary" view for our two content types
of post and project. As you can see, these sit next to the [single
content view](/templates/content/) template "single.html". You can even
provide a specific view for a given type and continue to use the
\_default/single.html for the primary view.
▾ layouts/
▾ post/
li.html
single.html
summary.html
▾ project/
li.html
single.html
summary.html
Hugo also has support for a default content template to be used in the event
that a specific template has not been provided for that type. The default type
works the same as the other types, but the directory must be called "_default".
Content views can also be defined in the "_default" directory.
▾ layouts/
▾ _default/
li.html
single.html
summary.html
## Which Template will be rendered?
Hugo uses a set of rules to figure out which template to use when
rendering a specific page.
Hugo will use the following prioritized list. If a file isn’t present,
then the next one in the list will be used. This enables you to craft
specific layouts when you want to without creating more templates
than necessary. For most sites only the \_default file at the end of
the list will be needed.
* /layouts/`TYPE`/`VIEW`.html
* /layouts/\_default/`VIEW`.html
* /themes/`THEME`/layouts/`TYPE`/`VIEW`.html
* /themes/`THEME`/layouts/\_default/`view`.html
## Example using views
### rendering view inside of a list
Using the summary view (defined below) inside of a ([list
templates](/templates/list/)).
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
In the above example, you will notice that we have called `.Render` and passed in
which view to render the content with. `.Render` is a special function available on
a content which tells the content to render itself with the provided view template.
In this example, we are not using the li view. To use this we would
change the render line to `{{ .Render "li" }}`.
### li.html
Hugo will pass the entire page object to the view template. See [page
variables](/templates/variables/) for a complete list.
This content template is used for [spf13.com](http://spf13.com/).
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
### summary.html
Hugo will pass the entire page object to the view template. See [page
variables](/templates/variables/) for a complete list.
This content template is used for [spf13.com](http://spf13.com/).
<article class="post">
<header>
<h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2>
<div class="post-meta">{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words </div>
</header>
{{ .Summary }}
<footer>
<a href='{{ .Permalink }}'><nobr>Read more →</nobr></a>
</footer>
</article>
content/templates/custom-404-page.md
+43 -5
View File
@@ -1,16 +1,54 @@
---
title: Custom 404 Page
linktitle:
linktitle: 404 Page
description:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
weight:
tags: [404, page not found]
categories: [templates]
tags: [404, page not found]
draft: false
slug:
aliases: []
aliases: [/templates/404/]
toc: false
notesforauthors:
needsreview: true
---
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.
404 pages will have all the regular [page
variables](/layout/variables/) available to use in the templates.
In addition to the standard page variables, the 404 page has access to
all site content accessible from `.Data.Pages`.
▾ layouts/
404.html
## 404.html
This is a basic example of a 404.html template:
{{ partial "header.html" . }}
{{ partial "subheader.html" . }}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
</div>
</section>
{{ partial "footer.html" . }}
### Automatic Loading
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.
* _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.
* _Caddy Server_ - using `errors { 404 /404.html }`. [Details here](https://caddyserver.com/docs/errors)
content/templates/data-templates.md
+219 -4
View File
@@ -6,11 +6,226 @@ date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
weight:
tags: [data]
categories: [templates]
tags: [data,dynamic,csv,json,toml,yaml]
draft: false
slug:
aliases:
aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/]
toc: false
notesforauthors:
needsreview: true
---
<!-- begin data files -->
In addition to the [built-in variables](/templates/variables/) available from Hugo, you can specify your own custom data that can be accessed via templates or shortcodes.
Hugo supports loading data from [YAML](http://yaml.org/), [JSON](http://www.json.org/), and [TOML](https://github.com/toml-lang/toml) files located in the `data` directory.
**It even works with [LiveReload](/extras/livereload/).**
Data Files can also be used in [themes](/themes/overview/), but note: If the same `key` is used in both the main data folder and in the theme's data folder, the main one will win. So, for theme authors, for theme specific data items that shouldn't be overridden, it can be wise to prefix the folder structure with a namespace, e.g. `mytheme/data/mytheme/somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag, e.g. `hugo -v`.
## The Data Folder
The `data` folder is where you can store additional data for Hugo to use when generating your site. Data files aren't used to generate standalone pages - rather they're meant supplemental to the content files. This feature can extend the content in case your frontmatter would grow immensely. Or perhaps your want to show a larger dataset in a template (see example below). In both cases it's a good idea to outsource the data in their own file.
These files must be YAML, JSON or TOML files (using either the `.yml`, `.yaml`, `.json` or `toml` extension) and the data will be accessible as a `map` in `.Site.Data`.
**The keys in this map will be a dot chained set of _path_, _filename_ and _key_ in file (if applicable).**
This is best explained with an example:
## Example: Jaco Pastorius' Solo Discography
[Jaco Pastorius](http://en.wikipedia.org/wiki/Jaco_Pastorius_discography) was a great bass player, but his solo discography is short enough to use as an example. [John Patitucci](http://en.wikipedia.org/wiki/John_Patitucci) is another bass giant.
The example below is a bit constructed, but it illustrates the flexibility of Data Files. It uses TOML as file format.
Given the files:
* `data/jazz/bass/jacopastorius.toml`
* `data/jazz/bass/johnpatitucci.toml`
`jacopastorius.toml` contains the content below, `johnpatitucci.toml` contains a similar list:
```
discography = [
"1974 – Modern American Music … Period! The Criteria Sessions",
"1974 – Jaco",
"1976 - Jaco Pastorius",
"1981 - Word of Mouth",
"1981 - The Birthday Concert (released in 1995)",
"1982 - Twins I & II (released in 1999)",
"1983 - Invitation",
"1986 - Broadway Blues (released in 1998)",
"1986 - Honestly Solo Live (released in 1990)",
"1986 - Live In Italy (released in 1991)",
"1986 - Heavy'n Jazz (released in 1992)",
"1991 - Live In New York City, Volumes 1-7.",
"1999 - Rare Collection (compilation)",
"2003 - Punk Jazz: The Jaco Pastorius Anthology (compilation)",
"2007 - The Essential Jaco Pastorius (compilation)"
]
```
The list of bass players can be accessed via `.Site.Data.jazz.bass`, a single bass player by adding the filename without the suffix, e.g. `.Site.Data.jazz.bass.jacopastorius`.
You can now render the list of recordings for all the bass players in a template:
```
{{ range $.Site.Data.jazz.bass }}
{{ partial "artist.html" . }}
{{ end }}
```
And then in `partial/artist.html`:
```
<ul>
{{ range .discography }}
<li>{{ . }}</li>
{{ end }}
</ul>
```
Discover a new favourite bass player? Just add another TOML-file.
## Example: Accessing named values in a Data File
Assuming you have the following YAML structure to your `User0123.yml` Data File located directly in `data/`
```
Name: User0123
"Short Description": "He is a **jolly good** fellow."
Achievements:
- "Can create a Key, Value list from Data File"
- "Learns Hugo"
- "Reads documentation"
```
To render the `Short Description` in your `layout` File following code is required.
```
<div>Short Description of {{.Site.Data.User0123.Name}}: <p>{{ index .Site.Data.User0123 "Short Description" | markdownify }}</p></div>
```
Note the use of the `markdownify` template function. This will send the description through the Blackfriday Markdown rendering engine.
<!-- begin "Data-drive Content" page -->
Data-driven content with a static site generator? Yes, it is possible!
In addition to the [data files](/extras/datafiles/) feature, we have also
implemented the feature "Data-driven Content", which lets you load
any [JSON](http://www.json.org/) or
[CSV](http://en.wikipedia.org/wiki/Comma-separated_values) file
from nearly any resource.
"Data-driven Content" currently consists of two functions, `getJSON`
and `getCSV`, which are available in **all template files**.
## Implementation details
### Calling the functions with an URL
In any HTML template or Markdown document, call the functions like this:
{{ $dataJ := getJSON "url" }}
{{ $dataC := getCSV "separator" "url" }}
or, if you use a prefix or postfix for the URL, the functions
accept [variadic arguments](http://en.wikipedia.org/wiki/Variadic_function):
{{ $dataJ := getJSON "url prefix" "arg1" "arg2" "arg n" }}
{{ $dataC := getCSV "separator" "url prefix" "arg1" "arg2" "arg n" }}
The separator for `getCSV` must be put in the first position and can only
be one character long.
All passed arguments will be joined to the final URL; for example:
{{ $urlPre := "https://api.github.com" }}
{{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }}
will resolve internally to:
{{ $gistJ := getJSON "https://api.github.com/users/GITHUB_USERNAME/gists" }}
Finally, you can range over an array. This example will output the
first 5 gists for a GitHub user:
<ul>
{{ $urlPre := "https://api.github.com" }}
{{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }}
{{ range first 5 $gistJ }}
{{ if .public }}
<li><a href="{{ .html_url }}" target="_blank">{{ .description }}</a></li>
{{ end }}
{{ end }}
</ul>
### Example for CSV files
For `getCSV`, the one-character long separator must be placed in the
first position followed by the URL.
<table>
<thead>
<tr>
<th>Name</th>
<th>Position</th>
<th>Salary</th>
</tr>
</thead>
<tbody>
{{ $url := "http://a-big-corp.com/finance/employee-salaries.csv" }}
{{ $sep := "," }}
{{ range $i, $r := getCSV $sep $url }}
<tr>
<td>{{ index $r 0 }}</td>
<td>{{ index $r 1 }}</td>
<td>{{ index $r 2 }}</td>
</tr>
{{ end }}
</tbody>
</table>
The expression `{{index $r number}}` must be used to output the nth-column from
the current row.
### Caching of URLs
Each downloaded URL will be cached in the default folder `$TMPDIR/hugo_cache/`. The variable `$TMPDIR` will be resolved to your system-dependent temporary directory.
With the command-line flag `--cacheDir`, you can specify any folder on your system as a caching directory.
You can also set `cacheDir` in the main configuration file.
If you don't like caching at all, you can fully disable caching with the command line flag `--ignoreCache`.
### Authentication when using REST URLs
Currently, you can only use those authentication methods that can be put into an URL. [OAuth](http://en.wikipedia.org/wiki/OAuth) or other authentication methods are not implemented.
### Loading local files
To load local files with the two functions `getJSON` and `getCSV`, the source files must reside within Hugo's working directory. The file extension does not matter but the content does.
It applies the same output logic as in the topic: *Calling the functions with an URL*.
## LiveReload
There is no chance to trigger a [LiveReload](/extras/livereload/) when the content of an URL changes. However, when a local JSON/CSV file changes, then a LiveReload will be triggered of course. Symlinks are not supported.
{{% note "URLs and LiveReload" %}}
If you change any local file and the LiveReload is triggered, Hugo will either read the URL content from the cache or, if you have disabled the cache, Hugo will re-download the content. This can create huge traffic and you may also reach API limits quickly.
{{% /note %}}
As downloading of content takes a while, Hugo stops processing
your Markdown files until the content has been downloaded.
## Examples
- Photo gallery JSON powered: [https://github.com/pcdummy/hugo-lightslider-example](https://github.com/pcdummy/hugo-lightslider-example)
- GitHub Starred Repositories [in a posts](https://github.com/SchumacherFM/blog-cs/blob/master/content%2Fposts%2Fgithub-starred.md) with the related [short code](https://github.com/SchumacherFM/blog-cs/blob/master/layouts%2Fshortcodes%2FghStarred.html).
- More? Please tell us!
content/templates/go-template-primer.md
+1 -1
View File
@@ -13,7 +13,7 @@ draft: false
slug:
aliases: [/templates/go-templates/]
toc: true
notesforauthors:
needsreview: true
---
Hugo uses the excellent [Go html/template][] library, an extremely lightweight engine that provides just the right amount of logic to be able to create a good static website. If you have used other template systems from different languages or frameworks, you will find a lot of similarities in Go templates.
content/templates/homepage-template.md
+59 -2
View File
@@ -12,5 +12,62 @@ draft: false
slug:
aliases: [/layout/homepage/,/templates/homepage/]
toc: false
notesforauthors:
---
needsreview: true
---
The home page of a website is often formatted differently than the other pages. In Hugo you can define your own homepage template.
Homepage is a `Page` and has all the [page variables](/templates/variables/) and [site variables](/templates/variables/) available to use in the templates.
*This is the only required template for building a site and useful when bootstrapping a new site and template. It is also the only required template when using a single page site.*
In addition to the standard page variables, the homepage has access to all site content accessible from `.Data.Pages`. Details on how to use the list of pages can be found in the [Lists Template](/templates/list/).
Note that a home page can also have a content file with frontmatter, see [Source Organization](/overview/source-directory/).
## Which Template will be rendered?
Hugo uses a set of rules to figure out which template to use when rendering a specific page.
Hugo will use the following prioritized list. If a file isn’t present, then the next one in the list will be used. This enables you to craft specific layouts when you want to without creating more templates than necessary. For most sites, only the \_default file at the end of
the list will be needed.
* /layouts/index.html
* /layouts/\_default/list.html
* /layouts/\_default/single.html
* /themes/`THEME`/layouts/index.html
* /themes/`THEME`/layouts/\_default/list.html
* /themes/`THEME`/layouts/\_default/single.html
## Example index.html
This content template is used for [spf13.com](http://spf13.com/).
It makes use of [partial templates](/templates/partials/) and uses a similar approach as a [List](/templates/list/).
<!DOCTYPE html>
<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
<head>
<meta charset="utf-8">
{{ partial "meta.html" . }}
<base href="{{ .Site.BaseURL }}">
<title>{{ .Site.Title }}</title>
<link rel="canonical" href="{{ .Permalink }}">
<link href="{{ .RSSLink }}" rel="alternate" type="application/rss+xml" title="{{ .Site.Title }}" />
{{ partial "head_includes.html" . }}
</head>
<body lang="en">
{{ partial "subheader.html" . }}
<section id="main">
<div>
{{ range first 10 .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{ partial "footer.html" . }}
content/templates/list-and-section-templates.md
+414 -3
View File
@@ -12,9 +12,420 @@ draft: false
slug:
aliases: [/templates/list/]
toc: false
notesforauthors:
needsreview: true
---
## Understanding what is Meant by a "List" Page
A list template is any template that will be used to render multiple pieces of
content in a single HTML page (with the exception of the [homepage](/layout/homepage/) which has a
dedicated template).
## Lookup Order for List and Section Page Templates
We are using the term *list* in its truest sense, a sequential arrangement of material, especially in alphabetical or numerical order. Hugo uses list templates to render anyplace where content is being listed such as taxonomies and sections.
## List and Section Template Lookup Order
Hugo uses a set of rules to figure out which template to use when
rendering a specific page.
Hugo will use the following prioritized list. If a file isn’t present,
then the next one in the list will be used. This enables you to craft
specific layouts when you want to without creating more templates
than necessary. For most sites only the \_default file at the end of
the list will be needed.
### Section Lists
A Section will be rendered at /`SECTION`/ (e.g.&nbsp;http://spf13.com/project/)
* /layouts/section/`SECTION`.html
* /layouts/\_default/section.html
* /layouts/\_default/list.html
* /themes/`THEME`/layouts/section/`SECTION`.html
* /themes/`THEME`/layouts/\_default/section.html
* /themes/`THEME`/layouts/\_default/list.html
Note that a sections list page can also have a content file with frontmatter, see [Source Organization](/overview/source-directory/}}).
### 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 frontmatter, see [Source Organization](/overview/source-directory/).
### Section RSS
A Section’s RSS will be rendered at /`SECTION`/index.xml (e.g.&nbsp;http://spf13.com/project/index.xml)
*Hugo ships with its own [RSS 2.0][] template. In most cases this will
be sufficient, and an RSS template will not need to be provided by the
user.*
Hugo provides the ability for you to define any RSS type you wish, and
can have different RSS files for each section and taxonomy.
* /layouts/section/`SECTION`.rss.xml
* /layouts/\_default/rss.xml
* /themes/`THEME`/layouts/section/`SECTION`.rss.xml
* /themes/`THEME`/layouts/\_default/rss.xml
### Taxonomy RSS
A Taxonomy’s RSS will be rendered at /`PLURAL`/`TERM`/index.xml (e.g.&nbsp;http://spf13.com/topics/golang/index.xml)
*Hugo ships with its own [RSS 2.0][] template. In most cases this will
be sufficient, and an RSS template will not need to be provided by the
user.*
Hugo provides the ability for you to define any RSS type you wish, and
can have different RSS files for each section and taxonomy.
* /layouts/taxonomy/`SINGULAR`.rss.xml
* /layouts/\_default/rss.xml
* /themes/`THEME`/layouts/taxonomy/`SINGULAR`.rss.xml
* /themes/`THEME`/layouts/\_default/rss.xml
## Variables
A list page is a `Page` and have all the [page variables](/templates/variables/)
and [site variables](/templates/variables/) available to use in the templates.
Taxonomy pages will additionally have:
**.Data.`Singular`** The taxonomy itself.<br>
## Example List Template Pages
### Example section template (post.html)
This content template is used for [spf13.com](http://spf13.com/).
It makes use of [partial templates](/templates/partials/). All examples use a
[view](/templates/views/) called either "li" or "summary" which this example site
defined.
{{ partial "header.html" . }}
{{ partial "subheader.html" . }}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
<ul id="list">
{{ range .Data.Pages }}
{{ .Render "li"}}
{{ end }}
</ul>
</div>
</section>
{{ partial "footer.html" . }}
### Example taxonomy template (tag.html)
This content template is used for [spf13.com](http://spf13.com/).
It makes use of [partial templates](/templates/partials/). All examples use a
[view](/templates/views/) called either "li" or "summary" which this example site
defined.
{{ partial "header.html" . }}
{{ partial "subheader.html" . }}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{ partial "footer.html" . }}
## Ordering Content
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
your list templates:
### Order by Weight -> Date (default)
{{ range .Data.Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Weight -> Date
{{ range .Data.Pages.ByWeight }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Date
{{ range .Data.Pages.ByDate }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by PublishDate
{{ range .Data.Pages.ByPublishDate }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by ExpiryDate
{{ range .Data.Pages.ByExpiryDate }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Lastmod
{{ range .Data.Pages.ByLastmod }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Length
{{ range .Data.Pages.ByLength }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Title
{{ range .Data.Pages.ByTitle }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by LinkTitle
{{ range .Data.Pages.ByLinkTitle }}
<li>
<a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Parameter
Order based on the specified frontmatter parameter. Pages without that
parameter will use the site's `.Site.Params` default. If the parameter is not
found at all in some entries, those entries will appear together at the end
of the ordering.
The below example sorts a list of posts by their rating.
{{ range (.Data.Pages.ByParam "rating") }}
<!-- ... -->
{{ end }}
If the frontmatter field of interest is nested beneath another field, you can
also get it:
{{ range (.Date.Pages.ByParam "author.last_name") }}
<!-- ... -->
{{ end }}
### Reverse Order
Can be applied to any of the above. Using Date for an example.
{{ range .Data.Pages.ByDate.Reverse }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
## Grouping Content
Hugo provides some grouping functions for list pages. You can use them to
group pages by Section, Type, Date etc.
Here are a variety of different ways you can group the content items in
your list templates:
### Grouping by Page field
{{ range .Data.Pages.GroupBy "Section" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
### Grouping by Page date
{{ range .Data.Pages.GroupByDate "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
### Grouping by Page publish date
{{ range .Data.Pages.GroupByPublishDate "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
### Grouping by Page param
{{ range .Data.Pages.GroupByParam "param_key" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
### Grouping by Page param in date format
{{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
### Reversing Key Order
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
it’s really just a matter of preference.
#### Reverse method
{{ range (.Data.Pages.GroupBy "Section").Reverse }}
...
{{ range (.Data.Pages.GroupByDate "2006-01").Reverse }}
...
#### Providing the (alternate) direction
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
...
{{ range .Data.Pages.GroupBy "Section" "desc" }}
...
### Ordering Pages within Group
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
within each group in alphabetical order by title.
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages.ByTitle }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
## 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,
you can do just that.
### `first`
`first` works like the `limit` keyword in SQL. It reduces the array to only the
first _N_ elements. It takes the array and number of elements as input.
{{ range first 10 .Data.Pages }}
{{ .Render "summary" }}
{{ end }}
### `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'.
{{ range where .Data.Pages "Section" "post" }}
{{ .Content }}
{{ end }}
### `first` & `where` Together
Using both together can be very powerful.
{{ range first 5 (where .Data.Pages "Section" "post") }}
{{ .Content }}
{{ end }}
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/),
[terms](/templates/terms/) and [groups](/templates/list/).
[RSS 2.0]: http://cyber.law.harvard.edu/rss/rss.html "RSS 2.0 Specification"
content/templates/local-file-templates.md
+5 -10
View File
@@ -10,23 +10,18 @@ categories: [templates]
tags: [files]
draft: false
weight:
aliases: [/extras/localfiles/]
aliases: [/extras/localfiles/,/templates/files/]
toc: true
notesforauthors:
needsreview: true
---
## Traversing Local Files
Hugo's [`readDir` function][], you can traverse your website's files on your server.
With Hugo's [`readDir` function][], you can traverse your website's files on your server.
## Using _readDir_
The `readDir` function returns an array
of [`os.FileInfo`](https://golang.org/pkg/os/#FileInfo).
It takes a single, string argument: a path.
This path can be to any directory of your website
(as found on your server's filesystem).
The `readDir` function returns an array of [`os.FileInfo`](https://golang.org/pkg/os/#FileInfo). It takes a single, string argument: a path. This path can be to any directory of your website (as found on your server's filesystem).
Whether the path is absolute or relative makes no difference,
because&mdash;at least for `readDir`&mdash;the root of your website (typically `./public/`)
@@ -35,7 +30,7 @@ in effect becomes both:
1. The filesystem root; and
1. The current working directory.
## New Shortcode
## Example Shortcode: List Directory's Files
So, let's create a new shortcode using `readDir`:
content/templates/menu-templates.md
+85 -2
View File
@@ -10,8 +10,91 @@ categories: [templates]
tags: [lists,sections,menus]
draft: false
slug:
aliases: [/extras/menus/,/templates/menus/]
aliases: [/templates/menus/]
toc: false
notesforauthors:
needsreview: true
---
Hugo makes no assumptions about how your rendered HTML will be
structured. Instead, it provides all of the functions you will need to be
able to build your menu however you want.
The following is an example:
<!--sidebar start-->
<aside>
<div id="sidebar" class="nav-collapse">
<!-- sidebar menu start-->
<ul class="sidebar-menu">
{{ $currentPage := . }}
{{ range .Site.Menus.main }}
{{ if .HasChildren }}
<li class="sub-menu{{if $currentPage.HasMenuCurrent "main" . }} active{{end}}">
<a href="javascript:;" class="">
{{ .Pre }}
<span>{{ .Name }}</span>
<span class="menu-arrow arrow_carrot-right"></span>
</a>
<ul class="sub">
{{ range .Children }}
<li{{if $currentPage.IsMenuCurrent "main" . }} class="active"{{end}}><a href="{{.URL}}"> {{ .Name }} </a> </li>
{{ end }}
</ul>
{{else}}
<li>
<a href="{{.URL}}">
{{ .Pre }}
<span>{{ .Name }}</span>
</a>
{{end}}
</li>
{{end}}
<li> <a href="https://github.com/spf13/hugo/issues" target="blank">Questions and Issues</a> </li>
<li> <a href="#" target="blank">Edit this Page</a> </li>
</ul>
<!-- sidebar menu end-->
</div>
</aside>
<!--sidebar end-->
> **Note**: use the `absLangURL` or `relLangURL` if your theme makes use of the [multilingual feature](/content-management/multilingual-mode/). In contrast to `absURL` and `relURL` it adds the correct language prefix to the url. [Read more](/functions/).
## Section Menu for "the Lazy Blogger"
To enable this menu, add this to your site config, i.e. `config.toml`:
```
SectionPagesMenu = "main"
```
The menu name can be anything, but take a note of what it is.
This will create a menu with all the sections as menu items and all the sections' pages as "shadow-members". The _shadow_ implies that the pages isn't represented by a menu-item themselves, but this enables you to create a top-level menu like this:
```
<nav class="sidebar-nav">
{{ $currentPage := . }}
{{ range .Site.Menus.main }}
<a class="sidebar-nav-item{{if or ($currentPage.IsMenuCurrent "main" .) ($currentPage.HasMenuCurrent "main" .) }} active{{end}}" href="{{.URL}}">{{ .Name }}</a>
{{ end }}
</nav>
```
In the above, the menu item is marked as active if on the current section's list page or on a page in that section.
The above is all that's needed. But if you want custom menu items, e.g. changing weight or name, you can define them manually in the site config, i.e. `config.toml`:
```
[[menu.main]]
name = "This is the blog section"
weight = -110
identifier = "blog"
url = "/blog/"
```
**Note** that the `identifier` must match the section name.
content/templates/pagination.md
+95 -2
View File
@@ -10,7 +10,100 @@ categories: [templates]
tags: [lists,sections,pagination]
draft: false
slug:
aliases: [/extras/pagination]
aliases: [/extras/pagination,/doc/pagination/]
toc: false
notesforauthors:
needsreview: true
---
Hugo supports pagination for the home page, sections and taxonomies. It's built to be easy use, but with loads of flexibility when needed. The real power shines when you combine it with [`where`](/templates/functions/), with its SQL-like operators, `first` and others --- you can even [order the content](/templates/list/) the way you've become used to with Hugo.
## Configuration
Pagination can be configured in the site configuration (e.g. `config.toml`):
* `Paginate` (default `10`) (this setting can be overridden in the template)
* `PaginatePath` (default `page`)
Setting `Paginate` to a positive value will split the list pages for the home page, sections and taxonomies into chunks of that size. But note that the generation of the pagination pages for sections, taxonomies and home page is *lazy* --- the pages will not be created if not referenced by a `.Paginator` (see below).
`PaginatePath` is used to adapt the `URL` to the pages in the paginator (the default setting will produce URLs on the form `/page/1/`.
## List the pages
**A `.Paginator` is provided to help building a pager menu. This is currently only relevant for the templates for the home page and the list pages (sections and taxonomies).**
There are two ways to configure and use a `.Paginator`:
1. The simplest way is just to call `.Paginator.Pages` from a template. It will contain the pages for *that page* .
2. Select a sub-set of the pages with the available template functions and ordering options, and pass the slice to `.Paginate`, e.g. `{{ range (.Paginate ( first 50 .Data.Pages.ByTitle )).Pages }}`.
For a given **Page**, it's one of the options above. The `.Paginator` is static and cannot change once created.
The global page size setting (`Paginate`) can be overridden by providing a positive integer as the last argument. The examples below will give five items per page:
* `{{ range (.Paginator 5).Pages }}`
* `{{ $paginator := .Paginate (where .Data.Pages "Type" "post") 5 }}`
It is also possible to use the `GroupBy` functions in combination with pagination:
```
{{ range (.Paginate (.Data.Pages.GroupByDate "2006")).PageGroups }}
```
## Build the navigation
The `.Paginator` contains enough information to build a paginator interface.
The easiest way to add this to your pages is to include the built-in template (with `Bootstrap`-compatible styles):
```
{{ template "_internal/pagination.html" . }}
```
**Note:** If you use any filters or ordering functions to create your `.Paginator` **and** you want the navigation buttons to be shown before the page listing, you must create the `.Paginator` before it's used:
```
{{ $paginator := .Paginate (where .Data.Pages "Type" "post") }}
{{ template "_internal/pagination.html" . }}
{{ range $paginator.Pages }}
{{ .Title }}
{{ end }}
```
Without the where-filter, the above is simpler:
```
{{ template "_internal/pagination.html" . }}
{{ range .Paginator.Pages }}
{{ .Title }}
{{ end }}
```
If you want to build custom navigation, you can do so using the `.Paginator` object:
* `PageNumber`: The current page's number in the pager sequence
* `URL`: The relative URL to the current pager
* `Pages`: The pages in the current pager
* `NumberOfElements`: The number of elements on this page
* `HasPrev`: Whether there are page(s) before the current
* `Prev`: The pager for the previous page
* `HasNext`: Whether there are page(s) after the current
* `Next`: The pager for the next page
* `First`: The pager for the first page
* `Last`: The pager for the last page
* `Pagers`: A list of pagers that can be used to build a pagination menu
* `PageSize`: Size of each pager
* `TotalPages`: The number of pages in the paginator
* `TotalNumberOfElements`: The number of elements on all pages in this paginator
## Additional information
The pages are built on the following form (`BLANK` means no value):
```
[SECTION/TAXONOMY/BLANK]/index.html
[SECTION/TAXONOMY/BLANK]/page/1/index.html => redirect to [SECTION/TAXONOMY/BLANK]/index.html
[SECTION/TAXONOMY/BLANK]/page/2/index.html
....
```
content/templates/partial-templates.md
+133 -1
View File
@@ -10,13 +10,145 @@ categories: [templates]
tags: [lists,sections,partials]
draft: false
slug:
aliases: [/templates/partials/]
aliases: [/templates/partials/,/layout/chrome/]
toc: true
notesforauthors:
---
## Partials vs Templates
In practice, it's very convenient to split out common template portions into a
partial template that can be included anywhere. As you create the rest of your
templates, you will include templates from the ``/layouts/partials` directory
or from arbitrary subdirectories like `/layouts/partials/post/tag`.
Partials are especially important for themes as it gives users an opportunity
to overwrite just a small part of your theme, while maintaining future compatibility.
Theme developers may want to include a few partials with empty HTML
files in the theme just so end users have an easy place to inject their
customized content.
I've found it helpful to include a header and footer template in
partials so I can include those in all the full page layouts. There is
nothing special about header.html and footer.html other than they seem
like good names to use for inclusion in your other templates.
▾ layouts/
▾ partials/
header.html
footer.html
## Partial vs Template
Version v0.12 of Hugo introduced the `partial` call inside the template system.
This is a change to the way partials were handled previously inside the
template system. In earlier versions, Hugo didn’t treat partials specially, and
you could include a partial template with the `template` call in the standard
template language.
With the addition of the theme system in v0.11, it became apparent that a theme
& override-aware partial was needed.
When using Hugo v0.12 and above, please use the `partial` call (and leave out
the “partial/” path). The old approach would still work, but wouldn’t benefit from
the ability to have users override the partial theme file with local layouts.
## Example header.html
This header template is used for [spf13.com](http://spf13.com/):
<!DOCTYPE html>
<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
<head>
<meta charset="utf-8">
{{ partial "meta.html" . }}
<base href="{{ .Site.BaseURL }}">
<title> {{ .Title }} : spf13.com </title>
<link rel="canonical" href="{{ .Permalink }}">
{{ if .RSSLink }}<link href="{{ .RSSLink }}" rel="alternate" type="application/rss+xml" title="{{ .Title }}" />{{ end }}
{{ partial "head_includes.html" . }}
</head>
<body lang="en">
## Example footer.html
This footer template is used for [spf13.com](http://spf13.com/):
<footer>
<div>
<p>
&copy; 2013-14 Steve Francia.
<a href="http://creativecommons.org/licenses/by/3.0/" title="Creative Commons Attribution">Some rights reserved</a>;
please attribute properly and link back. Hosted by <a href="http://servergrove.com">ServerGrove</a>.
</p>
</div>
</footer>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-XYSYXYSY-X']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script');
ga.src = ('https:' == document.location.protocol ? 'https://ssl' :
'http://www') + '.google-analytics.com/ga.js';
ga.setAttribute('async', 'true');
document.documentElement.firstChild.appendChild(ga);
})();
</script>
</body>
</html>
To reference a partial template stored in a subfolder, e.g. `/layouts/partials/post/tag/list.html`, call it this way:
{{ partial "post/tag/list" . }}
Note that the subdirectories you create under /layouts/partials can be named whatever you like.
For more examples of referencing these templates, see
[single content templates](/templates/content/),
[list templates](/templates/list/) and
[homepage templates](/templates/homepage/).
## Variable scoping
As you might have noticed, `partial` calls receive two parameters.
1. The first is the name of the partial and determines the file
location to be read.
2. The second is the variables to be passed down to the partial.
This means that the partial will _only_ be able to access those variables. It is
isolated and has no access to the outer scope. From within the
partial, `$.Var` is equivalent to `.Var`
## Cached Partials
The `partialCached` template function can offer significant performance gains
for complex templates that don't need to be rerendered upon every invocation.
The simplest usage is as follows:
{{ partialCached "footer.html" . }}
You can also pass additional parameters to `partialCached` to create *variants* of the cached partial.
For example, say you have a complex partial that should be identical when rendered for pages within the same section.
You could use a variant based upon section so that the partial is only rendered once per section:
{{ partialCached "footer.html" . .Section }}
If you need to pass additional parameters to create unique variants,
you can pass as many variant parameters as you need:
{{ partialCached "footer.html" . .Params.country .Params.province }}
Note that the variant parameters are not made available to the underlying partial template.
They are only use to create a unique cache key.
## Built-in Partials
* Google Analytics
content/templates/rss-templates.md
+106 -2
View File
@@ -12,5 +12,109 @@ draft: false
slug:
aliases: [/templates/rss/]
toc: false
notesforauthors:
---
needsreview: true
---
## RSS Template Lookup Order
Like all other templates, you can use a single RSS template to generate all of your RSS feeds, or you can create a specific template for each individual feed.
*Unlike other Hugo templates*, Hugo ships with its own [RSS 2.0 template](#the-embedded-rss-xml:eceb479b7b3b2077408a2878a29e1320). In most cases this will be sufficient, and an RSS template will not need to be provided by the user. But you can provide an rss template if you like, as you can see in the next section.
RSS pages are of the type `Page` and have all the [page variables](/layout/variables/) available to use in the templates.
## Which Template will be rendered?
Hugo uses a set of rules to figure out which template to use when rendering a specific page.
Hugo will use the following prioritized list. If a file isn’t present, then the next one in the list will be used. This enables you to craft specific layouts when you want to without creating more templates than necessary. For most sites only the `\_default` file at the end of the list will be needed.
### Main RSS
* /layouts/rss.xml
* /layouts/\_default/rss.xml
* [Embedded rss.xml](#the-embedded-rss-xml:eceb479b7b3b2077408a2878a29e1320)
### Section RSS
* /layouts/section/`SECTION`.rss.xml
* /layouts/\_default/rss.xml
* /themes/`THEME`/layouts/section/`SECTION`.rss.xml
* /themes/`THEME`/layouts/\_default/rss.xml
* [Embedded rss.xml](#the-embedded-rss-xml:eceb479b7b3b2077408a2878a29e1320)
### Taxonomy RSS
* /layouts/taxonomy/`SINGULAR`.rss.xml
* /layouts/\_default/rss.xml
* /themes/`THEME`/layouts/taxonomy/`SINGULAR`.rss.xml
* /themes/`THEME`/layouts/\_default/rss.xml
* [Embedded rss.xml](#the-embedded-rss-xml:eceb479b7b3b2077408a2878a29e1320)
## Configuring RSS
If the following values are specified in the site’s config file (`config.toml`), then they will be included in the RSS output. Example values are provided.
languageCode = "en-us"
copyright = "This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License."
[author]
name = "My Name Here"
## The Embedded rss.xml
This is the default RSS template that ships with Hugo. It adheres to the [RSS 2.0 Specification][RSS 2.0].
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel>
<title>{{ with .Title }}{{.}} on {{ end }}{{ .Site.Title }}</title>
<link>{{ .Permalink }}</link>
<description>Recent content {{ with .Title }}in {{.}} {{ end }}on {{ .Site.Title }}</description>
<generator>Hugo -- gohugo.io</generator>{{ with .Site.LanguageCode }}
<language>{{.}}</language>{{end}}{{ with .Site.Author.email }}
<managingEditor>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</managingEditor>{{end}}{{ with .Site.Author.email }}
<webMaster>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</webMaster>{{end}}{{ with .Site.Copyright }}
<copyright>{{.}}</copyright>{{end}}{{ if not .Date.IsZero }}
<lastBuildDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>{{ end }}
<atom:link href="{{.URL}}" rel="self" type="application/rss+xml" />
{{ range first 15 .Data.Pages }}
<item>
<title>{{ .Title }}</title>
<link>{{ .Permalink }}</link>
<pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
{{ with .Site.Author.email }}<author>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</author>{{end}}
<guid>{{ .Permalink }}</guid>
<description>{{ .Content | html }}</description>
</item>
{{ end }}
</channel>
</rss>
**Important**: _Hugo will automatically add the following header line to this file on render… please don't include this in the template as it's not valid HTML._
```css
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
```
## Referencing your RSS Feed in `<head>`
In your `header.html` template, you can specify your RSS feed in your `<head></head>` tag like this:
```html
{{ if .RSSLink }}
<link href="{{ .RSSLink }}" rel="alternate" type="application/rss+xml" title="{{ .Site.Title }}" />
<link href="{{ .RSSLink }}" rel="feed" type="application/rss+xml" title="{{ .Site.Title }}" />
{{ end }}
```
... with the autodiscovery link specified by the line with `rel="alternate"`.
The `.RSSLink` will render the appropriate RSS feed URL for the section, whether it's everything, posts in a section, or a taxonomy.
**N.b.**, if you reference your RSS link, be sure to specify the mime type with `type="application/rss+xml"`.
```html
<a href="{{ .URL }}" type="application/rss+xml" target="_blank">{{ .SomeText }}</a>
```
[RSS 2.0]: http://cyber.law.harvard.edu/rss/rss.html "RSS 2.0 Specification"
content/templates/shortcode-templates.md
+1 -2
View File
@@ -11,7 +11,6 @@ tags: [shortcodes]
draft: false
aliases: []
toc: true
notesforauthors:
---
## Creating Custom Shortcodes
@@ -28,7 +27,7 @@ You can create the following types of shortcodes
* Positional parameters
* Named parameters
* Both positional or named parameters (i.e, "flexible")
* Positional *or* named parameters (i.e, "flexible")
* Single-word shortcodes
* Nested
content/templates/single-page-templates.md
+144 -3
View File
@@ -10,9 +10,150 @@ tags: []
categories: [templates]
draft: false
slug:
aliases: []
aliases: [/layout/content/]
toc: false
notesforauthors:
needsreview: true
---
## Lookup Order for Single Page Templates
The primary view of content in Hugo is the single view. Hugo, for every
Markdown file provided, will render it with a single template.
## Lookup Order for Single Page Templates
Hugo uses a set of rules to figure out which template to use when
rendering a specific page.
Hugo will use the following prioritized list. If a file isn’t present,
then the next one in the list will be used. This enables you to craft
specific layouts when you want to without creating more templates
than necessary. For most sites, only the `_default` file at the end of
the list will be needed.
Users can specify the `type` and `layout` in the [front-matter](/content/front-matter/). `Section`
is determined based on the content file’s location. If `type` is provided,
it will be used instead of `section`.
### Single Page
* /layouts/`TYPE`/`LAYOUT`.html
* /layouts/`SECTION`/`LAYOUT`.html
* /layouts/`TYPE`/single.html
* /layouts/`SECTION`/single.html
* /layouts/_default/single.html
* /themes/`THEME`/layouts/`TYPE`/`LAYOUT`.html
* /themes/`THEME`/layouts/`SECTION`/`LAYOUT`.html
* /themes/`THEME`/layouts/`TYPE`/single.html
* /themes/`THEME`/layouts/`SECTION`/single.html
* /themes/`THEME`/layouts/_default/single.html
## Example Single Template File
Content pages are of the type "page" and have all the [page variables](/layout/variables/) and [site variables](/templates/variables/) available to use in the templates.
In the following examples we have created two different content types as well as a default content type.
The default content template to be used in the event that a specific template has not been provided for that type. The default type works the same as the other types, but the directory must be called "\_default".
▾ layouts/
▾ _default/
single.html
▾ post/
single.html
▾ project/
single.html
### post/single.html
This content template is used for [spf13.com](http://spf13.com/). It makes use of [partial templates](/templates/partials/)
{{ partial "header.html" . }}
{{ partial "subheader.html" . }}
{{ $baseURL := .Site.BaseURL }}
<section id="main">
<h1 id="title">{{ .Title }}</h1>
<div>
<article id="content">
{{ .Content }}
</article>
</div>
</section>
<aside id="meta">
<div>
<section>
<h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4>
<h5 id="wc"> {{ .FuzzyWordCount }} Words </h5>
</section>
<ul id="categories">
{{ range .Params.topics }}
<li><a href="{{ $baseURL }}/topics/{{ . | urlize }}">{{ . }}</a> </li>
{{ end }}
</ul>
<ul id="tags">
{{ range .Params.tags }}
<li> <a href="{{ $baseURL }}/tags/{{ . | urlize }}">{{ . }}</a> </li>
{{ end }}
</ul>
</div>
<div>
{{ if .Prev }}
<a class="previous" href="{{.Prev.Permalink}}"> {{.Prev.Title}}</a>
{{ end }}
{{ if .Next }}
<a class="next" href="{{.Next.Permalink}}"> {{.Next.Title}}</a>
{{ end }}
</div>
</aside>
{{ partial "disqus.html" . }}
{{ partial "footer.html" . }}
### project/single.html
This content template is used for [spf13.com](http://spf13.com/). It makes use of [partial templates](/templates/partials/)
{{ partial "header.html" . }}
{{ partial "subheader.html" . }}
{{ $baseURL := .Site.BaseURL }}
<section id="main">
<h1 id="title">{{ .Title }}</h1>
<div>
<article id="content">
{{ .Content }}
</article>
</div>
</section>
<aside id="meta">
<div>
<section>
<h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4>
<h5 id="wc"> {{ .FuzzyWordCount }} Words </h5>
</section>
<ul id="categories">
{{ range .Params.topics }}
<li><a href="{{ $baseURL }}/topics/{{ . | urlize }}">{{ . }}</a> </li>
{{ end }}
</ul>
<ul id="tags">
{{ range .Params.tags }}
<li> <a href="{{ $baseURL }}/tags/{{ . | urlize }}">{{ . }}</a> </li>
{{ end }}
</ul>
</div>
</aside>
{{if isset .Params "project_url" }}
<div id="ribbon">
<a href="{{ index .Params "project_url" }}" rel="me">Fork me on GitHub</a>
</div>
{{ end }}
{{ partial "footer.html" . }}
Notice how the project/single.html template uses an additional parameter unique to this template. This doesn't need to be defined ahead of time. If the key is present in the front matter than it can be used in the template. To easily generate new content of this type with these keys ready use [content archetypes](/content/archetypes/).
content/templates/sitemap-template.md
+58 -4
View File
@@ -1,6 +1,6 @@
---
title: Sitemap Template
linktitle:
linktitle: Sitemap
description:
date: 2017-02-01
publishdate: 2017-02-01
@@ -10,7 +10,61 @@ tags: [sitemap, xml]
categories: [templates]
draft: false
slug:
aliases: []
aliases: [/layout/sitemap/,/templates/sitemap/]
toc: false
notesforauthors:
---
needsreview: true
---
A single Sitemap template is used to generate the `sitemap.xml` file.
Hugo automatically comes with this template file. **No work is needed on
the users' part unless they want to customize `sitemap.xml`.**
A sitemap is a `Page` and have all the [page variables](/layout/variables/) available to use in this template along with Sitemap-specific ones:
`.Sitemap.ChangeFreq`
: The page change frequency
`.Sitemap.Priority`
: The priority of the page
`.Sitemap.Filename`
: The sitemap filename
If provided, Hugo will use `/layouts/sitemap.xml` instead of the internal one.
## Hugo’s sitemap.xml
This template respects the version 0.9 of the [Sitemap Protocol](http://www.sitemaps.org/protocol.html).
```xml
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
{{ range .Data.Pages }}
<url>
<loc>{{ .Permalink }}</loc>{{ if not .Lastmod.IsZero }}
<lastmod>{{ safeHTML ( .Lastmod.Format "2006-01-02T15:04:05-07:00" ) }}</lastmod>{{ end }}{{ with .Sitemap.ChangeFreq }}
<changefreq>{{ . }}</changefreq>{{ end }}{{ if ge .Sitemap.Priority 0.0 }}
<priority>{{ .Sitemap.Priority }}</priority>{{ end }}
</url>
{{ end }}
</urlset>
```
{{% note %}}
Hugo will automatically add the following header line to this file
on render. Please don't include this in the template as it's not valid HTML.
`<?xml version="1.0" encoding="utf-8" standalone="yes" ?>`
{{% /note %}}
## Configuring `sitemap.xml`
Defaults for `<changefreq>`, `<priority>` and `filename` values can be set in the site's config file, e.g.:
```toml
[sitemap]
changefreq = "monthly"
priority = 0.5
filename = "sitemap.xml"
```
The same fields can be specified in an individual page's front matter in order to override the value for that page.
content/templates/taxonomy-templates.md
+255 -5
View File
@@ -10,16 +10,266 @@ categories: [templates]
weight:
draft: false
slug:
aliases: []
aliases: [/taxonomies/displaying/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/]
needsreview: true
toc: true
notesforauthors:
---
## Taxonomy Terms Page Templates
<!-- Begin /taxonomies/methods/ -->
### Lookup Order for Taxonomy Terms Page Templates
Hugo makes a set of values and methods available on the various Taxonomy structures.
## Taxonomy List Page Templates
## Taxonomy Methods
### Lookup Order for Taxonomy List Page Templates
A Taxonomy is a `map[string]WeightedPages`.
.Get(term)
: Returns the WeightedPages for a term.
.Count(term)
: The number of pieces of content assigned to this term.
.Alphabetical
: Returns an OrderedTaxonomy (slice) ordered by Term.
.ByCount
: Returns an OrderedTaxonomy (slice) ordered by number of entries.
## OrderedTaxonomy
Since Maps are unordered, an OrderedTaxonomy is a special structure that has a defined order.
```go
[]struct {
Name string
WeightedPages WeightedPages
}
```
Each element of the slice has:
.Term
: The Term used.
.WeightedPages
: A slice of Weighted Pages.
.Count
: The number of pieces of content assigned to this term.
.Pages
: All Pages assigned to this term. All [list methods](/templates/list/) are available to this.
## WeightedPages
WeightedPages is simply a slice of WeightedPage.
```go
type WeightedPages []WeightedPage
```
.Count(term)
: The number of pieces of content assigned to this term.
.Pages
: Returns a slice of pages, which then can be ordered using any of the [list methods](/templates/list/).
<!-- Begin /taxonomies/ordering/ -->
Hugo provides the ability to both:
1. Order the way the keys for a taxonomy are displayed
2. Order the way taxonomyed content appears
## Ordering Taxonomies
Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key.
### Order Alphabetically Example
<ul>
{{ $data := .Data }}
{{ range $key, $value := .Data.Taxonomy.Alphabetical }}
<li><a href="{{ .Site.LanguagePrefix }}/{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li>
{{ end }}
</ul>
### Order by Popularity Example
<ul>
{{ $data := .Data }}
{{ range $key, $value := .Data.Taxonomy.ByCount }}
<li><a href="{{ .Site.LanguagePrefix }}/{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li>
{{ end }}
</ul>
[See Also Taxonomy Lists](/templates/list/)
## Ordering Content within Taxonomies
Hugo uses both **Date** and **Weight** to order content within taxonomies.
Each piece of content in Hugo can optionally be assigned a date.
It can also be assigned a weight for each taxonomy it is assigned to.
When iterating over content within taxonomies the default sort is first by weight then by date. This means that if the weights for two pieces of content are the same, than the more recent content will be displayed first. The default weight for any piece of content is 0.
### Assigning Weight
Content can be assigned weight for each taxonomy that it's assigned to.
```toml
+++
tags = [ "a", "b", "c" ]
tags_weight = 22
categories = ["d"]
title = "foo"
categories_weight = 44
+++
Front Matter with weighted tags and categories
```
The convention is `taxonomyname_weight`.
In the above example, this piece of content has a weight of 22 which applies to the sorting when rendering the pages assigned to the "a", "b" and "c" values of the 'tag' taxonomy.
It has also been assigned the weight of 44 when rendering the 'd' category.
With this the same piece of content can appear in different positions in different taxonomies.
Currently taxonomies only support the default ordering of content which is weight -> date.
<!-- Begin /taxonomies/templates/ -->
There are two different templates that the use of taxonomies will require you to provide.
Both templates are covered in detail in the templates section.
A [list template](/templates/list/) is any template that will be used to render multiple pieces of
content in a single html page. This template will be used to generate
all the automatically created taxonomy pages.
A [taxonomy terms template](/templates/terms/) is a template used to
generate the list of terms for a given template.
<!-- Begin /taxonomies/displaying/ -->
There are four common ways you can display the data in your
taxonomies in addition to the automatic taxonomy pages created by hugo
using the [list templates](/templates/list/):
1. For a given piece of content, you can list the terms attached
2. For a given piece of content, you can list other content with the same
term
3. You can list all terms for a taxonomy
4. You can list all taxonomies (with their terms)
## 1. Displaying taxonomy terms assigned to this content
Within your content templates, you may wish to display
the taxonomies that that piece of content is assigned to.
Because we are leveraging the front matter system to
define taxonomies for content, the taxonomies assigned to
each content piece are located in the usual place
(.Params.`plural`).
### Example
<ul id="tags">
{{ range .Params.tags }}
<li><a href="{{ "/tags/" | relLangURL }}{{ . | urlize }}">{{ . }}</a> </li>
{{ end }}
</ul>
If you want to list taxonomies inline, you will have to take
care of optional plural ending in the title (if multiple taxonomies),
as well as commas. Let's say we have a taxonomy "directors" such as
`directors: [ "Joel Coen", "Ethan Coen" ]` in the TOML-format front matter.
To list such taxonomy use the following:
### Example
{{ if .Params.directors }}
<strong>Director{{ if gt (len .Params.directors) 1 }}s{{ end }}:</strong>
{{ range $index, $director := .Params.directors }}{{ if gt $index 0 }}, {{ end }}<a href="{{ "/directors/" | relURL }}{{ . | urlize }}">{{ . }}</a>{{ end }}
{{ end }}
Alternatively, you may use the [delimit](/templates/functions/) template function as a shortcut if the taxonomies should just be listed with a separator. See {{< gh 2143 >}} on GitHub for discussion.
## 2. Listing content with the same taxonomy term
First, you may be asking why you would use this. If you are using a taxonomy for something like a series of posts, this is exactly how you would do it. It’s also an quick and dirty way to show some related content.
### Example
```html
<ul>
{{ range .Site.Taxonomies.series.golang }}
<li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li>
{{ end }}
</ul>
```
## 3. Listing all content in a given taxonomy
This would be very useful in a sidebar as “featured content”. You could
even have different sections of “featured content” by assigning
different terms to the content.
### Example
<section id="menu">
<ul>
{{ range $key, $taxonomy := .Site.Taxonomies.featured }}
<li> {{ $key }} </li>
<ul>
{{ range $taxonomy.Pages }}
<li hugo-nav="{{ .RelPermalink}}"><a href="{{ .Permalink}}"> {{ .LinkTitle }} </a> </li>
{{ end }}
</ul>
{{ end }}
</ul>
</section>
## 4. Rendering a Site's Taxonomies
If you wish to display the list of all keys for a taxonomy, you can find retrieve
them from the `.Site` variable which is available on every page.
This may take the form of a tag cloud, a menu or simply a list.
The following example displays all tag keys:
### Example
<ul id="all-tags">
{{ range $name, $taxonomy := .Site.Taxonomies.tags }}
<li><a href="{{ "/tags/" | relLangURL }}{{ $name | urlize }}">{{ $name }}</a></li>
{{ end }}
</ul>
### Complete Example
This example will list all taxonomies, each of their keys and all the content assigned to each key.
<section>
<ul>
{{ range $taxonomyname, $taxonomy := .Site.Taxonomies }}
<li><a href="{{ "/" | relLangURL}}{{ $taxonomyname | urlize }}">{{ $taxonomyname }}</a>
<ul>
{{ range $key, $value := $taxonomy }}
<li> {{ $key }} </li>
<ul>
{{ range $value.Pages }}
<li hugo-nav="{{ .RelPermalink}}"><a href="{{ .Permalink}}"> {{ .LinkTitle }} </a> </li>
{{ end }}
</ul>
{{ end }}
</ul>
</li>
{{ end }}
</ul>
</section>
content/templates/template-debugging.md
+47 -2
View File
@@ -12,5 +12,50 @@ draft: false
slug:
aliases: []
toc: false
notesforauthors:
---
needsreview: true
---
# Template Debugging
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/).
### What variables are available in this context?
You can use the template syntax, `$.`, to get the top-level template context from anywhere in your template. This will print out all the values under, `.Site`.
{{ printf "%#v" $.Site }}
This will print out the value of `.Permalink`:
{{ printf "%#v" .Permalink }}
This will print out a list of all the variables scoped to the current context
(a.k.a. The dot, "`.`").
{{ printf "%#v" . }}
When writing a [Homepage](/templates/homepage), what does one of the pages
you're looping through look like?
```
{{ range .Data.Pages }}
{{/* The context, ".", is now a Page */}}
{{ printf "%#v" . }}
{{ end }}
```
### Why do I have no variables defined?
Check that you are passing variables in the `partial` function. For example
```
{{ partial "header" }}
```
will render the header partial, but the header partial will not have access to any variables. You need to pass variables explicitly. For example:
```
{{ partial "header" . }}
```
content/themes/creating-a-theme.md
+69 -3
View File
@@ -11,10 +11,76 @@ weight: 30
draft: false
aliases: [/themes/creation/]
toc: false
needsreview: true
---
{{% warning "Use Proper Cross References" %}}
When creating your theme, it is not always safe to assume that the end user of the theme is working from the root directory of the website. That said, whenever possible, use Hugo's powerful [URL management functions](/content-management/url-management/).
{{% warning "Use Relative Links" %}}
When creating your theme, it is not always safe to assume that the end user of the theme is working from the root directory of the website.
{{% /warning %}}
Hugo has the ability to create a new theme in your themes directory for you
using the `hugo new` command.
`hugo new theme [name]`
This command will initialize all of the files and directories a basic theme
would need. Hugo themes are written in the Go template language. If you are new
to Go, the [Go template primer](/layout/go-templates/) will help you get started.
## Theme Components
A theme consists of templates and static assets such as javascript and css
files. Themes can also optionally provide [archetypes](/content/archetypes/)
which are archetypal content types used by the `hugo new` command.
### Layouts
Hugo is built around the concept that things should be as simple as possible.
Fundamentally website content is displayed in two different ways, a single
piece of content and a list of content items. With Hugo a theme layout starts
with the defaults. As additional layouts are defined they are used for the
content type or section they apply to. This keeps layouts simple, but permits
a large amount of flexibility.
### Single Content
The default single file layout is located at `layouts/_default/single.html`.
### List of Contents
The default list file layout is located at `layouts/_default/list.html`.
### Partial Templates
Theme creators should liberally use [partial templates](/templates/partials/)
throughout their theme files. Not only is a good DRY practice to include shared
code, but partials are a special template type that enables the themes end user
to be able to overwrite just a small piece of a file or inject code into the
theme from their local /layouts. These partial templates are perfect for easy
injection into the theme with minimal maintenance to ensure future
compatibility.
### Static
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:
/css
/js
/img
The actual structure is entirely up to you, the theme creator, on how you would like to organize your files.
### Archetypes
If your theme makes use of specific keys in the front matter, it is a good idea
to provide an archetype for each content type you have. Archetypes follow the
[guidelines provided](/content/archetypes/).
### Generator meta tag
With a growing community around Hugo we recommend theme creators to include the [Generator meta tag](/templates/variables/) with `.Hugo.Generator` in the `<head>` of your HTML code. The output might looks like `<meta name="generator" content="Hugo 0.13" />` and helps us to analyse the usage and popularity of Hugo.
content/themes/customizing-a-theme.md
+45
View File
@@ -11,5 +11,50 @@ weight: 20
draft: false
aliases: [/themes/customizing/,/themes/customize/]
toc: false
needsreview: true
---
_The following are key concepts for Hugo site customization. Hugo permits you to **supplement or override** any theme template or static file, with files in your working directory._
_When you use a theme cloned from its git repository, you do not edit the theme's files directly. Rather, you override them as per the following:_
## Replace Static Files
For including a different file than what the theme ships with. For example, if you would like to use a more recent version of jQuery than what the theme happens to include, simply place an identically-named file in the same relative location but in your working directory.
For example, if the theme has jQuery 1.6 in:
/themes/themename/static/js/jquery.min.js
... you would simply place your file in the same relative path, but in the root of your working folder:
/static/js/jquery.min.js
## Replace a single template file
Anytime Hugo looks for a matching template, it will first check the working directory before looking in the theme directory. If you would like to modify a template, simply create that template in your local `layouts` directory.
In the [template documentation](/templates/overview/) _each different template type explains the rules it uses to determine which template to use_. Read and understand these rules carefully.
This is especially helpful when the theme creator used [partial templates](/templates/partials/). These partial templates are perfect for easy injection into the theme with minimal maintenance to ensure future compatibility.
For example:
/themes/themename/layouts/_default/single.html
... would be overridden by:
/layouts/_default/single.html
**Warning**: This only works for templates that Hugo "knows about" (that follow its convention for folder structure and naming). If the theme imports template files in a creatively-named directory, Hugo won’t know to look for the local `/layouts` first.
## Replace an archetype
If the archetype that ships with the theme for a given content type (or all content types) doesn’t fit with how you are using the theme, feel free to copy it to your `/archetypes` directory and make modifications as you see fit.
## 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.
It is usually better to override specific files rather than using the default in your working directory.
content/themes/installing-and-using-themes.md
+1
View File
@@ -11,6 +11,7 @@ weight: 10
draft: false
aliases: [/themes/usage/,/themes/installing/]
toc: true
needsreview: true
---
{{% note "No Default Theme" %}}
content/variables-and-params/_index.md
+5 -1
View File
@@ -1,5 +1,5 @@
---
title: Variables and Params
title: Overview
linktitle: Overview
description: Page-, file-, taxonomy-, and site-level variables and parameters available in templates.
date: 2017-02-01
@@ -14,3 +14,7 @@ toc: false
hidesectioncontents: false
needsreview: true
---
[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."
content/variables-and-params/file-variables.md
+30 -7
View File
@@ -15,10 +15,33 @@ needsreview: true
notesforauthors:
---
**.File.Path** The original relative path of the page, e.g. `content/posts/foo.en.md`<br>
**.File.LogicalName** The name of the content file that represents a page, e.g. `foo.en.md`<br>
**.File.TranslationBaseName** The filename without extension or optional language identifier, e.g. `foo`<br>
**.File.BaseFileName** The filename without extension, e.g. `foo.en`<br>
**.File.Ext** or **.File.Extension** The file extension of the content file, e.g. `md`<br>
**.File.Lang** The language associated with the given file if [Multilingual](/content-management/multilingual-mode/ is enabled, e.g. `en`<br>
**.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/`<br>
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" %}}
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 %}}
The `.File` object contains the following fields:
`.File.Path`
: The original relative path of the page (e.g., `content/posts/foo.en.md`)
`.File.LogicalName`
: The name of the content file that represents a page (e.g., `foo.en.md`)
`.File.TranslationBaseName`
: The filename without extension or optional language identifier (e.g., `foo`)
`.File.BaseFileName`
: The filename without extension (e.g., `foo.en`)
`.File.Ext`
: 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`)
`.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/`)
[Multilingual]: /content-management/multilingual-mode/
content/variables-and-params/page-variables.md
+163 -65
View File
@@ -1,7 +1,7 @@
---
title: Page Variables
linktitle:
description:
description: Page-level variables are defined in a content file's front matter, derived from the content's file location, or extracted from the content body itself.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
@@ -10,9 +10,7 @@ tags: [pages]
draft: false
weight: 20
aliases: []
toc: false
needsreview: true
notesforauthors:
toc: true
---
The following is a list of page-level variables that can be defined for a piece of content. Many of these will be defined in the front matter, derived from file location, or extracted from the content itself.
@@ -21,55 +19,154 @@ The following is a list of page-level variables that can be defined for a piece
See [`.Scratch`](/functions/scratch/) for page-scoped writable variables.
{{% /note %}}
* `.Content` The content itself, defined below the front matter.
* `.Data` The data specific to this type of page.
* `.Date` The date the page is associated with.
* `.Description` The description for the page.
* `.Draft` A boolean, `true` if the content is marked as a draft in the front matter.
* `.ExpiryDate` The date where the content is scheduled to expire on.
* `.FuzzyWordCount` The approximate number of words in the content.
* `.Hugo` See [Hugo Variables][hugovariables]
* `.IsHome` True if this is the home page.
* `.IsNode` Always false for regular content pages.
* `.IsPage` Always true for regular content pages.
* `.IsTranslated` Whether there are any translations to display.
* `.Keywords` The meta keywords for this content.
* `.Kind` What *kind* of page is this: is one of *page, home, section, taxonomy or taxonomyTerm.* There are also *RSS, sitemap, robotsTXT and 404*, but these will only available during rendering of that kind of page, and not available in any of the `Pages` collections.
* `.Lang` Language taken from the language extension notation.
* `.Language` A language object that points to this the language's definition in the site config.
* `.Lastmod` The date the content was last modified.
* `.LinkTitle` Access when creating links to this content. Will use `linktitle` if set in front matter, else `title`.
* `.Next` Pointer to the following content (based on pub date).
* `.NextInSection` Pointer to the following content within the same section (based on pub date)
* `.Pages` a collection of associated pages. This will be nil for regular content pages. This is an alias for `.Data.Pages`.
* `.Permalink` The Permanent link for this page.
* `.Prev` Pointer to the previous content (based on pub date).
* `.PrevInSection` Pointer to the previous content within the same section (based on `.PublishDate`). For example, `{{if .PrevInSection}}{{.PrevInSection.Permalink}}{{end}}`.
* `.PublishDate` The date the content is published on.
* `.RSSLink` Link to the taxonomies' RSS link.
* `.RawContent` Raw markdown content without the front matter. Useful with [remarkjs.com](http://remarkjs.com)
* `.ReadingTime` The estimated time it takes to read the content in minutes.
* `.Ref` Returns the permalink for a given reference;e.g., `.Ref "sample.md"`. See [Cross References][crossreferences]. Does not handle in-page fragments correctly.
* `.RelPermalink` The Relative permanent link for this page.
* `.RelRef` Returns the relative permalink for a given reference. Example: `RelRef "sample.md"`. See [Cross References][crossreferences]. This does not handle in-page fragments.
* `.Section` The [section](/content-management/content-sections/) this content belongs to.
* `.Site` See [Site Variables][sitevariables] below.
* `.Summary` A generated summary of the content for easily showing a snippet in a summary view. Note that the breakpoint can be set manually by inserting <code>&lt;!&#x2d;&#x2d;more&#x2d;&#x2d;&gt;</code> at the appropriate place in the content page. See [Summaries](/content/summaries/) for more details.
* `.TableOfContents` The rendered [table of contents](/content-management/table-of-contents/) for the page.
* `.Title` The title for this page.
* `.Translations` A list of translated versions of the current page. See [Multilingual](/content-management/multilingual-mode/) for more info.
* `.Truncated` A boolean, `true` if the `.Summary` is truncated. Useful for showing a "Read more..." link only if necessary. See [Summaries](/content/summaries/) for more details.
* `.Type` The [content type][] (e.g., `post`).
* `.URL` The relative URL for this page. Note that if `URL` is set directly in front matter, that URL is returned as-is.
* `.UniqueID` The MD5-checksum of the content file's path
* `.Weight` Assigned weight (in the front matter) to this content, used in sorting.
* `.WordCount` The number of words in the content.
## Page Variables List
`.Content`
: the content itself, defined below the front matter.
`.Data`
: the data specific to this type of page.
`.Date`
: the date associated with the page.
`.Description`
: the description for the page.
`.Draft`
: a boolean, `true` if the content is marked as a draft in the front matter.
`.ExpiryDate`
: the date on which the content is scheduled to expire.
`.FuzzyWordCount`
: the approximate number of words in the content.
`.Hugo`
: see [Hugo Variables](/variables-and-params/shortcode-git-and-hugo-variables/).
`.IsHome`
: `true` in the context of the [home page](/templates/homepage-template/).
`.IsNode`
: always `false` for regular content pages.
`.IsPage`
: always `true` for regular content pages.
`.IsTranslated`
: `true` if there are translations to display.
`.Keywords`
: the meta keywords for the content.
`.Kind`
: the page's *kind*. Possible return values are `page`, `home`, `section`, `taxonomy`, or `taxonomyTerm`. Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` kinds, but these are only available during the rendering of each of these respective page's kind and therefore *not* available in any of the `Pages` collections.
`.Lang`
: language taken from the language extension notation.
`.Language`
: a language object that points to the language's definition in the site
`config`.
`.Lastmod`
: the date the content was last modified (i.e. from `lastmod` in the content's front matter)
`.LinkTitle`
: access when creating links to the content. If set, Hugo will use the `linktitle` from the front matter before `title`.
`.Next`
: pointer to the following content (based on `publishdate` in front matter).
`.NextInSection`
: pointer to the following content within the same section (based on `publishdate` in front matter).
`.Pages`
: a collection of associated pages. This value will be `nil` for regular content pages. `.Pages` is an alias for `.Data.Pages`.
`.Permalink`
: the Permanent link for this page; see [Permalinks](/content-management/url-management/)
`.Prev`
: Pointer to the previous content (based on `publishdate` in front matter).
`.PrevInSection`
: Pointer to the previous content within the same section (based on `publishdate` in front matter). For example, `{{if .PrevInSection}}{{.PrevInSection.Permalink}}{{end}}`.
`.PublishDate`
: the date on which the content was or will be published.
`.RSSLink`
: link to the taxonomies' RSS link.
`.RawContent`
: raw markdown content without the front matter. Useful with [remarkjs.com](
http://remarkjs.com)
`.ReadingTime`
: the estimated time, in minutes, it takes to read the content.
`.Ref`
: returns the permalink for a given reference (e.g., `.Ref "sample.md"`). `.Ref` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/).
`.RelPermalink`
: the relative permanent link for this page.
`.RelRef`
: returns the relative permalink for a given reference (e.g., `RelRef
"sample.md"`). `.RelRef` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/).
`.Section`
: the [section](/content-management/content-sections/) this content belongs to.
`.Site`
: see [Site Variables](/variables-and-params/site-variables/).
`.Summary`
: a generated summary of the content for easily showing a snippet in a summary view. The breakpoint can be set manually by inserting <code>&lt;!&#x2d;&#x2d;more&#x2d;&#x2d;&gt;</code> at the appropriate place in the content page. See [Content Summaries](/content-management/content-summaries/) for more details.
`.TableOfContents`
: the rendered [table of contents](/content-management/table-of-contents/) for the page.
`.Title`
: the title for this page.
`.Translations`
: a list of translated versions of the current page. See [Multilingual Mode](/content-management/multilingual-mode/) for more information.
`.Truncated`
: a boolean, `true` if the `.Summary` is truncated. Useful for showing a "Read more..." link only when necessary. See [Summaries](/content-management/content-summaries/) for more information.
`.Type`
: the [content type](/content-management/content-types/) of the content (e.g., `post`).
`.URL`
: the relative URL for the page. Note that the `URL` set directly in front
matter overrides the default relative URL for the page.
`.UniqueID`
: the MD5-checksum of the content file's path.
`.Weight`
: assigned weight (in the front matter) to this content, used in sorting.
`.WordCount`
: the number of words in the content.
## Page-level Params
Any other value defined in the front matter, including taxonomies, will be made available as part of the `.Params variable.
Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable.
For example, the *tags* and *categories* taxonomies are accessed with:
```yaml
---
title: My First Post
date: date: 2017-02-20T15:26:23-06:00
categories: [one]
tags: [two,three,four]
```
With the above front matter, the `tags` and `categories` taxonomies are accessible via the following:
* `.Params.tags`
* `.Params.categories`
@@ -78,46 +175,52 @@ For example, the *tags* and *categories* taxonomies are accessed with:
Page-level `.Params` are *only* accessible in lowercase.
{{% /note %}}
This is particularly useful for the introduction of user-defined fields in content files. For example, a Hugo website on book reviews could have the following front matter in `/content/review/book01.md`:
The `.Params` variable is particularly useful for the introduction of user-defined front matter fields in content files. For example, a Hugo website on book reviews could have the following front matter in `/content/review/book01.md`:
```yaml
---
...
affiliatelink: "http://www.my-book-link.here"
recommendedby: "My Mother"
...
---
```
Which would then be accessible to a template at `/themes/yourtheme/layouts/review/single.html` through `.Params.affiliatelink` and `.Params.recommendedby`, respectively. Two common situations where these could be introduced are as a value of a certain attribute (like `href=""` below) or by itself to be displayed. Sample syntaxes include:
These fields would then be accessible to the `/themes/yourtheme/layouts/review/single.html` template through `.Params.affiliatelink` and `.Params.recommendedby`, respectively.
Two common situations where this type of front matter field could be introduced is as a value of a certain attribute like `href=""` or by itself to be displayed as text to the website's visitors.
{{% input "/themes/yourtheme/layouts/review/single.html" %}}
```html
<h3><a href={{ printf "%s" $.Params.affiliatelink }}>Buy this book</a></h3>
<p>It was recommended by {{ .Params.recommendedby }}.</p>
```
{{% /input %}}
which would render
This template would render as follows, assuming you've set [`uglyURLs`](/content-management/url-management/) to `false` in your [site `config`](/getting-started/configuration/):
{{% output "yourbaseurl/review/book01/index.html" %}}
```html
<h3><a href="http://www.my-book-link.here">Buy this book</a></h3>
<p>It was recommended by my Mother.</p>
```
{{% /output %}}
{{% note %}}
See [Archetypes](/content-management/archetyps) for consistency of `Params` across pieces of content.
{{% /note %}}
### Param method
### The `.Param` Method
In Hugo, you can declare params both for the site and the individual page. A
common use case is to have a general value for the site and a more specific
value for some of the pages (i.e., a header image):
In Hugo, you can declare params in individual pages and globally for your entire website. A common use case is to have a general value for the site param and a more specific value for some of the pages (i.e., a header image):
```golang
{{ $.Param "header_image" }}
```
The `.Param` method provides a way to resolve a single value whether it's
in a page parameter or a site parameter.
The `.Param` method provides a way to resolve a single value according to it's definition in a page parameter (i.e. in the content's front matter) or a site parameter (i.e., in your `config`).
### Accessing Nested Fields in Front Matter
When front matter contains nested fields like the following:
@@ -129,8 +232,7 @@ author:
display_name: John Feminella
---
```
`.Param` can access them by concatenating the field names together with a
dot:
`.Param` can access these fields by concatenating the field names together with a dot:
```
{{ $.Param "author.display_name" }}
@@ -150,9 +252,5 @@ The top-level key will be preferred. Therefore, the following method, when appli
```golang
{{ $.Param "favorites.flavor" }}
=> vanilla
```
[content type]: /content-management/content-types/
[crossreferences]: /content-management/cross-references/
[hugovariables]: /variables-and-params/hugo-variables/
[sitevariables]: /variables-and-params/site-variables/
content/variables-and-params/shortcode-git-and-hugo-variables.md
+69 -10
View File
@@ -9,24 +9,83 @@ categories: [variables and params]
tags: [shortcodes,git]
draft: false
weight: 50
aliases: []
toc: false
aliases: [/extras/gitinfo/,/variables-and-params/other/]
toc: true
needsreview: true
notesforauthors:
---
## Shortcodes
## Shortcode Variables
[Shortcodes][shortcodes] have access to parameters delimited in the shortcode declaration via [`.Get`][getfunction], page- and site-level variables, and also the following shortcode-specific fields:
`.Parent`
: Provides access to the parent shortcode context in nested shortcodes. This can be very useful for inheritance of common shortcode parameters from the root.
`.IsNamedParams`
: Boolean that returns `true` when the shortcode in question uses [named rather than positional parameters][shortcodes]
`.Parent` (reference to nested shortcodes paragraph in /shortcodes/)
`.IsNamedParams` (reference to shortcodes)
`.Inner`
: Represents the content between the opening and closing shortcode tags when a [closing shortcode][markdownshortcode] is used
## Git Variables
Hugo provides a way to integrate Git data into your website.
{{% note "`.GitInfo` Performance Considerations" %}}
Hugo's Git integrations should be fairly performant but *can* increase your build time. This will depend on the size of your Git history.
{{% /note %}}
### `.GitInfo` Prerequisites
1. The Hugo site must be in a Git-enabled directory.
2. The Git executable must be installed and in your system `PATH`.
3. The `.GitInfo` feature must be enabled in your Hugo project by passing `--enableGitInfo` flag on the command line or by setting `enableGitInfo` to `true` in your [site's configuration file][configuration].
### The `.GitInfo` Object
The `GitInfo` object contains the following fields:
`.AbbreviatedHash`
: The abbreviated commit hash (e.g., `866cbcc`)
`.AuthorName`
: The author's name, respecting `.mailmap`
`.AuthorEmail`
: The author's email address, respecting `.mailmap`
`.AuthorDate`
: The author date
`.Hash`
: The commit hash (e.g., `866cbccdab588b9908887ffd3b4f2667e94090c3`)
`.Subject`
: commit message subject (e.g., `tpl: Add custom index function`)
## Hugo Variables
Also available is `.Hugo` which has the following:
The `.Hugo` variable provides easy access to Hugo-related data and contains the following fields:
**.Hugo.Generator** Meta tag for the version of Hugo that generated the site. Highly recommended to be included by default in all theme headers so we can start to track the usage and popularity of Hugo. Unlike other variables it outputs a **complete** HTML tag, e.g. `<meta name="generator" content="Hugo 0.15" />`<br>
**.Hugo.Version** The current version of the Hugo binary you are using e.g. `0.13-DEV`<br>
**.Hugo.CommitHash** The git commit hash of the current Hugo binary e.g. `0e8bed9ccffba0df554728b46c5bbf6d78ae5247`<br>
**.Hugo.BuildDate** The compile date of the current Hugo binary formatted with RFC 3339 e.g. `2002-10-02T10:00:00-05:00`<br>
`.Hugo.Generator`
: Meta tag for the version of Hugo that generated the site. `.Hugo.Generator` outputs a *complete* HTML tag; e.g. `<meta name="generator" content="Hugo 0.18" />`
`.Hugo.Version`
: The current version of the Hugo binary you are using e.g. `0.13-DEV`<br>
`.Hugo.CommitHash`
: The git commit hash of the current Hugo binary e.g. `0e8bed9ccffba0df554728b46c5bbf6d78ae5247`<br>
`.Hugo.BuildDate`
: The compile date of the current Hugo binary formatted with RFC 3339 e.g. `2002-10-02T10:00:00-05:00`<br>
{{% note "Use the Hugo Generator Tag" %}}
We highly recommend using `.Hugo.Generator` in your website. It is already included in all theme headers. The generator tag is significant in that it allows the Hugo team to track the usage and popularity of Hugo.
{{% /note %}}
[configuration]: /getting-started/configuration/
[getfunction]: /functions/get/
[markdownshortcode]: /content-management/shortcodes/#shortcodes-with-markdown
[shortcodes]: /templates/shortcode-templates/
content/variables-and-params/site-variables.md
+96 -30
View File
@@ -1,7 +1,7 @@
---
title: Site Variables
linktitle: Site Variables
description:
description: Many, but not all, site-wide variables are defined in your site's configuration. However, Hugo provides a number of built-in variables for convenient access to global values in your templates.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
@@ -10,40 +10,99 @@ tags: [global,site]
draft: false
weight: 10
aliases: []
toc: false
toc: true
notesforauthors:
---
Also available is `.Site` which has the following:
The following is a list of site-level variables (aka "global"). Many of these variables are defined in your site's [configuration file](/getting-started/config/), whereas others are built into Hugo's core for convenient usage in your templates.
* `.Site.AllPages` Array of all pages regardless of their translation.
* `.Site.Author` A map of the authors as defined in the site configuration.
* `.Site.BaseURL` The base URL for the site as defined in the site configuration file.
* `.Site.BuildDrafts` A boolean (Default: false) to indicate whether to build drafts. Defined in the site configuration.
* `.Site.Copyright` A string representing the copyright of your web site as defined in the site configuration.
* `.Site.Data` Custom data, see [Data Files](/extras/datafiles/).
* `.Site.DisqusShortname` A string representing the shortname of the Disqus shortcode as defined in the site configuration.
* `.Site.Files` All of the source files of the site.
* `.Site.GoogleAnalytics` A string representing your tracking code for Google Analytics as defined in the site configuration.
* `.Site.IsMultiLingual` Whether there are more than one language in this site. See [Multilingual](/content-management/multilingual-mode/) for more information.
* `.Site.Language.Lang` The language code of the current locale, e.g. `en`.
* `.Site.Language.LanguageName` The full language name, e.g. `English`.
* `.Site.Language.Weight` The weight that defines the order in the `.Site.Languages` list.
* `.Site.Language` This indicates which language you are currently rendering the website for. This is an object with the attributes set in your language definition in your site config.
* `.Site.LanguageCode` A string representing the language as defined in the site configuration. This is mostly used to populate the RSS feeds with the right language code.
* `.Site.LanguagePrefix` This can be used to prefix theURLs with whats needed to point to the correct language. It will even work when only one language defined. See also the functions [absLangURL](/functions/abslangurl/) and [relLangURL](/functions/rellangurl).
* `.Site.Languages` An ordered list (ordered by defined weight) of languages.
* `.Site.LastChange` A string representing the date/time of the most recent change to your site, based on the [`date` variable in the front matter](/content-management/front-matter) of your content pages.
* `.Site.Menus` All of the menus in the site.
* `.Site.Pages` Array of all content ordered by Date, newest first. Replaces the now-deprecated `.Site.Recent` starting v0.13. This array contains only the pages in the current language.
* `.Site.Permalinks` A string to override the default [permalink](/content-management/url-management/) format defined in the [site configuration](/getting-started/configuration/).
* `.Site.RegularPages` A shortcut to the *regular page* collection. Equivalent to `where .Site.Pages "Kind" "page"`.
* `.Site.RSSLink` The URL for the site RSS.
* `.Site.Sections` Top level directories of the site.
* `.Site.Taxonomies` The [taxonomies](/taxonomies/usage/) for the entire site. Replaces the now-obsolete `.Site.Indexes` since v0.11. Also see section [Taxonomies elsewhere](#taxonomies-elsewhere).
* `.Site.Title` A string representing the title of the site.
## Site Variables List
`.Site.Params` is a container holding the values from the `params` section of your site configuration file. For example, a TOML config file might look like this:
`.Site.AllPages`
: array of all pages, regardless of their translation.
`.Site.Author`
: a map of the authors as defined in the site configuration.
`.Site.BaseURL`
: the base URL for the site as defined in the site configuration.
`.Site.BuildDrafts`
: a boolean (default: `false`) to indicate whether to build drafts as defined in the site configuration.
`.Site.Copyright`
: a string representing the copyright of your website as defined in the site configuration.
`.Site.Data`
: custom data, see [Data Templates](/templates/date-templates/).
`.Site.DisqusShortname`
: a string representing the shortname of the Disqus shortcode as defined in the site configuration.
`.Site.Files`
: all source files for the Hugo website.
`.Site.GoogleAnalytics`
: a string representing your tracking code for Google Analytics as defined in the site configuration.
`.Site.IsMultiLingual`
: whether there are more than one language in this site. See [Multilingual](/content-management/multilingual-mode/) for more information.
`.Site.Language.Lang`
: the language code of the current locale (e.g., `en`).
`.Site.Language.LanguageName`
: the full language name (e.g. `English`).
`.Site.Language.Weight`
: the weight that defines the order in the `.Site.Languages` list.
`.Site.Language`
: indicates the language currently being used to render the website. This object's attributes are set in site configurations' language definition.
`.Site.LanguageCode`
: a string representing the language as defined in the site configuration. This is mostly used to populate the RSS feeds with the right language code.
`.Site.LanguagePrefix`
: this can be used to prefix URLs to point to the correct language. It will even work when only one defined language. See also the functions [absLangURL](/functions/abslangurl/) and [relLangURL](/functions/rellangurl).
`.Site.Languages`
: an ordered list (ordered by defined weight) of languages.
`.Site.LastChange`
: a string representing the date/time of the most recent change to your site. This string is based on the [`date` variable in the front matter](/content-management/front-matter) of your content pages.
`.Site.Menus`
: all of the menus in the site.
`.Site.Pages`
: array of all content ordered by Date with the newest first. `.Site.Pages` replaced the deprecated `.Site.Recent` as of Hugo v0.13. This array contains only the pages in the current language.
`.Site.Permalinks`
: a string to override the default [permalink](/content-management/url-management/) format as defined in the site configuration.
`.Site.RegularPages`
: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalents to `where .Site.Pages "Kind" "page"`.
`.Site.RSSLink`
: the URL for the site RSS.
`.Site.Sections`
: top-level directories of the site.
`.Site.Taxonomies`
: the [taxonomies](/taxonomies/usage/) for the entire site. Replaces the now-obsolete `.Site.Indexes` since v0.11. Also see section [Taxonomies elsewhere](#taxonomies-elsewhere).
`.Site.Title`
: a string representing the title of the site.
## The `.Site.Params` Variable
`.Site.Params` is a container holding the values from the `params` section of your site configuration.
### `.Site.Params` Example
The following `config.toml` defines a site-wide param for `description`:
```toml
baseURL = "http://yoursite.example.com/"
@@ -53,3 +112,10 @@ baseURL = "http://yoursite.example.com/"
author = "Nikola Tesla"
```
You can use `.Site.Params` in a [partial template](/templates/partial-templates/) to call the default site description:
{{% input "layouts/partials/head.html" %}}
```html
<meta name="description" content="{{if .IsHome}}{{ $.Site.Params.description }}{{else}}{{.Description}}{{end}}" />
```
{{% /input %}}
content/variables-and-params/taxonomy-variables.md
+33 -13
View File
@@ -10,28 +10,48 @@ tags: [taxonomies,terms]
draft: false
weight: 30
aliases: []
toc: false
toc: true
needsreview: true
notesforauthors:
---
### Taxonomy Terms Page Variables
[Taxonomy terms](/templates/taxonomy-templates/) pages are of the type `Page` and have the following additional variables. These are available in `layouts/_defaults/terms.html` for example.
[Taxonomy terms pages][taxonomytemplates] are of the type `Page` and have the following additional variables. For example, the following fields would be available in `layouts/_defaults/terms.html`, depending on how you organize your [taxonomy templates][taxonomytemplates]:
* `.Data.Singular` The singular name of the taxonomy<br>
* `.Data.Plural` The plural name of the taxonomy<br>
* `.Data.Pages` the list of pages in this taxonomy<br>
* `.Data.Terms` The taxonomy itself<br>
* `.Data.Terms.Alphabetical` The Terms alphabetized<br>
* `.Data.Terms.ByCount` The Terms ordered by popularity<br>
`.Data.Singular`
: The singular name of the taxonomy
The last two can also be reversed: `.Data.Terms.Alphabetical.Reverse`, `.Data.Terms.ByCount.Reverse`.
`.Data.Plural`
: The plural name of the taxonomy
### Taxonomies elsewhere
`.Data.Pages`
: The list of pages in the taxonomy
The `.Site.Taxonomies` variable holds all taxonomies defines site-wide. It is a map of the taxonomy name to a list of its values. For example: "tags" -> ["tag1", "tag2", "tag3"]. Each value, though, is not a string but rather a [Taxonomy variable](#the-taxonomy-variable).
`.Data.Terms`
: The taxonomy itself
#### The Taxonomy variable
`.Data.Terms.Alphabetical`
: The taxonomy terms alphabetized
The Taxonomy variable, available as `.Site.Taxonomies.tags` for example, contains the list of tags (values) and, for each of tag, their corresponding content pages.
`.Data.Terms.ByCount`
: The Terms ordered by popularity
Note that `.Data.Terms.Alphabetical` and `.Data.Terms.ByCount` can also be reversed:
* `.Data.Terms.Alphabetical.Reverse`
* `.Data.Terms.ByCount.Reverse`
### 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 Taxonomy Variable
The Taxonomy variable, available, for example, as `.Site.Taxonomies.tags`, contains the list of tags (values) and, for each of tag, their corresponding content pages.
### Example Usage of `.Site.Taxonomies`
**NEEDS EXAMPLE**
[taxonomytemplates]: /templates/taxonomy-templates/
questions-for-reviewers.md
+1
View File
@@ -0,0 +1 @@
*
static/css/style.min.css
Vendored
+1 -1
View File
File diff suppressed because one or more lines are too long
themes/hugodocs/layouts/_default/single.html
+3
View File
@@ -7,6 +7,9 @@
<h1 class="page-title {{.Section}}" id="{{with .LinkTitle}}{{. | urlize}}{{else}}{{ .Title | urlize }}{{end}}">{{with .LinkTitle}}{{.}}{{else}}{{ .Title | markdownify }}{{end}}</h1>
{{partial "content-header-links.html" . }}
{{partial "tags.html" . }}
{{if .Params.needsreview }}
<div id="beingreviewed">UNDERGOING REVIEW</div>
{{end}}
</header>
<div class="body-copy">
{{.Content}}
themes/hugodocs/layouts/partials/contents-list.html
+1 -1
View File
@@ -1,7 +1,7 @@
{{$kind := .Kind}}
{{if eq $kind "section"}}
{{$section := replace (humanize .Section | title) "And" "and"}}
<h2 id="contents" class="contents-list-heading">Contents:</h2>
<h2 id="contents" class="contents-list-heading section-heading">Contents:</h2>
{{end}}
{{range .Data.Pages}}
<a href="{{.Permalink}}">
themes/hugodocs/layouts/section/functions.html
+9
View File
@@ -0,0 +1,9 @@
{{define "main"}}
<main class="main showcase-list">
<header class="content-header">
{{partial "breadcrumb.html" . }}
<h1 class="page-title" id="{{ .Title | urlize }}">{{ .Title | markdownify }}</h1>
{{.Content}}
</header>
</main>
{{end}}
themes/hugodocs/pipeline/scss/_temp.scss
+14
View File
@@ -0,0 +1,14 @@
#beingreviewed {
background-color: $hugo-pink;
color:white;
position:absolute;
left:40px;
top:20px;
transform:rotate(-10deg);
font-weight:bold;
width:200px;
font-size:24px;
padding:6px;
z-index:9999;
overflow:visible;
}
themes/hugodocs/pipeline/scss/components/_admonitions.scss
+1 -1
View File
@@ -37,7 +37,7 @@
z-index: 20;
code,
pre {
color: lighten($base-font-color, 20%);
color: inherit;
}
em,strong {
color:inherit;
themes/hugodocs/pipeline/scss/components/_anchors.scss
+2 -2
View File
@@ -81,10 +81,10 @@ a.tooltip {
a.heading-link {
color: lighten($base-font-color, 50%);
font-size: .8em;
font-size: .7em;
position: absolute;
display: inline;
top: .3em;
top: .4em;
right:0px;
&:before,
&:after {
themes/hugodocs/pipeline/scss/components/_code.scss
+26 -12
View File
@@ -13,7 +13,7 @@ pre {
margin: .5em 0px 32px 0px;
overflow: auto;
& > code {
color:$hugo-white;
color: $hugo-white;
}
}
@@ -37,7 +37,6 @@ pre {
font-family: $code-font-family;
padding-left: .25em;
padding-right: .25em;
// padding-bottom: .1em;
text-transform: none;
line-height: 1.2;
margin-bottom: .15em;
@@ -55,14 +54,28 @@ pre {
}
}
}
//for definitions lists
dd,
dt {
code {
//darken code background color for non-retina displays
background-color: darken($inline-code-background-color, 5%);
color: $inline-code-text-color;
font-family: $code-font-family;
@include MQ(retina) {
//lighten code background color for retina displays
background-color: $inline-code-background-color;
}
}
}
p > a code,
li > a code,
td > a code {
color: $hugo-pink;
}
> pre {
padding-bottom:20px;
padding-top:20px;
padding-bottom: 20px;
padding-top: 20px;
background-color: $code-block-background-color;
font-family: $code-font-family;
color: $code-block-base-font-color;
@@ -164,9 +177,9 @@ div.code-copy-header {
background-color: $code-editor-header-base-bg-color;
border-radius: 0px;
position: relative;
display:flex;
justify-content:space-between;
align-items:center;
display: flex;
justify-content: space-between;
align-items: center;
&.output {
background-color: $output-example-color;
}
@@ -181,22 +194,23 @@ div.code-copy-header {
font-family: $systemfonts;
i.icon-website {
color: inherit;
font-weight:bold;
font-size:18px;
font-weight: bold;
font-size: 18px;
}
}
[class^="icon-"] {
color: $code-filename-color;
}
//corrects odd placement of terminal icon
i.icon-sh.input,i.icon-bash.input {
padding-right:.5em;
i.icon-sh.input,
i.icon-bash.input {
padding-right: .5em;
}
}
.action-buttons {
// position: absolute;
position:relative;
position: relative;
left: 10px;
width: 12px;
height: 12px;
themes/hugodocs/pipeline/scss/components/_contents-list.scss
+1
View File
@@ -5,6 +5,7 @@
border-bottom: 1px solid $hugo-gray-light;
margin-bottom: 1em;
position: relative;
font-size:.95em;
a {
width: 100%;
color: $base-font-color;
themes/hugodocs/pipeline/scss/components/_lists.scss
+45 -5
View File
@@ -8,7 +8,7 @@ aside {
list-style: none;
text-indent: 0px;
li {
position:relative;
position: relative;
margin-left: 0px;
padding-left: 0px;
list-style: none;
@@ -26,10 +26,11 @@ aside {
padding-top: 0px;
margin-bottom: 1.5em;
li {
position:relative;
margin-top:.25em;
ul,ol {
margin-bottom:0px;
position: relative;
margin-top: .25em;
ul,
ol {
margin-bottom: 0px;
}
}
}
@@ -59,3 +60,42 @@ aside {
}
}
}
//definition lists
.body-copy {
dl {
margin: 0px;
border-bottom: 1px solid #ccc;
border-top: 1px solid #ccc;
display: block;
margin-bottom: 1em;
font-size: 1em;
clear: both;
line-height:1.6;
padding: {
top: .5em;
bottom: .5em;
}
dt {
float: left;
display: block;
width: 100%;
clear: both;
margin: 0px;
font-weight: bolder;
margin-right: 1em;
}
dd {
margin: .5em 0em 0em 0em;
text-indent: 0px;
height: auto;
font-size:.9em;
padding: {
top: .25em;
bottom: 0em;
left: 1.5em;
right: 0em;
}
}
}
}
themes/hugodocs/pipeline/scss/style.scss
+3 -1
View File
@@ -41,4 +41,6 @@
@import 'layout/site-footer';
//styles for individual pages
@import 'pages/homepage';
@import 'pages/homepage';
@import 'temp';