From b563142fc05570c5951ad600bf0c743a7ac2ca3f Mon Sep 17 00:00:00 2001 From: Daniel Sockwell Date: Mon, 16 Jul 2018 02:49:26 -0400 Subject: [PATCH] Add `index page` section to documentation (#331) * Add `index page` section to documentation The current documentation does not describe how to create a index page. I initially found this confusing, because I expected an index page to be a **page** rather than a section. Thus, I tried to access the page content with `{{ page.content }}` and was very frustrated when I could not. This addition clarifies that the index page is **always** a section, even if it does not have any sub-pages. This should also help people who intend to use Gutenberg to build stand-alone webpages, rather than blogs. --- .../documentation/templates/overview.md | 41 ++++++++++++++++--- 1 file changed, 36 insertions(+), 5 deletions(-) diff --git a/docs/content/documentation/templates/overview.md b/docs/content/documentation/templates/overview.md index 1d67e94..01810e6 100644 --- a/docs/content/documentation/templates/overview.md +++ b/docs/content/documentation/templates/overview.md @@ -10,11 +10,7 @@ As this documentation will only talk about how templates work in Gutenberg, plea the [Tera template documentation](https://tera.netlify.com/docs/templates/) if you want to learn more about it first. -All templates live in the `templates` directory and built-in or themes templates can -be overriden by creating a template with same name in the correct path. For example, -you can override the RSS template by creating a `templates/rss.xml` file. - -If you are not sure what variables are available in a template, you can just stick `{{ __tera_context }}` in it +All templates live in the `templates` directory. If you are not sure what variables are available in a template, you can just stick `{{ __tera_context }}` in it to print the whole context. A few variables are available on all templates minus RSS and sitemap: @@ -23,6 +19,41 @@ A few variables are available on all templates minus RSS and sitemap: - `current_path`: the path (full URL without the `base_url`) of the current page, never starting with a `/` - `current_url`: the full URL for that page +## Standard Templates +By default, Gutenberg will look for three templates: `index.html`, which is applied +to the site homepage; `section.html`, which is applied to all sections (any HTML +page generated by creating a directory within your `content` directory); and +`page.html`, which is applied to all pages (any HTML page generated by creating a +`.md` file within your `content` directory). + +The homepage is always a section (regardless of whether it contains other pages). +Thus, the `index.html` and `section.html` templates both have access to the +section variables. The `page.html` template has access to the page variables. +The page and section variables are described in more detail in the next section of this documentation. + +## Built-in Templates +Gutenberg comes with three built-in templates: `rss.xml`, `sitemap.xml`, and +`robots.txt` (each described in their own section of this documentation). +Additionally, themes can add their own templates, which will be applied if not +overridden. You can override built-in or theme templates by creating a template with +same name in the correct path. For example, you can override the RSS template by +creating a `templates/rss.xml` file. + +## Custom Templates +In addition to the standard `index.html`, `section.html`, and `page.html` templates, +you may also create custom templates by creating a `.html` file in the `templates` +directory. These custom templates will not be used by default. Instead, the custom template will _only_ be used if you apply it by setting the `template` front-matter variable to the path for that template (or if you `include` it in another template that is applied). For example, if you created a custom template for your site's About page called `about.html`, you could apply it to your `about.md` page by including the following front matter in your `about.md` page: + +```md ++++ +title = "About Us" +template = "about.html" ++++ +``` + +Custom templates are not required to live at the root of your `templates` directory. +For example, `product_pages/with_pictures.html` is a valid template. + ## Built-in filters Gutenberg adds a few filters, in addition of the ones already present in Tera.