b563142fc0
* 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.
139 lines
5.2 KiB
Markdown
139 lines
5.2 KiB
Markdown
+++
|
|
title = "Overview"
|
|
weight = 10
|
|
+++
|
|
|
|
Gutenberg uses the [Tera](https://tera.netlify.com) template engine and is very similar
|
|
to Jinja2, Liquid or Twig.
|
|
|
|
As this documentation will only talk about how templates work in Gutenberg, please read
|
|
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. 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:
|
|
|
|
- `config`: the [configuration](./documentation/getting-started/configuration.md) without any modifications
|
|
- `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.
|
|
|
|
### markdown
|
|
Converts the given variable to HTML using Markdown. This doesn't apply any of the
|
|
features that Gutenberg adds to Markdown: internal links, shortcodes etc won't work.
|
|
|
|
By default, the filter will wrap all text into a paragraph. To disable that, you can
|
|
pass `true` to the inline argument:
|
|
|
|
```jinja2
|
|
{{ some_text | markdown(inline=true) }}
|
|
```
|
|
|
|
### base64_encode
|
|
Encode the variable to base64.
|
|
|
|
### base64_decode
|
|
Decode the variable from base64.
|
|
|
|
|
|
## Built-in global functions
|
|
Gutenberg adds a few global functions to Tera in order to make it easier to develop complex sites.
|
|
|
|
### `get_page`
|
|
Takes a path to a `.md` file and returns the associated page
|
|
|
|
```jinja2
|
|
{% set page = get_page(path="blog/page2.md") %}
|
|
```
|
|
|
|
### `get_section`
|
|
Takes a path to a `_index.md` file and returns the associated section
|
|
|
|
```jinja2
|
|
{% set section = get_section(path="blog/_index.md") %}
|
|
```
|
|
|
|
### ` get_url`
|
|
Gets the permalink for the given path.
|
|
If the path starts with `./`, it will be understood as an internal
|
|
link like the ones used in markdown.
|
|
|
|
```jinja2
|
|
{% set url = get_url(path="./blog/_index.md") %}
|
|
```
|
|
|
|
This can also be used to get the permalinks for static assets for example if
|
|
we want to link to the file that is located at `static/css/app.css`:
|
|
|
|
```jinja2
|
|
{{ get_url(path="css/app.css") }}
|
|
```
|
|
|
|
For assets it is reccommended that you pass `trailing_slash=false` to the `get_url` function. This prevents errors
|
|
when dealing with certain hosting providers. An example is:
|
|
|
|
```jinja2
|
|
{{ get_url(path="css/app.css", trailing_slash=false) }}
|
|
```
|
|
|
|
In the case of non-internal links, you can also add a cachebust of the format `?t=1290192` at the end of a URL
|
|
by passing `cachebust=true` to the `get_url` function.
|
|
|
|
|
|
### `get_taxonomy_url`
|
|
Gets the permalink for the tag or category given.
|
|
|
|
```jinja2
|
|
{% set url = get_taxonomy_url(kind="category", name=page.category) %}
|
|
```
|
|
|
|
The `name` will almost come from a variable but in case you want to do it manually,
|
|
the value should be the same as the one in the front-matter, not the slugified version.
|
|
|
|
### `trans`
|
|
Gets the translation of the given `key`, for the `default_language` or the `language given
|
|
|
|
```jinja2
|
|
{{ trans(key="title") }}
|
|
{{ trans(key="title", lang="fr") }}
|
|
```
|