initial commit

51 files changed, 4142 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..85a1daf
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+/public
\ No newline at end of file
diff --git a/config.toml b/config.toml
new file mode 100644
index 0000000..042f023
--- /dev/null
+++ b/config.toml
@@ -0,0 +1,12 @@
+base_url = "https://example.com"
+title = "Docs"
+compile_sass = true
+build_search_index = true
+
+[markdown]
+highlight_code = true
+highlight_theme = "base16-ocean-light"
+
+[extra]
+logo = "https://logoipsum.com/logo/logo-11.svg"
+release = "https://api.github.com/repos/getzola/zola/releases/latest"
\ No newline at end of file
diff --git a/content/_index.md b/content/_index.md
new file mode 100644
index 0000000..5205ef4
--- /dev/null
+++ b/content/_index.md
@@ -0,0 +1,30 @@
++++
+title = "spec"
++++
+
+
+Getting started
+ - Installation
+ - CLI usage
+ - Directory structure
+ - config.toml
+ 
+Content
+ - Organisation
+ - Sections
+ - Pages
+ - Shortcodes
+ - Internal links & deep linking
+ - Table of contents
+ - Syntax highlighting
+ - Sass
+ 
+Templates
+ - Intro
+ - Each kind of page and the variables available
+ - Built-in global functions
+ - Built-in filters
+
+Theme
+ - Installing & customising a theme
+ - Creating a theme
diff --git a/content/content/_index.md b/content/content/_index.md
new file mode 100644
index 0000000..85ed62e
--- /dev/null
+++ b/content/content/_index.md
@@ -0,0 +1,6 @@
++++
+title = "Content"
+weight = 2
+sort_by = "weight"
+insert_anchor_links = "right"
++++
diff --git a/content/content/linking.md b/content/content/linking.md
new file mode 100644
index 0000000..e8352e5
--- /dev/null
+++ b/content/content/linking.md
@@ -0,0 +1,55 @@
++++
+title = "Internal links & deep linking"
+weight = 50
++++
+
+## Heading id and anchor insertion
+While rendering the Markdown content, a unique id will automatically be assigned to each heading. 
+This id is created by converting the heading text to a [slug](https://en.wikipedia.org/wiki/Semantic_URL#Slug) if `slugify.anchors` is set to `"on"` (the default).
+If `slugify.paths` is set to `"safe"`, whitespaces are replaced by `_` and the following characters are stripped: `#`, `%`, `<`, `>`, `[`, `]`, `(`, `)`, \`, `^`, `{`, `|`, `}`.
+If `slugify.paths` is set to `"off"`, no modifications are made, and you may be left with nominally illegal ids.
+A number is appended at the end if the slug already exists for that article 
+For example:
+
+```md
+# Something exciting! <- something-exciting
+## Example code <- example-code
+
+# Something else <- something-else
+## Example code <- example-code-1
+```
+
+You can also manually specify an id with a `{#…}` suffix on the heading line:
+
+```md
+# Something manual! {#manual}
+```
+
+This is useful for making deep links robust, either proactively (so that you can later change the text of a heading
+without breaking links to it) or retroactively (keeping the slug of the old header text when changing the text). It
+can also be useful for migration of existing sites with different header id schemes, so that you can keep deep
+links working.
+
+## Anchor insertion
+It is possible to have Zola automatically insert anchor links next to the heading, as you can see on this documentation
+if you hover a title.
+
+This option is set at the section level: the `insert_anchor_links` variable on the
+[section front matter page](@/content/section.md#front-matter).
+
+The default template is very basic and will need CSS tweaks in your project to look decent.
+If you want to change the anchor template, it can be easily overwritten by
+creating an `anchor-link.html` file in the `templates` directory.
+
+The anchor link template has the following variables:
+
+- `id`: the heading's id after applying the rules defined by `slugify.anchors`
+- `level`: the heading level (between 1 and 6)
+
+## Internal links
+Linking to other pages and their headings is so common that Zola adds a
+special syntax to Markdown links to handle them: start the link with `@/` and point to the `.md` file you want
+to link to. The path to the file starts from the `content` directory.
+
+For example, linking to a file located at `content/pages/about.md` would be `[my link](@/pages/about.md)`.
+You can still link to an anchor directly; `[my link](@/pages/about.md#example)` will work as expected.
diff --git a/content/content/multilingual.md b/content/content/multilingual.md
new file mode 100644
index 0000000..cd697ff
--- /dev/null
+++ b/content/content/multilingual.md
@@ -0,0 +1,44 @@
++++
+title = "Multilingual sites"
+weight = 130
++++
+
+Zola supports having a site in multiple languages.
+
+## Configuration
+To get started, you will need to add the languages you want to support
+to your `config.toml`. For example:
+
+```toml
+languages = [
+    {code = "fr", feed = true}, # there will be a feed for French content
+    {code = "fr", search = true}, # there will be a Search Index for French content
+    {code = "it"}, # there won't be a feed for Italian content
+]
+```
+
+If you want to use per-language taxonomies, ensure you set the `lang` field in their
+configuration.
+
+Note: By default, Chinese and Japanese search indexing is not included. You can include
+the support by building `zola` using `cargo build --features search/indexing-ja search/indexing-zh`.
+Please also note that, enabling Chinese indexing will increase the binary size by approximately
+5 MB while enabling Japanese indexing will increase the binary size by approximately 70 MB 
+due to the incredibly large dictionaries.
+
+## Content
+Once the languages have been added, you can start to translate your content. Zola
+uses the filename to detect the language:
+
+- `content/an-article.md`: this will be the default language
+- `content/an-article.fr.md`: this will be in French
+
+If the language code in the filename does not correspond to one of the languages or
+the default language configured, an error will be shown.
+
+If your default language has an `_index.md` in a directory, you will need to add an `_index.{code}.md`
+file with the desired front-matter options as there is no language fallback.
+
+## Output
+Zola outputs the translated content with a base URL of `{base_url}/{code}/`.
+The only exception to this is if you are setting a translated page `path` directly in the front matter.
diff --git a/content/content/overview.md b/content/content/overview.md
new file mode 100644
index 0000000..98b1d47
--- /dev/null
+++ b/content/content/overview.md
@@ -0,0 +1,117 @@
++++
+title = "Overview"
+weight = 10
++++
+
+Zola uses the directory structure to determine the site structure.
+Each child directory in the `content` directory represents a [section](@/content/section.md)
+that contains [pages](@/content/page.md) (your `.md` files).
+
+```bash
+.
+└── content
+    ├── content
+    │   └── something.md // -> https://mywebsite.com/content/something/
+    ├── blog
+    │   ├── cli-usage.md // -> https://mywebsite.com/blog/cli-usage/
+    │   ├── configuration.md // -> https://mywebsite.com/blog/configuration/
+    │   ├── directory-structure.md // -> https://mywebsite.com/blog/directory-structure/
+    │   ├── _index.md // -> https://mywebsite.com/blog/
+    │   └── installation.md // -> https://mywebsite.com/blog/installation/
+    └── landing
+        └── _index.md // -> https://mywebsite.com/landing/
+```
+
+Each page path (the part after `base_url`, for example `blog/cli-usage/`) can be customised by changing the `path` or
+`slug` attribute of the [page front-matter](@/content/page.md#front-matter).
+
+You might have noticed a file named `_index.md` in the example above.
+This file is used to store both the metadata and content of the section itself and is not considered a page.
+
+To ensure that the terminology used in the rest of the documentation is understood, let's go over the example above.
+
+The `content` directory in this case has three `sections`: `content`, `blog` and `landing`. The `content` section has only
+one page (`something.md`), the `landing` section has no pages and the `blog` section has 4 pages (`cli-usage.md`,
+`configuration.md`, `directory-structure.md` and `installation.md`).
+
+Sections can be nested indefinitely.
+
+## Asset colocation
+
+The `content` directory is not limited to markup files. It's natural to want to co-locate a page and some related
+assets, such as images or spreadsheets. Zola supports this pattern out of the box for both sections and pages.
+
+All non-Markdown files you add in a page/section directory will be copied alongside the generated page when the site is
+built, which allows us to use a relative path to access them.
+
+Pages with co-located assets should not be placed directly in their section directory (such as `latest-experiment.md`), but
+as an `index.md` file in a dedicated directory (`latest-experiment/index.md`), like so:
+
+
+```bash
+└── research
+    ├── latest-experiment
+    │   ├── index.md
+    │   └── yavascript.js
+    ├── _index.md
+    └── research.jpg
+```
+
+With this setup, you may access `research.jpg` from your 'research' section
+and `yavascript.js` from your 'latest-experiment' page directly within the Markdown:
+
+```Markdown
+Check out the complete program [here](yavascript.js). It's **really cool free-software**!
+```
+
+By default, this page's slug will be the directory name and thus its permalink will be `https://example.com/research/latest-experiment/`.
+
+### Excluding files from assets
+
+It is possible to ignore selected asset files using the
+[ignored_content](@/getting-started/configuration.md) setting in the config file.
+For example, say that you have an Excel spreadsheet from which you are taking several screenshots and
+then linking to these image files on your website. For maintainability, you want to keep
+the spreadsheet in the same directory as the Markdown file, but you don't want to copy the spreadsheet to
+the public web site. You can achieve this by setting `ignored_content` in the config file:
+
+```
+ignored_content = ["*.xlsx"]
+```
+
+## Static assets
+
+In addition to placing content files in the `content` directory, you may also place content
+files in the `static` directory.  Any files/directories that you place in the `static` directory
+will be copied, without modification, to the `public` directory.
+
+Typically, you might put site-wide assets (such as the site favicon, site logos or site-wide
+JavaScript) in the root of the static directory. You can also place any HTML or other files that
+you wish to be included without modification (that is, without being parsed as Markdown files)
+into the static directory.
+
+Note that the static directory provides an _alternative_ to co-location.  For example, imagine that you
+had the following directory structure (a simplified version of the structure presented above):
+
+```bash
+.
+└── content
+    └── blog
+        ├── configuration
+        │    └── index.md // -> https://mywebsite.com/blog/configuration/
+        └── _index.md // -> https://mywebsite.com/blog/
+```
+
+To add an image to the `https://mywebsite.com/blog/configuration` page, you have three options:
+ *  You could save the image to the `content/blog/configuration` directory and then link to it with a
+ relative path from the `index.md` page.  This is the approach described under **co-location**
+ above.
+ *  You could save the image to a `static/blog/configuration` directory and link to it in exactly the
+ same way as if you had co-located it. If you do this, the generated files will be identical to those
+ obtained if you had co-located the image; the only difference will be that all static files will be saved in the
+ static directory rather than in the content directory. The choice depends on your organizational needs.
+ *  Or you could save the image to some arbitrary directory within the static directory. For example,
+ you could save all images to `static/images`.  Using this approach, you can no longer use relative links. Instead,
+ you must use an absolute link to `images/[filename]` to access your
+ image. This might be preferable for small sites or for sites that associate images with
+ multiple pages (e.g., logo images that appear on every page).
diff --git a/content/content/page.md b/content/content/page.md
new file mode 100644
index 0000000..2038c50
--- /dev/null
+++ b/content/content/page.md
@@ -0,0 +1,154 @@
++++
+title = "Page"
+weight = 30
++++
+
+A page is any file ending with `.md` in the `content` directory, except files
+named `_index.md`.
+
+If a file ending with `.md` is named `index.md`, it will generate a page
+with the name of its directory (for example, `/content/about/index.md` would
+create a page at `[base_url]/about`). (Note the lack of an underscore; if the file
+were named `_index.md`, then it would create a **section** at `[base_url]/about`, as
+discussed in a previous part of this documentation.  In contrast, naming the file `index.md` will
+create a **page** at `[base_url]/about`).
+
+If the file is given any name *other* than `index.md` or `_index.md`, then it will
+create a page with that name (without the `.md`). For example, naming a file in the root of your
+content directory `about.md` would create a page at `[base_url]/about`.
+Another exception to this rule is that a filename starting with a datetime (YYYY-mm-dd or [an RFC3339 datetime](https://www.ietf.org/rfc/rfc3339.txt)) followed by
+an underscore (`_`) or a dash (`-`) will use that date as the page date, unless already set
+in the front matter. The page name will be anything after `_`/`-`, so the file `2018-10-10-hello-world.md` will
+be available at `[base_url]/hello-world`. Note that the full RFC3339 datetime contains colons, which is not a valid
+character in a filename on Windows.
+
+As you can see, creating an `about.md` file is equivalent to creating an
+`about/index.md` file.  The only difference between the two methods is that creating
+the `about` directory allows you to use asset co-location, as discussed in the
+[overview](@/content/overview.md#asset-colocation) section.
+
+## Output paths
+
+For any page within your content folder, its output path will be defined by either:
+
+- its `slug` frontmatter key
+- its filename
+
+Either way, these proposed path will be sanitized before being used.
+If `slugify.paths` is set to `"on"` in the site's config - the default - paths are [slugified](https://en.wikipedia.org/wiki/Clean_URL#Slug). 
+If it is set to `"safe"`, only sanitation is performed, with the following characters being removed: `<`, `>`, `:`, `/`, `|`, `?`, `*`, `#`, `\\`, `(`, `)`, `[`, `]` as well as newlines and tabulations. This ensures that the path can be represented on all operating systems.
+Additionally, trailing whitespace and dots are removed and whitespaces are replaced by `_`.
+
+If `slugify.paths` is set to `"off"`, no modifications are made.
+
+If you want URLs containing non-ASCII characters, `slugify.paths` needs to be set to `"safe"` or `"off"`.
+
+### Path from frontmatter
+
+The output path for the page will first be read from the `slug` key in the page's frontmatter.
+
+**Example:** (file `content/zines/mlf-kurdistan.md`)
+
+```
++++
+title = "Le mouvement des Femmes Libres, à la tête de la libération kurde"
+slug = "femmes-libres-libération-kurde"
++++
+This is my article.
+```
+
+This frontmatter will output the article to `[base_url]/zines/femmes-libres-libération-kurde` with `slugify.paths` set to `"safe"` or `"off"`, and to `[base_url]/zines/femmes-libres-liberation-kurde` with the default value for `slugify.paths` of `"on"`.
+
+### Path from filename
+
+When the article's output path is not specified in the frontmatter, it is extracted from the file's path in the content folder. Consider a file `content/foo/bar/thing.md`. The output path is constructed:
+- if the filename is `index.md`, its parent folder name (`bar`) is used as output path
+- otherwise, the output path is extracted from `thing` (the filename without the `.md` extension)
+
+If the path found starts with a datetime string (`YYYY-mm-dd` or [a RFC3339 datetime](https://www.ietf.org/rfc/rfc3339.txt)) followed by an underscore (`_`) or a dash (`-`), this date is removed from the output path and will be used as the page date (unless already set in the front-matter). Note that the full RFC3339 datetime contains colons, which is not a valid character in a filename on Windows.
+
+The output path extracted from the file path is then slugified or not, depending on the `slugify.paths` config, as explained previously.
+
+**Example:**
+The file `content/blog/2018-10-10-hello-world.md` will yield a page at `[base_url]/blog/hello-world`.
+
+## Front matter
+
+The TOML front matter is a set of metadata embedded in a file at the beginning of the file enclosed
+by triple pluses (`+++`).
+
+Although none of the front matter variables are mandatory, the opening and closing `+++` are required.
+
+Note that even though the use of TOML is encouraged, YAML front matter is also supported to ease porting
+legacy content. In this case the embedded metadata must be enclosed by triple minuses (`---`).
+
+Here is an example page with all the available variables. The values provided below are the
+default values.
+
+```toml
+title = ""
+description = ""
+
+# The date of the post.
+# Two formats are allowed: YYYY-MM-DD (2012-10-02) and RFC3339 (2002-10-02T15:00:00Z).
+# Do not wrap dates in quotes; the line below only indicates that there is no default date.
+# If the section variable `sort_by` is set to `date`, then any page that lacks a `date`
+# will not be rendered.
+# Setting this overrides a date set in the filename.
+date =
+
+# The last updated date of the post, if different from the date.
+# Same format as `date`.
+updated =
+
+# The weight as defined on the Section page of the documentation.
+# If the section variable `sort_by` is set to `weight`, then any page that lacks a `weight`
+# will not be rendered.
+weight = 0
+
+# A draft page is only loaded if the `--drafts` flag is passed to `zola build`, `zola serve` or `zola check`.
+draft = false
+
+# If set, this slug will be instead of the filename to make the URL.
+# The section path will still be used.
+slug = ""
+
+# The path the content will appear at.
+# If set, it cannot be an empty string and will override both `slug` and the filename.
+# The sections' path won't be used.
+# It should not start with a `/` and the slash will be removed if it does.
+path = ""
+
+# Use aliases if you are moving content but want to redirect previous URLs to the
+# current one. This takes an array of paths, not URLs.
+aliases = []
+
+# When set to "true", the page will be in the search index. This is only used if
+# `build_search_index` is set to "true" in the Zola configuration and the parent section
+# hasn't set `in_search_index` to "false" in its front matter.
+in_search_index = true
+
+# Template to use to render this page.
+template = "page.html"
+
+# The taxonomies for this page. The keys need to be the same as the taxonomy
+# names configured in `config.toml` and the values are an array of String objects. For example,
+# tags = ["rust", "web"].
+[taxonomies]
+
+# Your own data.
+[extra]
+```
+
+## Summary
+
+You can ask Zola to create a summary if, for example, you only want to show the first
+paragraph of the page content in a list.
+
+To do so, add <code>&lt;!-- more --&gt;</code> in your content at the point
+where you want the summary to end. The content up to that point will be
+available separately in the
+[template](@/templates/pages-sections.md#page-variables).
+
+A span element in this position with a `continue-reading` id is created, so you can link directly to it if needed. For example:
+`<a href="{{ page.permalink }}#continue-reading">Continue Reading</a>`.
diff --git a/content/content/sass.md b/content/content/sass.md
new file mode 100644
index 0000000..8764467
--- /dev/null
+++ b/content/content/sass.md
@@ -0,0 +1,42 @@
++++
+title = "Sass"
+weight = 110
++++
+
+Sass is a popular CSS preprocessor that adds special features (e.g., variables, nested rules) to facilitate the
+maintenance of large sets of CSS rules. If you're curious about what Sass
+is and why it might be useful for styling your static site, the following links
+may be of interest:
+
+* The [official Sass website](http://sass-lang.com/)
+* [Why Sass?](https://alistapart.com/article/why-sass), by Dan Cederholm
+
+## Using Sass in Zola
+
+Zola processes any files with the `sass` or `scss` extension in the `sass`
+folder, and places the processed output into a `css` file with the same folder
+structure and base name into the `public` folder:
+
+```bash
+.
+└── sass
+    ├── style.scss // -> ./public/style.css
+    ├── indented_style.sass // -> ./public/indented_style.css
+    ├── _include.scss # This file won't get put into the `public` folder, but other files can @import it.
+    ├── assets
+    │   ├── fancy.scss // -> ./public/assets/fancy.css
+    │   ├── same_name.scss // -> ./public/assets/same_name.css
+    │   ├── same_name.sass # CONFLICT! This has the same base name as the file above, so Zola will return an error.
+    │   └── _common_mixins.scss # This file won't get put into the `public` folder, but other files can @import it.
+    └── secret-side-project
+        └── style.scss // -> ./public/secret-side-project/style.css
+```
+
+Files with a leading underscore in the name are not placed into the `public`
+folder, but can still be used as `@import` dependencies. For more information, see the "Partials" section of
+[Sass Basics](https://sass-lang.com/guide).
+
+Files with the `scss` extension use "Sassy CSS" syntax,
+while files with the `sass` extension use the "indented" syntax: <https://sass-lang.com/documentation/syntax>.
+Zola will return an error if `scss` and `sass` files with the same
+base name exist in the same folder to avoid confusion -- see the example above.
diff --git a/content/content/search.md b/content/content/search.md
new file mode 100644
index 0000000..d091105
--- /dev/null
+++ b/content/content/search.md
@@ -0,0 +1,26 @@
++++
+title = "Search"
+weight = 100
++++
+
+Zola can build a search index from the sections and pages content to
+be used by a JavaScript library such as [elasticlunr](http://elasticlunr.com/).
+
+To enable it, you only need to set `build_search_index = true` in your `config.toml` and Zola will
+generate an index for the `default_language` set for all pages not excluded from the search index.
+
+It is very important to set the `default_language` in your `config.toml` if you are writing a site not in
+English; the index building pipelines are very different depending on the language.
+
+After `zola build` or `zola serve`, you should see two files in your static directory:
+
+- `search_index.${default_language}.js`: so `search_index.en.js` for a default setup
+- `elasticlunr.min.js`
+
+As each site will be different, Zola makes no assumptions about your search function and doesn't provide
+the JavaScript/CSS code to do an actual search and display results. You can look at how this site
+implements it to get an idea: [search.js](https://github.com/getzola/zola/tree/master/docs/static/search.js).
+
+## Configuring the search index
+In some cases, the default indexing strategy is not suitable. You can customise which fields to include and whether
+to truncate the content in the [search configuration](@/getting-started/configuration.md).
diff --git a/content/content/section.md b/content/content/section.md
new file mode 100644
index 0000000..2951007
--- /dev/null
+++ b/content/content/section.md
@@ -0,0 +1,192 @@
++++
+title = "Section"
+weight = 20
++++
+
+A section is created whenever a directory (or subdirectory) in the `content` section contains an
+`_index.md` file.  If a directory does not contain an `_index.md` file, no section will be
+created, but Markdown files within that directory will still create pages (known as orphan pages).
+
+The index page (i.e., the page displayed when a user browses to your `base_url`) is a section,
+which is created whether or not you add an `_index.md` file at the root of your `content` directory.
+If you do not create an `_index.md` file in your content directory, this main content section will
+not have any content or metadata.  If you would like to add content or metadata, you can add an
+`_index.md` file at the root of the `content` directory and edit it just as you would edit any other
+`_index.md` file; your `index.html` template will then have access to that content and metadata.
+
+Any non-Markdown file in a section directory is added to the `assets` collection of the section, as explained in the
+[content overview](@/content/overview.md#asset-colocation). These files are then available in the
+Markdown file using relative links.
+
+## Drafting
+Just like pages sections can be drafted by setting the `draft` option in the front matter. By default this is not