11 files changed, 756 insertions, 0 deletions
diff --git a/content/templates/404.md b/content/templates/404.md
new file mode 100644
index 0000000..eb0a558
--- /dev/null
+++ b/content/templates/404.md
@@ -0,0 +1,7 @@
++++
+title = "404 error page"
+weight = 80
++++
+
+Zola will look for a `404.html` file in the `templates` directory or
+use the built-in one. The default template is very basic and gets `config` in its context.
diff --git a/content/templates/_index.md b/content/templates/_index.md
new file mode 100644
index 0000000..3c56b87
--- /dev/null
+++ b/content/templates/_index.md
@@ -0,0 +1,5 @@
++++
+title = "Templates"
+weight = 3
+sort_by = "weight"
++++
diff --git a/content/templates/archive.md b/content/templates/archive.md
new file mode 100644
index 0000000..467d12c
--- /dev/null
+++ b/content/templates/archive.md
@@ -0,0 +1,23 @@
++++
+title = "Archive"
+weight = 90
++++
+
+Zola doesn't have a built-in way to display an archive page (a page showing
+all post titles ordered by year). However, this can be accomplished directly in the templates:
+
+```jinja2
+{% for year, posts in section.pages | group_by(attribute="year") %}
+    <h2>{{ year }}</h2>
+
+    <ul>
+    {% for post in posts %}
+        <li><a href="{{ post.permalink }}">{{ post.title }}</a></li>
+    {% endfor %}
+    </ul>
+{% endfor %}
+```
+
+This snippet assumes that posts are sorted by date and that you want to display the archive
+in descending order. If you want to show articles in ascending order, add a `reverse` filter
+after `group_by`.
diff --git a/content/templates/feeds/index.md b/content/templates/feeds/index.md
new file mode 100644
index 0000000..9ac72e2
--- /dev/null
+++ b/content/templates/feeds/index.md
@@ -0,0 +1,64 @@
++++
+title = "Feeds"
+weight = 50
+aliases = ["/documentation/templates/rss/"]
++++
+
+If the site `config.toml` file sets `generate_feed = true`, then Zola will
+generate a feed file for the site, named according to the `feed_filename`
+setting in `config.toml`, which defaults to `atom.xml`. Given the feed filename
+`atom.xml`, the generated file will live at `base_url/atom.xml`, based upon the
+`atom.xml` file in the `templates` directory, or the built-in Atom template.
+
+`feed_filename` can be set to any value, but built-in templates are provided
+for `atom.xml` (in the preferred Atom 1.0 format), and `rss.xml` (in the RSS
+2.0 format). If you choose a different filename (e.g. `feed.xml`), you will
+need to provide a template yourself.
+
+**Only pages with a date will be available.**
+
+The feed template gets five variables:
+
+- `config`: the site config
+- `feed_url`: the full url to that specific feed
+- `last_updated`: the most recent `updated` or `date` field of any post
+- `pages`: see [page variables](@/templates/pages-sections.md#page-variables)
+  for a detailed description of what this contains
+- `lang`: the language code that applies to all of the pages in the feed,
+  if the site is multilingual, or `config.default_language` if it is not
+
+Feeds for taxonomy terms get two more variables, using types from the
+[taxonomies templates](@/templates/taxonomies.md):
+
+- `taxonomy`: of type `TaxonomyConfig`
+- `term`: of type `TaxonomyTerm`, but without `term.pages` (use `pages` instead)
+
+You can also enable separate feeds for each section by setting the
+`generate_feed` variable to true in the respective section's front matter.
+Section feeds will use the same template as indicated in the `config.toml` file.
+Section feeds, in addition to the five feed template variables, get the
+`section` variable from the [section template](@/templates/pages-sections.md).
+
+Enable feed autodiscovery allows feed readers and browsers to notify user about a RSS or Atom feed available on your web site. So it is easier for user to subscribe.
+As an example this is how it looks like using [Firefox](https://en.wikipedia.org/wiki/Mozilla_Firefox) [Livemarks](https://addons.mozilla.org/en-US/firefox/addon/livemarks/?src=search) addon.
+
+![RSS feed autodiscovery example.](rss_feed.png)
+
+You can enable posts autodiscovery modifying your blog `base.html` template adding the following code in between the `<head>` tags.
+```html
+{% block rss %}
+  <link rel="alternate" type="application/rss+xml" title="RSS" href="{{/* get_url(path="rss.xml", trailing_slash=false) */}}">
+{% endblock %}
+```
+You can as well use an Atom feed using `type="application/atom+xml"` and `path="atom.xml"`.
+
+All pages on your site will refer to your post feed.
+
+In order to enable the tag feeds as well, you can overload the `block rss` using the following code in your `tags/single.html` template.
+```html
+{% block rss %}
+  {% set rss_path = "tags/" ~ term.name ~ "/rss.xml" %}
+  <link rel="alternate" type="application/rss+xml" title="RSS" href="{{/* get_url(path=rss_path, trailing_slash=false) */}}">
+{% endblock rss %}
+```
+Each tag page will refer to it's dedicated feed.
diff --git a/content/templates/feeds/rss_feed.png b/content/templates/feeds/rss_feed.png
new file mode 100644
index 0000000..81abb70
--- /dev/null
+++ b/content/templates/feeds/rss_feed.png
diff --git a/content/templates/overview.md b/content/templates/overview.md
new file mode 100644
index 0000000..7f19005
--- /dev/null
+++ b/content/templates/overview.md
@@ -0,0 +1,343 @@
++++
+title = "Overview"
+weight = 10
++++
+
+Zola uses the [Tera](https://tera.netlify.com) template engine, which is very similar
+to Jinja2, Liquid and Twig.
+
+As this documentation will only talk about how templates work in Zola, 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 place `{{ __tera_context }}` in the template to print the whole context.
+
+A few variables are available on all templates except feeds and the sitemap:
+
+- `config`: the [configuration](@/getting-started/configuration.md) without any modifications
+- `current_path`: the path (full URL without `base_url`) of the current page, always starting with a `/`
+- `current_url`: the full URL for the current page
+- `lang`: the language for the current page
+
+Config variables can be accessed like `config.variable`, in HTML for example with `{{ config.base_url }}`.
+The 404 template does not get `current_path` and `current_url` (this information cannot be determined).
+
+## Standard templates
+By default, Zola 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 an
+`.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.
+
+## Built-in templates
+Zola comes with four built-in templates: `atom.xml` and `rss.xml` (described in
+[Feeds](@/templates/feeds/index.md)), `sitemap.xml` (described in [Sitemap](@/templates/sitemap.md)),
+and `robots.txt` (described in [Robots.txt](@/templates/robots.md)).
+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
+the same name in the correct path. For example, you can override the Atom template by
+creating a `templates/atom.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 an `.html` file in the `templates`
+directory.  These custom templates will not be used by default.  Instead, a 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
+Zola adds a few filters in addition to [those](https://tera.netlify.com/docs/#filters) already present
+in Tera.
+
+### markdown
+Converts the given variable to HTML using Markdown. This doesn't apply any of the
+features that Zola adds to Markdown; for example, internal links and shortcodes won't work.
+
+By default, the filter will wrap all text in a paragraph. To disable this behaviour, you can
+pass `true` to the inline argument:
+
+```jinja2
+{{ some_text | markdown(inline=true) }}
+```
+
+You do not need to use this filter with `page.content` or `section.content`, the content is already rendered.
+
+### base64_encode
+Encode the variable to base64.
+
+### base64_decode
+Decode the variable from base64.
+
+
+## Built-in global functions
+
+Zola adds a few global functions to [those in Tera](https://tera.netlify.com/docs#built-in-functions)
+to make it easier to develop complex sites.
+
+
+### `get_page`
+Takes a path to an `.md` file and returns the associated page.
+
+```jinja2
+{% set page = get_page(path="blog/page2.md") %}
+```
+
+### `get_section`
+Takes a path to an `_index.md` file and returns the associated section.
+
+```jinja2
+{% set section = get_section(path="blog/_index.md") %}
+```
+
+If you only need the metadata of the section, you can pass `metadata_only=true` to the function:
+
+```jinja2
+{% set section = get_section(path="blog/_index.md", metadata_only=true) %}
+```
+
+### `get_url`
+Gets the permalink for the given path.
+If the path starts with `@/`, it will be treated as an internal
+link like the ones used in Markdown, starting from the root `content` directory.
+
+```jinja2
+{% set url = get_url(path="@/blog/_index.md") %}
+```
+
+It accepts an optional parameter `lang` in order to compute a *language-aware URL* in multilingual websites. Assuming `config.base_url` is `"http://example.com"`, the following snippet will:
+
+- return `"http://example.com/blog/"` if `config.default_language` is `"en"`
+- return `"http://example.com/en/blog/"` if `config.default_language` is **not** `"en"` and `"en"` appears in `config.languages`
+- fail otherwise, with the error message `"'en' is not an authorized language (check config.languages)."`
+
+```jinja2
+{% set url = get_url(path="@/blog/_index.md", lang="en") %}
+```
+
+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") */}}
+```
+
+By default, assets will not have a trailing slash. You can force one by passing `trailing_slash=true` to the `get_url` function.
+An example is:
+
+```jinja2
+{{/* get_url(path="css/app.css", trailing_slash=true) */}}
+```
+
+In the case of non-internal links, you can also add a cachebust of the format `?h=<sha256>` at the end of a URL
+by passing `cachebust=true` to the `get_url` function.
+
+
+### `get_file_hash`
+
+Gets the hash digest for a static file. Supported hashes are SHA-256, SHA-384 (default) and SHA-512. Requires `path`. The `sha_type` key is optional and must be one of 256, 384 or 512.
+
+```jinja2
+{{/* get_file_hash(path="js/app.js", sha_type=256) */}}
+```
+
+This can be used to implement subresource integrity. Do note that subresource integrity is typically used when using external scripts, which `get_file_hash` does not support.
+
+```jinja2
+<script src="{{/* get_url(path="js/app.js") */}}"
+        integrity="sha384-{{/* get_file_hash(path="js/app.js", sha_type=384) */}}"></script>
+```
+
+Whenever hashing files, whether using `get_file_hash` or `get_url(..., cachebust=true)`, the file is searched for in three places: `static/`, `content/` and the output path (so e.g. compiled SASS can be hashed, too.)
+
+
+### `get_image_metadata`
+Gets metadata for an image. This supports common formats like JPEG, PNG, as well as SVG.
+Currently, the only supported keys are `width` and `height`.
+
+```jinja2
+  {% set meta = get_image_metadata(path="...") %}
+  Our image is {{ meta.width }}x{{ meta.height }}
+```
+
+### `get_taxonomy_url`
+Gets the permalink for the taxonomy item found.
+
+```jinja2
+{% set url = get_taxonomy_url(kind="categories", name=page.taxonomies.category, lang=page.lang) %}
+```
+
+`name` will almost always 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.
+
+`lang` (optional) default to `config.default_language` in config.toml
+
+### `get_taxonomy`
+Gets the whole taxonomy of a specific kind.
+
+```jinja2
+{% set categories = get_taxonomy(kind="categories") %}
+```
+
+The type of the output is:
+
+```ts
+kind: TaxonomyConfig;
+items: Array<TaxonomyTerm>;
+```
+
+See the [Taxonomies documentation](@/templates/taxonomies.md) for a full documentation of those types.
+
+### `load_data`
+Loads data from a file or URL. Supported file types include *toml*, *json*, *csv* and *bibtex*.
+Any other file type will be loaded as plain text.
+
+The `path` argument specifies the path to the data file relative to your base directory, where your `config.toml` is.
+As a security precaution, if this file is outside the main site directory, your site will fail to build.
+
+```jinja2
+{% set data = load_data(path="content/blog/story/data.toml") %}
+```
+
+The optional `format` argument allows you to specify and override which data type is contained
+within the file specified in the `path` argument. Valid entries are `toml`, `json`, `csv`, `bibtex`
+or `plain`. If the `format` argument isn't specified, then the path extension is used.
+
+```jinja2
+{% set data = load_data(path="content/blog/story/data.txt", format="json") %}
+```
+
+Use the `plain` format for when your file has a toml/json/csv extension but you want to load it as plain text.
+
+For *toml* and *json*, the data is loaded into a structure matching the original data file;
+however, for *csv* there is no native notion of such a structure. Instead, the data is separated
+into a data structure containing *headers* and *records*. See the example below to see
+how this works.
+
+In the template:
+```jinja2
+{% set data = load_data(path="content/blog/story/data.csv") %}
+```
+
+In the *content/blog/story/data.csv* file:
+```csv
+Number, Title
+1,Gutenberg
+2,Printing
+```
+
+The equivalent json value of the parsed data would be stored in the `data` variable in the
+template:
+```json
+{
+    "headers": ["Number", "Title"],
+    "records": [
+        ["1", "Gutenberg"],
+        ["2", "Printing"]
+    ],
+}
+```
+
+The `bibtex` format loads data into a structure matching the format used by the
+[nom-bibtex crate](https://crates.io/crates/nom-bibtex). The following is an example of data
+in bibtex format:
+
+```
+@preamble{"A bibtex preamble" # " this is."}
+
+@Comment{
+    Here is a comment.
+}
+
+Another comment!
+
+@string(name = "Vincent Prouillet")
+@string(github = "https://github.com/getzola/zola")
+
+@misc {my_citation_key,
+    author= name,
+    title = "Zola",
+    note = "github: " # github
+}                                                    }
+```
+
+The following is the json-equivalent format of the produced bibtex data structure:
+```json
+{
+    "preambles": ["A bibtex preamble this is."],
+    "comments": ["Here is a comment.", "Another comment!"],
+    "variables": {
+        "name": "Vincent Prouillet",
+        "github": "https://github.com/getzola/zola"
+    },
+    "bibliographies": [
+        {
+            "entry_type": "misc",
+            "citation_key": "my_citation_key",
+            "tags": {
+                "author": "Vincent Prouillet",
+                "title": "Zola",
+                "note": "github: https://github.com/getzola/zola"
+            }
+        }
+    ]
+}
+```
+
+Finally, the bibtex data can be accessed from the template as follows:
+```jinja2
+{% set tags = data.bibliographies[0].tags %}
+This was generated using {{ tags.title }}, authored by {{ tags.author }}.
+```
+
+#### Remote content
+
+Instead of using a file, you can load data from a remote URL. This can be done by specifying a `url` parameter
+to `load_data` rather than `path`.
+
+```jinja2
+{% set response = load_data(url="https://api.github.com/repos/getzola/zola") %}
+{{ response }}
+```
+
+By default, the response body will be returned with no parsing. This can be changed by using the `format` argument
+as below.
+
+
+```jinja2
+{% set response = load_data(url="https://api.github.com/repos/getzola/zola", format="json") %}
+{{ response }}
+```
+
+#### Data caching
+
+Data file loading and remote requests are cached in memory during the build, so multiple requests aren't made
+to the same endpoint.
+URLs are cached based on the URL, and data files are cached based on the file modified time.
+The format is also taken into account when caching, so a request will be sent twice if it's loaded with two
+different formats.
+
+### `trans`
+Gets the translation of the given `key`, for the `default_language` or the `lang`uage given
+
+```jinja2
+{{/* trans(key="title") */}}
+{{/* trans(key="title", lang="fr") */}}
+```
+
+### `resize_image`
+Resizes an image file.
+Please refer to  Content / Image Processing for complete documentation.
diff --git a/content/templates/pages-sections.md b/content/templates/pages-sections.md
new file mode 100644
index 0000000..ec550ed
--- /dev/null
+++ b/content/templates/pages-sections.md
@@ -0,0 +1,145 @@
++++
+title = "Sections and Pages"
+weight = 20
++++
+
+Templates for pages and sections are very similar.
+
+## Page variables
+Zola will try to load the `templates/page.html` template, the `page.html` template of the theme if one is used
+or render the built-in template (a blank page).
+
+Whichever template you decide to render, you will get a `page` variable in your template
+with the following fields:
+
+
+```ts
+// The HTML output of the Markdown content
+content: String;
+title: String?;
+description: String?;
+date: String?;
+// `updated` will be the same as `date` if `date` is specified but `updated` is not in front-matter
+updated: String?;
+slug: String;
+path: String;
+draft: Bool;
+// the path, split on '/'
+components: Array<String>;
+permalink: String;
+summary: String?;
+taxonomies: HashMap<String, Array<String>>;
+extra: HashMap<String, Any>;
+toc: Array<Header>,
+// Naive word count, will not work for languages without whitespace
+word_count: Number;
+// Based on https://help.medium.com/hc/en-us/articles/214991667-Read-time
+reading_time: Number;
+// `earlier` and `later` are only populated if the section variable `sort_by` is set to `date`
+// and only set when rendering the page itself
+earlier: Page?;
+later: Page?;
+// `heavier` and `lighter` are only populated if the section variable `sort_by` is set to `weight`
+// and only set when rendering the page itself
+heavier: Page?;
+lighter: Page?;
+// Year/month/day is only set if the page has a date and month/day are 1-indexed
+year: Number?;
+month: Number?;
+day: Number?;
+// Paths of colocated assets, relative to the content directory
+assets: Array<String>;
+// The relative paths of the parent sections until the index one, for use with the `get_section` Tera function
+// The first item is the index section and the last one is the parent section
+// This is filled after rendering a page content so it will be empty in shortcodes
+ancestors: Array<String>;
+// The relative path from the `content` directory to the markdown file
+relative_path: String;
+// The language for the page if there is one. Default to the config `default_language`
+lang: String;
+// Information about all the available languages for that content
+translations: Array<TranslatedContent>;
+```
+
+## Section variables
+By default, Zola will try to load `templates/index.html` for `content/_index.md`
+and `templates/section.html` for other `_index.md` files. If there isn't
+one, it will render the built-in template (a blank page).
+
+Whichever template you decide to render, you will get a `section` variable in your template
+with the following fields:
+
+
+```ts
+// The HTML output of the Markdown content
+content: String;
+title: String?;
+description: String?;
+path: String;
+// the path, split on '/'
+components: Array<String>;
+permalink: String;
+extra: HashMap<String, Any>;
+// Pages directly in this section. By default, the pages are not sorted. Please set the "sorted_by"
+// variable in the _index.md file of the corresponding section to "date" or "weight" for sorting by
+// date and weight, respectively.
+pages: Array<Page>;
+// Direct subsections to this section, sorted by subsections weight
+// This only contains the path to use in the `get_section` Tera function to get
+// the actual section object if you need it
+subsections: Array<String>;
+toc: Array<Header>,
+// Unicode word count
+word_count: Number;
+// Based on https://help.medium.com/hc/en-us/articles/214991667-Read-time
+reading_time: Number;
+// Paths of colocated assets, relative to the content directory
+assets: Array<String>;
+// The relative paths of the parent sections until the index one, for use with the `get_section` Tera function
+// The first item is the index section and the last one is the parent section
+// This is filled after rendering a page content so it will be empty in shortcodes
+ancestors: Array<String>;
+// The relative path from the `content` directory to the markdown file
+relative_path: String;
+// The language for the section if there is one. Default to the config `default_language`
+lang: String;
+// Information about all the available languages for that content
+translations: Array<TranslatedContent>;
+```
+
+## Table of contents
+
+Both page and section templates have a `toc` variable that corresponds to an array of `Header`.
+A `Header` has the following fields:
+
+```ts
+// The hX level
+level: 1 | 2 | 3 | 4 | 5 | 6;
+// The generated slug id
+id: String;
+// The text of the header
+title: String;
+// A link pointing directly to the header, using the inserted anchor
+permalink: String;
+// All lower level headers below this header
+children: Array<Header>;
+```
+
+## Translated content
+
+Both pages and sections have a `translations` field that corresponds to an array of `TranslatedContent`. If your
+site is not using multiple languages, this will always be an empty array.
+`TranslatedContent` has the following fields:
+
+```ts
+// The language code for that content, empty if it is the default language
+lang: String?;
+// The title of that content if there is one
+title: String?;
+// A permalink to that content
+permalink: String;
+// The path to the markdown file; useful for retrieving the full page through
+// the `get_page` function.
+path: String;
+```
+
diff --git a/content/templates/pagination.md b/content/templates/pagination.md
new file mode 100644
index 0000000..846a2cc
--- /dev/null
+++ b/content/templates/pagination.md
@@ -0,0 +1,51 @@
++++
+title = "Pagination"
+weight = 30
++++
+
+Two things can get paginated: a section and a taxonomy term.
+
+Both kinds get a `paginator` variable of the `Pager` type, on top of the common variables mentioned in the
+[overview page](@/templates/overview.md):
+
+```ts
+// How many items per pager
+paginate_by: Number;
+// The base URL for the pagination: section permalink + pagination path
+// You can concatenate an integer with that to get a link to a given pagination pager.
+base_url: String;
+// How many pagers in total
+number_pagers: Number;
+// Permalink to the first pager
+first: String;
+// Permalink to the last pager
+last: String;
+// Permalink to the previous pager, if there is one
+previous: String?;
+// Permalink to the next pager, if there is one
+next: String?;
+// All pages for the current pager
+pages: Array<Page>;
+// Which pager are we on
+current_index: Number;
+// Total number of pages accross all the pagers
+total_pages: Number;
+```
+
+A pager is a page of the pagination; if you have 100 pages and paginate_by is set to 10, you will have 10 pagers each
+containing 10 pages.
+
+## Section
+
+A paginated section gets the same `section` variable as a normal
+[section page](@/templates/pages-sections.md#section-variables)
+minus its pages. The pages are instead in `paginator.pages`.
+
+## Taxonomy term
+
+A paginated taxonomy gets two variables aside from the `paginator` variable:
+
+- a `taxonomy` variable of type `TaxonomyConfig`
+- a `term` variable of type `TaxonomyTerm`.
+
+See the [taxonomies page](@/templates/taxonomies.md) for a detailed version of the types.
diff --git a/content/templates/robots.md b/content/templates/robots.md
new file mode 100644
index 0000000..40a1089
--- /dev/null
+++ b/content/templates/robots.md
@@ -0,0 +1,16 @@
++++
+title = "Robots.txt"
+weight = 70
++++
+
+Zola will look for a `robots.txt` file in the `templates` directory or
+use the built-in one.
+
+Robots.txt is the simplest of all templates: it only gets `config`
+and the default is what most sites want:
+
+```jinja2
+User-agent: *
+Allow: /
+Sitemap: {{/* get_url(path="sitemap.xml") */}}
+```
diff --git a/content/templates/sitemap.md b/content/templates/sitemap.md
new file mode 100644
index 0000000..3c21351
--- /dev/null
+++ b/content/templates/sitemap.md
@@ -0,0 +1,34 @@
++++
+title = "Sitemap"
+weight = 60
++++
+
+Zola will look for a `sitemap.xml` file in the `templates` directory or
+use the built-in one.
+
+If your site has more than 30 000 pages, it will automatically split
+the links into multiple sitemaps, as recommended by [Google](https://support.google.com/webmasters/answer/183668?hl=en):
+
+> All formats limit a single sitemap to 50MB (uncompressed) and 50,000 URLs. 
+> If you have a larger file or more URLs, you will have to break your list into multiple sitemaps. 
+> You can optionally create a sitemap index file (a file that points to a list of sitemaps) and submit
+> that single index file to Google.
+
+In such a case, Zola will use a template called `split_sitemap_index.xml` to render the index sitemap.
+
+
+The `sitemap.xml` template gets a single variable:
+
+- `entries`: all pages of the site, as a list of `SitemapEntry`
+
+A `SitemapEntry` has the following fields:
+
+```ts
+permalink: String;
+updated: String?;
+extra: Hashmap<String, Any>?;
+```
+
+The `split_sitemap_index.xml` also gets a single variable:
+
+- `sitemaps`: a list of permalinks to the sitemaps
diff --git a/content/templates/taxonomies.md b/content/templates/taxonomies.md
new file mode 100644
index 0000000..1ca3286
--- /dev/null
+++ b/content/templates/taxonomies.md
@@ -0,0 +1,68 @@
++++
+title = "Taxonomies"
+weight = 40
++++
+
+Zola will look up the following files in the `templates` directory:
+
+- `$TAXONOMY_NAME/single.html`
+- `$TAXONOMY_NAME/list.html`
+
+First, `TaxonomyTerm` has the following fields:
+
+```ts
+name: String;
+slug: String;
+permalink: String;
+pages: Array<Page>;
+```
+
+and `TaxonomyConfig` has the following fields:
+
+```ts
+name: String,
+paginate_by: Number?;
+paginate_path: String?;
+feed: Bool;
+lang: String;
+```
+
+
+### Taxonomy list (`list.html`)
+
+This template is never paginated and therefore gets the following variables in all cases.
+
+```ts
+// The site config
+config: Config;
+// The data of the taxonomy, from the config
+taxonomy: TaxonomyConfig;
+// The current full permalink for that page
+current_url: String;
+// The current path for that page
+current_path: String;
+// All terms for that taxonomy
+terms: Array<TaxonomyTerm>;
+// The lang of the current page
+lang: String;
+```
+
+
+### Single term (`single.html`)
+```ts
+// The site config
+config: Config;
+// The data of the taxonomy, from the config
+taxonomy: TaxonomyConfig;
+// The current full permalink for that page
+current_url: String;
+// The current path for that page
+current_path: String;
+// The current term being rendered
+term: TaxonomyTerm;
+// The lang of the current page
+lang: String;
+```
+
+A paginated taxonomy term will also get a `paginator` variable; see the
+[pagination page](@/templates/pagination.md) for more details.