diff --git a/content/templates/homepage.md b/content/templates/homepage.md index 13fdc07e9..c5be543d9 100644 --- a/content/templates/homepage.md +++ b/content/templates/homepage.md @@ -49,7 +49,7 @@ In addition to the standard [page variables][pagevars], the homepage template ha ## Example Homepage Template -The following is an example of a homepage template that uses [partial][partials], [block][] templates, and a content file at `content/_index.md` to populate the `{{.Title}}` and `{{Content}}` [page variables][pagevars]. +The following is an example of a homepage template that uses [partial][partials], [base][] templates, and a content file at `content/_index.md` to populate the `{{.Title}}` and `{{Content}}` [page variables][pagevars]. {{% code file="layouts/index.html" download="index.html" %}} ```html @@ -76,7 +76,7 @@ The following is an example of a homepage template that uses [partial][partials] ``` {{% /code %}} -[block]: /templates/base/ +[base]: /templates/base/ [contentorg]: /content-management/organization/ [lists]: /templates/lists/ [lookup]: /templates/lookup-order/ diff --git a/content/templates/lists.md b/content/templates/lists.md index 020a1e26d..60f667c3d 100644 --- a/content/templates/lists.md +++ b/content/templates/lists.md @@ -51,17 +51,21 @@ Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][taxte ## Adding Content and Front Matter to List Pages -Since v0.18, [everything in Hugo is a `Page`][bepsays]. This means list pages and the homepage can have associated content files---i.e. `_index.md`---that contain page metadata (i.e., front matter) and content. +Since v0.18, [everything in Hugo is a `Page`][bepsays]. This means list pages and the homepage can have associated content files (i.e. `_index.md`) that contain page metadata (i.e., front matter) and content. This new model allows you to include list-specific front matter via `.Params` and also means that list templates (e.g., `layouts/_default/list.html`) have access to all [page variables][pagevars]. +{{% note %}} +It is important to note that all `_index.md` content files will render according to a *list* template and not according to a [single page template](/templates/single-page-templates/). +{{% /note %}} + ### Example Project Directory -The following is an example of a typical Hugo project directory: +The following is an example of a typical Hugo project directory's content: ```bash . -├── config.toml +... ├── content | ├── post | | ├── _index.md @@ -70,6 +74,7 @@ The following is an example of a typical Hugo project directory: | └── quote | | ├── quote-01.md | | └── quote-02.md +... ``` Using the above example, let's assume you have the following in `content/post/_index.md`: diff --git a/content/templates/lookup-order.md b/content/templates/lookup-order.md index dc25809bb..bc4ff80bc 100644 --- a/content/templates/lookup-order.md +++ b/content/templates/lookup-order.md @@ -162,6 +162,11 @@ Here is the way Hugo traverses the single-page lookup order for `my-first-event. 9. `/themes//layouts/events/single.html` 10. `/themes//layouts/_default/single.html` + +{{% note %}} +`my-first-event.md` is significant because it demonstrates the role of the lookup order in Hugo themes. Both the root project directory *and* the `mytheme` themes directory have a file at `_default/single.html`. Understanding this order allows you to [customize Hugo themes](/themes/customizing/) by creating template files with identical names in your project directory that step in front of theme template files in the lookup. This allows you to customize the look and feel of your website while maintaining compatibility with the theme's upstream. +{{% /note %}} + ## Lookup Orders The respective lookup order for each of Hugo's templates has been defined throughout the Hugo docs: diff --git a/content/templates/section-templates.md b/content/templates/section-templates.md index 1c59b5734..ce920714c 100644 --- a/content/templates/section-templates.md +++ b/content/templates/section-templates.md @@ -20,11 +20,10 @@ toc: true Templates used for section pages are *lists* and therefore have all the variables and methods available to [list pages][lists]. -## Adding Content to Section Templates +## Adding Content and Front Matter to Section Templates To effectively leverage section page templates, you should first understand Hugo's [content organization](/content-management/organization/) and, specifically, the purpose of `_index.md` for adding content and front matter to section and other list pages. - ## Section Template Lookup Order The [lookup order][lookup] for section templates is as follows: diff --git a/content/templates/single-page-templates.md b/content/templates/single-page-templates.md index 123132cc6..3488fecdf 100644 --- a/content/templates/single-page-templates.md +++ b/content/templates/single-page-templates.md @@ -22,7 +22,7 @@ The primary view of content in Hugo is the single view. Hugo's default behavior ## Single Page Template Lookup Order -You can specify `type` (i.e., [content type][]) and `layout` in a single content file's [front matter][]. However, you cannot specify `section` because this is determined based on file location (see [content section][section]). +You can specify a [content's `type`][content type] and `layout` in a single content file's [front matter][]. However, you cannot specify `section` because this is determined based on file location (see [content section][section]). Hugo assumes your content section and content type are the same unless you tell Hugo otherwise by providing a `type` directly in the front matter of a content file. This is why #1 and #3 come before #2 and #4, respectively, in the following lookup order. Values in angle brackets (`<>`) are variable. @@ -37,10 +37,6 @@ Hugo assumes your content section and content type are the same unless you tell 9. `/themes//layouts/
/single.html` 10. `/themes//layouts/_default/single.html` -{{% note %}} -`my-first-event.md` is significant because it demonstrates the role of the lookup order in Hugo themes. Both the root project directory *and* the `mytheme` themes directory have a file at `_default/single.html`. Understanding this order allows you to [customize Hugo themes](/themes/customizing/) by creating template files with identical names in your project directory that step in front of theme template files in the lookup. This allows you to customize the look and feel of your website while maintaining compatibility with the theme's upstream. -{{% /note %}} - ## Example Single Page Templates Content pages are of the type `page` and will therefore have all the [page variables][pagevars] and [site variables][] available to use in their templates.