From e29f6fe527d6b40b1f1aff0e1628fadc9d1a3704 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Mon, 21 Nov 2016 13:02:02 +0100 Subject: [PATCH] docs: Add sections on node now being a page Updates #2297 --- docs/content/content/sections.md | 2 ++ docs/content/overview/source-directory.md | 29 +++++++++++++++++++++++ docs/content/taxonomies/usage.md | 9 +++++-- docs/content/templates/functions.md | 14 +++++++++++ docs/content/templates/homepage.md | 2 ++ docs/content/templates/list.md | 3 +++ docs/content/templates/terms.md | 2 ++ 7 files changed, 59 insertions(+), 2 deletions(-) diff --git a/docs/content/content/sections.md b/docs/content/content/sections.md index 340e2298b..c603c0872 100644 --- a/docs/content/content/sections.md +++ b/docs/content/content/sections.md @@ -36,6 +36,8 @@ Hugo will automatically create pages for each section root that list all of the content in that section. See [List Templates](/templates/list/) for details on customizing the way they appear. +Section pages can also have a content file and frontmatter, see [Source Organization]({{< relref "overview/source-directory.md#content-for-home-page-and-other-list-pages" >}}). + ## Sections and Types By default everything created within a section will use the content type diff --git a/docs/content/overview/source-directory.md b/docs/content/overview/source-directory.md index e6a586f3b..5eef7c23c 100644 --- a/docs/content/overview/source-directory.md +++ b/docs/content/overview/source-directory.md @@ -95,3 +95,32 @@ This directory structure tells us a lot about this site: 1. The website intends to have two different types of content: *posts* and *quotes*. 2. It will also apply two different taxonomies to that content: *categories* and *tags*. 3. It will be displaying content in 3 different views: a list, a summary and a full page view. + +## Content for home page and other list pages + +Since Hugo 0.18, "everything" is a `Page` that can have content and metadata, like `.Params`, attached to it -- and share the same set of [page variables](/templates/variables/). + +To add content and frontmatter to the home page, a section, a taxonomy or a taxonomy terms listing, add a markdown file with the base name `_index` on the relevant place on the file system. + +For the default Markdown content, the filename will be `_index.html`. + +Se the example directory tree below. + +**Note that you don't have to create `_index` file for every section, taxonomy and similar, a default page will be created if not present, but with no content an default values for `.Title` etc.** + +```bash +└── content + ├── _index.md + ├── categories + │   ├── _index.md + │   └── photo + │   └── _index.md + ├── post + │   ├── _index.md + │   └── firstpost.md + └── tags + ├── _index.md + └── hugo + └── _index.md +``` + diff --git a/docs/content/taxonomies/usage.md b/docs/content/taxonomies/usage.md index b206f9c74..dae4541a7 100644 --- a/docs/content/taxonomies/usage.md +++ b/docs/content/taxonomies/usage.md @@ -2,6 +2,7 @@ lastmod: 2015-12-23 date: 2014-05-26 linktitle: Usage +toc: true menu: main: parent: taxonomy @@ -68,7 +69,7 @@ but will still titleize the values for titles and normalize them in URLs. Note that if you use `preserveTaxonomyNames` and intend to manually construct URLs to the archive pages, you will need to pass the taxonomy values through the `urlize` template function. -### Front Matter Example (in TOML) +## Front Matter Example (in TOML) ```toml +++ @@ -81,7 +82,7 @@ project_url = "https://github.com/spf13/hugo" +++ ``` -### Front Matter Example (in JSON) +## Front Matter Example (in JSON) ```json { @@ -102,3 +103,7 @@ project_url = "https://github.com/spf13/hugo" "project_url": "https://github.com/spf13/hugo" } ``` + +## Add content file with frontmatter + +See [Source Organization]({{< relref "overview/source-directory.md#content-for-home-page-and-other-list-pages" >}}). diff --git a/docs/content/templates/functions.md b/docs/content/templates/functions.md index bd48bb470..f51fa5a81 100644 --- a/docs/content/templates/functions.md +++ b/docs/content/templates/functions.md @@ -989,3 +989,17 @@ responses of APIs. {{ $resp.content | base64Decode | markdownify }} The response of the GitHub API contains the base64-encoded version of the [README.md](https://github.com/spf13/hugo/blob/master/README.md) in the Hugo repository. Now we can decode it and parse the Markdown. The final output will look similar to the rendered version on GitHub. + + +## .Site.GetPage +Every `Page` as a `Kind` attribute that shows what kind of page it is. While this attribute can be used to list pages of a certain `kind` using `where`, often it can be useful to fetch a single page by its path. + +GetPage looks up an index page of a given `Kind` and `path`. This method may support regular pages in the future, but currently it is a convenient way of getting the index pages such as the home page or a section from a template: + +``` + {{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }} + ``` + +This method wil return `nil` when no page could be found, so the above will not print anything if the blog section isn't found. + +The valid page kinds are: *home, section, taxonomy and taxonomyTerm.* diff --git a/docs/content/templates/homepage.md b/docs/content/templates/homepage.md index 9188b868b..c5cebd219 100644 --- a/docs/content/templates/homepage.md +++ b/docs/content/templates/homepage.md @@ -28,6 +28,8 @@ 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]({{< relref "overview/source-directory.md#content-for-home-page-and-other-list-pages" >}}). + ## Which Template will be rendered? Hugo uses a set of rules to figure out which template to use when rendering a specific page. diff --git a/docs/content/templates/list.md b/docs/content/templates/list.md index cdff19db9..36ababff6 100644 --- a/docs/content/templates/list.md +++ b/docs/content/templates/list.md @@ -46,6 +46,7 @@ A Section will be rendered at /`SECTION`/ (e.g. http://spf13.com/project/) * /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]({{< relref "overview/source-directory.md#content-for-home-page-and-other-list-pages" >}}). ### Taxonomy Lists @@ -58,6 +59,8 @@ A Taxonomy will be rendered at /`PLURAL`/`TERM`/ (e.g. http://spf13.com/top * /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]({{< relref "overview/source-directory.md#content-for-home-page-and-other-list-pages" >}}). + ### Section RSS A Section’s RSS will be rendered at /`SECTION`/index.xml (e.g. http://spf13.com/project/index.xml) diff --git a/docs/content/templates/terms.md b/docs/content/templates/terms.md index 3eafcc324..378bd4df8 100644 --- a/docs/content/templates/terms.md +++ b/docs/content/templates/terms.md @@ -20,6 +20,8 @@ A unique template is needed to create a list of the terms for a given taxonomy. This is different from the [list template](/templates/list/) as that template is a list of content, whereas this is a list of meta data. +Note that a taxonomy terms page can also have a content file with frontmatter, see [Source Organization]({{< relref "overview/source-directory.md#content-for-home-page-and-other-list-pages" >}}). + ## Which Template will be rendered? Hugo uses a set of rules to figure out which template to use when rendering a specific page.