From 3ec976842cfc3e6b908de1a16f9bd18948007ecc Mon Sep 17 00:00:00 2001 From: codeandmedia Date: Sat, 13 Mar 2021 20:15:21 +0300 Subject: initial commit --- .gitignore | 1 + config.toml | 12 + content/_index.md | 30 +++ content/content/_index.md | 6 + content/content/linking.md | 55 ++++ content/content/multilingual.md | 44 ++++ content/content/overview.md | 117 +++++++++ content/content/page.md | 154 +++++++++++ content/content/sass.md | 42 +++ content/content/search.md | 26 ++ content/content/section.md | 192 ++++++++++++++ content/content/shortcodes.md | 243 ++++++++++++++++++ content/content/syntax-highlighting.md | 171 ++++++++++++ content/content/table-of-contents.md | 36 +++ content/content/taxonomies.md | 138 ++++++++++ content/deployment/_index.md | 6 + content/deployment/github-pages.md | 120 +++++++++ content/deployment/gitlab-pages.md | 71 +++++ content/deployment/netlify.md | 70 +++++ content/deployment/overview.md | 9 + content/deployment/vercel.md | 36 +++ content/getting-started/_index.md | 5 + content/getting-started/cli-usage.md | 129 ++++++++++ content/getting-started/configuration.md | 245 ++++++++++++++++++ content/getting-started/directory-structure.md | 51 ++++ content/getting-started/installation.md | 107 ++++++++ content/getting-started/overview.md | 208 +++++++++++++++ content/templates/404.md | 7 + content/templates/_index.md | 5 + content/templates/archive.md | 23 ++ content/templates/feeds/index.md | 64 +++++ content/templates/feeds/rss_feed.png | Bin 0 -> 12874 bytes content/templates/overview.md | 343 +++++++++++++++++++++++++ content/templates/pages-sections.md | 145 +++++++++++ content/templates/pagination.md | 51 ++++ content/templates/robots.md | 16 ++ content/templates/sitemap.md | 34 +++ content/templates/taxonomies.md | 68 +++++ content/themes/_index.md | 5 + content/themes/creating-a-theme.md | 72 ++++++ content/themes/extending-a-theme.md | 21 ++ content/themes/installing-and-using-themes.md | 65 +++++ content/themes/overview.md | 11 + sass/_search.scss | 61 +++++ sass/_variables.scss | 13 + sass/fabric-icons-inline.scss | 40 +++ sass/main.scss | 339 ++++++++++++++++++++++++ static/js.js | 295 +++++++++++++++++++++ templates/anchor-link.html | 1 + templates/index.html | 135 ++++++++++ templates/page.html | 4 + 51 files changed, 4142 insertions(+) create mode 100644 .gitignore create mode 100644 config.toml create mode 100644 content/_index.md create mode 100644 content/content/_index.md create mode 100644 content/content/linking.md create mode 100644 content/content/multilingual.md create mode 100644 content/content/overview.md create mode 100644 content/content/page.md create mode 100644 content/content/sass.md create mode 100644 content/content/search.md create mode 100644 content/content/section.md create mode 100644 content/content/shortcodes.md create mode 100644 content/content/syntax-highlighting.md create mode 100644 content/content/table-of-contents.md create mode 100644 content/content/taxonomies.md create mode 100644 content/deployment/_index.md create mode 100644 content/deployment/github-pages.md create mode 100644 content/deployment/gitlab-pages.md create mode 100644 content/deployment/netlify.md create mode 100644 content/deployment/overview.md create mode 100644 content/deployment/vercel.md create mode 100644 content/getting-started/_index.md create mode 100644 content/getting-started/cli-usage.md create mode 100644 content/getting-started/configuration.md create mode 100644 content/getting-started/directory-structure.md create mode 100644 content/getting-started/installation.md create mode 100644 content/getting-started/overview.md create mode 100644 content/templates/404.md create mode 100644 content/templates/_index.md create mode 100644 content/templates/archive.md create mode 100644 content/templates/feeds/index.md create mode 100644 content/templates/feeds/rss_feed.png create mode 100644 content/templates/overview.md create mode 100644 content/templates/pages-sections.md create mode 100644 content/templates/pagination.md create mode 100644 content/templates/robots.md create mode 100644 content/templates/sitemap.md create mode 100644 content/templates/taxonomies.md create mode 100644 content/themes/_index.md create mode 100644 content/themes/creating-a-theme.md create mode 100644 content/themes/extending-a-theme.md create mode 100644 content/themes/installing-and-using-themes.md create mode 100644 content/themes/overview.md create mode 100644 sass/_search.scss create mode 100644 sass/_variables.scss create mode 100644 sass/fabric-icons-inline.scss create mode 100644 sass/main.scss create mode 100644 static/js.js create mode 100644 templates/anchor-link.html create mode 100644 templates/index.html create mode 100644 templates/page.html 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 <!-- more --> 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: +`Continue Reading`. 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: . +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 done. When a section is drafted it's descendants like pages, subsections and assets will not be processed unless the `--drafts` flag is passed. Note that even pages that don't have a `draft` status will not be processed if one of their parent sections is drafted. + +## Front matter + +The `_index.md` file within a directory defines the content and metadata for that section. To set +the metadata, add front matter to the file. + +The TOML front matter is a set of metadata embedded in a file at the beginning of the file enclosed by triple pluses (`+++`). + +After the closing `+++`, you can add content, which will be parsed as Markdown and made available +to your templates through the `section.content` variable. + +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 `_index.md` with all the available variables. The values provided below are the +default values. + + +```toml +title = "" + +description = "" + +# A draft section is only loaded if the `--drafts` flag is passed to `zola build`, `zola serve` or `zola check`. +draft = false + +# Used to sort pages by "date", "weight" or "none". See below for more information. +sort_by = "none" + +# Used by the parent section to order its subsections. +# Lower values have higher priority. +weight = 0 + +# Template to use to render this section page. +template = "section.html" + +# The given template is applied to ALL pages below the section, recursively. +# If you have several nested sections, each with a page_template set, the page +# will always use the closest to itself. +# However, a page's own `template` variable will always have priority. +# Not set by default. +page_template = + +# This sets the number of pages to be displayed per paginated page. +# No pagination will happen if this isn't set or if the value is 0. +paginate_by = 0 + +# If set, this will be the path used by the paginated page. The page number will be appended after this path. +# The default is page/1. +paginate_path = "page" + +# This determines whether to insert a link for each header like the ones you can see on this site if you hover over +# a header. +# The default template can be overridden by creating an `anchor-link.html` file in the `templates` directory. +# This value can be "left", "right" or "none". +insert_anchor_links = "none" + +# If set to "true", the section pages will be in the search index. This is only used if +# `build_search_index` is set to "true" in the Zola configuration file. +in_search_index = true + +# If set to "true", the section homepage is rendered. +# Useful when the section is used to organize pages (not used directly). +render = true + +# This determines whether to redirect when a user lands on the section. Defaults to not being set. +# Useful for the same reason as `render` but when you don't want a 404 when +# landing on the root section page. +# Example: redirect_to = "documentation/content/overview" +redirect_to = + +# If set to "true", the section will pass its pages on to the parent section. Defaults to `false`. +# Useful when the section shouldn't split up the parent section, like +# sections for each year under a posts section. +transparent = false + +# 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 = [] + +# If set to "true", a feed file will be generated for this section at the +# section's root path. This is independent of the site-wide variable of the same +# name. The section feed will only include posts from that respective feed, and +# not from any other sections, including sub-sections under that section. +generate_feed = false + +# Your own data. +[extra] +``` + +Keep in mind that any configuration options apply only to the direct pages, not to the subsections' pages. + +## Pagination + +To enable pagination for a section's pages, set `paginate_by` to a positive number. See +[pagination template documentation](@/templates/pagination.md) for more information +on what variables are available in the template. + +You can also change the pagination path (the word displayed while paginated in the URL, like `page/1`) +by setting the `paginate_path` variable, which defaults to `page`. + +## Sorting +It is very common for Zola templates to iterate over pages or sections +to display all pages/sections in a given directory. Consider a very simple +example: a `blog` directory with three files: `blog/Post_1.md`, +`blog/Post_2.md` and `blog/Post_3.md`. To iterate over these posts and +create a list of links to the posts, a simple template might look like this: + +```j2 +{% for post in section.pages %} +

{{ post.title }}

+{% endfor %} +``` + +This would iterate over the posts in the order specified +by the `sort_by` variable set in the `_index.md` page for the corresponding +section. The `sort_by` variable can be given one of three values: `date`, +`weight` or `none`. If `sort_by` is not set, the pages will be +sorted in the `none` order, which is not intended for sorted content. + +Any page that is missing the data it needs to be sorted will be ignored and +won't be rendered. For example, if a page is missing the date variable and its +section sets `sort_by = "date"`, then that page will be ignored. +The terminal will warn you if this occurs. + +If several pages have the same date/weight/order, their permalink will be used +to break the tie based on alphabetical order. + +## Sorting pages +The `sort_by` front-matter variable can have the following values: + +### `date` +This will sort all pages by their `date` field, from the most recent (at the +top of the list) to the oldest (at the bottom of the list). Each page will +get `page.earlier` and `page.later` variables that contain the pages with +earlier and later dates, respectively. + +### `weight` +This will be sort all pages by their `weight` field, from lightest weight +(at the top of the list) to heaviest (at the bottom of the list). Each +page gets `page.lighter` and `page.heavier` variables that contain the +pages with lighter and heavier weights, respectively. + +### Reversed sorting +When iterating through pages, you may wish to use the Tera `reverse` filter, +which reverses the order of the pages. For example, after using the `reverse` filter, +pages sorted by weight will be sorted from lightest (at the top) to heaviest +(at the bottom); pages sorted by date will be sorted from oldest (at the top) +to newest (at the bottom). + +`reverse` has no effect on `page.later`/`page.earlier` or `page.heavier`/`page.lighter`. + +If the section is paginated the `paginate_reversed=true` in the front matter of the relevant section should be set instead of using the filter. + +## Sorting subsections +Sorting sections is a bit less flexible: sections can only be sorted by `weight`, +and do not have variables that point to the heavier/lighter sections. + +By default, the lightest (lowest `weight`) subsections will be at +the top of the list and the heaviest (highest `weight`) will be at the bottom; +the `reverse` filter reverses this order. + +**Note**: Unlike pages, permalinks will **not** be used to break ties between +equally weighted sections. Thus, if the `weight` variable for your section is not set (or if it +is set in a way that produces ties), then your sections will be sorted in +**random** order. Moreover, that order is determined at build time and will +change with each site rebuild. Thus, if there is any chance that you will +iterate over your sections, you should always assign them a weight. diff --git a/content/content/shortcodes.md b/content/content/shortcodes.md new file mode 100644 index 0000000..af90a02 --- /dev/null +++ b/content/content/shortcodes.md @@ -0,0 +1,243 @@ ++++ +title = "Shortcodes" +weight = 40 ++++ + +Zola borrows the concept of [shortcodes](https://codex.wordpress.org/Shortcode_API) from WordPress. +In our case, a shortcode corresponds to a template defined in the `templates/shortcodes` directory or +a built-in one that can be used in a Markdown file. If you want to use something similar to shortcodes in your templates, +try [Tera macros](https://tera.netlify.com/docs#macros). + +Broadly speaking, Zola's shortcodes cover two distinct use cases: + +* Inject more complex HTML: Markdown is good for writing, but it isn't great when you need add inline HTML or styling. +* Ease repetitive data based tasks: when you have [external data](@/templates/overview.md#load-data) that you + want to display in your page's body. + +The latter may also be solved by writing HTML, however Zola allows the use of Markdown based shortcodes which end in `.md` +rather than `.html`. This may be particularly useful if you want to include headings generated by the shortcode in the +[table of contents](@/content/table-of-contents.md). + +## Writing a shortcode +Let's write a shortcode to embed YouTube videos as an example. +In a file called `youtube.html` in the `templates/shortcodes` directory, paste the +following: + +```jinja2 +
+ +
+``` + +This template is very straightforward: an iframe pointing to the YouTube embed URL wrapped in a `
`. +In terms of input, this shortcode expects at least one variable: `id`. Because the other variables +are in an `if` statement, they are optional. + +That's it. Zola will now recognise this template as a shortcode named `youtube` (the filename minus the `.html` extension). + +The Markdown renderer will wrap an inline HTML node such as `` or `` into a paragraph. +If you want to disable this behaviour, wrap your shortcode in a `
`. + +A Markdown based shortcode in turn will be treated as if what it returned was part of the page's body. If we create +`books.md` in `templates/shortcodes` for example: + +```jinja2 +{% set data = load_data(path=path) -%} +{% for book in data.books %} +### {{ book.title }} + +{{ book.description | safe }} +{% endfor %} +``` + +This will create a shortcode `books` with the argument `path` pointing to a `.toml` file where it loads lists of books with +titles and descriptions. They will flow with the rest of the document in which `books` is called. + +Shortcodes are rendered before the page's Markdown is parsed so they don't have access to the page's table of contents. +Because of that, you also cannot use the `get_page`/`get_section`/`get_taxonomy` global functions. It might work while +running `zola serve` because it has been loaded but it will fail during `zola build`. + +## Using shortcodes + +There are two kinds of shortcodes: + +- ones that do not take a body, such as the YouTube example above +- ones that do, such as one that styles a quote + +In both cases, the arguments must be named and they will all be passed to the template. + +Lastly, a shortcode name (and thus the corresponding `.html` file) as well as the argument names +can only contain numbers, letters and underscores, or in Regex terms `[0-9A-Za-z_]`. +Although theoretically an argument name could be a number, it will not be possible to use such an argument in the template. + +Argument values can be of one of five types: + +- string: surrounded by double quotes, single quotes or backticks +- bool: `true` or `false` +- float: a number with a decimal point (e.g., 1.2) +- integer: a whole number or its negative counterpart (e.g., 3) +- array: an array of any kind of value, except arrays + +Malformed values will be silently ignored. + +Both types of shortcode will also get either a `page` or `section` variable depending on where they were used +and a `config` variable. These values will overwrite any arguments passed to a shortcode so these variable names +should not be used as argument names in shortcodes. + +### Shortcodes without body + +Simply call the shortcode as if it was a Tera function in a variable block. All the examples below are valid +calls of the YouTube shortcode. + +```md +Here is a YouTube video: + +{{/* youtube(id="dQw4w9WgXcQ") */}} + +{{/* youtube(id="dQw4w9WgXcQ", autoplay=true) */}} + +An inline {{/* youtube(id="dQw4w9WgXcQ", autoplay=true, class="youtube") */}} shortcode +``` + +Note that if you want to have some content that looks like a shortcode but not have Zola try to render it, +you will need to escape it by using `{{/*` and `*/}}` instead of `{{` and `}}`. + +### Shortcodes with body +Let's imagine that we have the following shortcode `quote.html` template: + +```jinja2 +
+ {{ body }}
+ -- {{ author}} +
+``` + +We could use it in our Markdown file like so: + +```md +As someone said: + +{%/* quote(author="Vincent") */%} +A quote +{%/* end */%} +``` + +The body of the shortcode will be automatically passed down to the rendering context as the `body` variable and needs +to be on a new line. + +If you want to have some content that looks like a shortcode but not have Zola try to render it, +you will need to escape it by using `{%/*` and `*/%}` instead of `{%` and `%}`. You won't need to escape +anything else until the closing tag. + +### Invocation Count + +Every shortcode context is passed in a variable named `nth` that tracks how many times a particular shortcode has +been invoked in a Markdown file. Given a shortcode `true_statement.html` template: + +```jinja2 +

{{ value }} is equal to {{ nth }}.

+``` + +It could be used in our Markdown as follows: + +```md +{{/* true_statement(value=1) */}} +{{/* true_statement(value=2) */}} +``` + +This is useful when implementing custom markup for features such as sidenotes or end notes. + +## Built-in shortcodes + +Zola comes with a few built-in shortcodes. If you want to override a default shortcode template, +simply place a `{shortcode_name}.html` file in the `templates/shortcodes` directory and Zola will +use that instead. + +### YouTube +Embed a responsive player for a YouTube video. + +The arguments are: + +- `id`: the video id (mandatory) +- `class`: a class to add to the `
` surrounding the iframe +- `autoplay`: when set to "true", the video autoplays on load + +Usage example: + +```md +{{/* youtube(id="dQw4w9WgXcQ") */}} + +{{/* youtube(id="dQw4w9WgXcQ", autoplay=true) */}} + +{{/* youtube(id="dQw4w9WgXcQ", autoplay=true, class="youtube") */}} +``` + +Result example: + +{{ youtube(id="dQw4w9WgXcQ") }} + +### Vimeo +Embed a player for a Vimeo video. + +The arguments are: + +- `id`: the video id (mandatory) +- `class`: a class to add to the `
` surrounding the iframe + +Usage example: + +```md +{{/* vimeo(id="124313553") */}} + +{{/* vimeo(id="124313553", class="vimeo") */}} +``` + +Result example: + +{{ vimeo(id="124313553") }} + +### Streamable +Embed a player for a Streamable video. + +The arguments are: + +- `id`: the video id (mandatory) +- `class`: a class to add to the `
` surrounding the iframe + +Usage example: + +```md +{{/* streamable(id="92ok4") */}} + +{{/* streamable(id="92ok4", class="streamble") */}} +``` + +Result example: + +{{ streamable(id="92ok4") }} + +### Gist +Embed a [Github gist](https://gist.github.com). + +The arguments are: + +- `url`: the url to the gist (mandatory) +- `file`: by default, the shortcode will pull every file from the URL unless a specific filename is requested +- `class`: a class to add to the `
` surrounding the iframe + +Usage example: + +```md +{{/* gist(url="https://gist.github.com/Keats/e5fb6aad409f28721c0ba14161644c57") */}} + +{{/* gist(url="https://gist.github.com/Keats/e5fb6aad409f28721c0ba14161644c57", class="gist") */}} +``` + +Result example: + +{{ gist(url="https://gist.github.com/Keats/e5fb6aad409f28721c0ba14161644c57") }} diff --git a/content/content/syntax-highlighting.md b/content/content/syntax-highlighting.md new file mode 100644 index 0000000..b4f65da --- /dev/null +++ b/content/content/syntax-highlighting.md @@ -0,0 +1,171 @@ ++++ +title = "Syntax Highlighting" +weight = 80 ++++ + +Zola comes with built-in syntax highlighting but you first +need to enable it in the configuration + +Once this is done, Zola will automatically highlight all code blocks +in your content. A code block in Markdown looks like the following: + +````md + +```rust +let highlight = true; +``` + +```` + +You can replace `rust` with another language or not put anything to get the text +interpreted as plain text. + +Here is a full list of supported languages and their short names: + +``` +- ActionScript -> ["as"] +- Advanced CSV -> ["csv", "tsv"] +- AppleScript -> ["applescript", "script editor"] +- ASP -> ["asa"] +- Assembly x86 (NASM) -> ["asm", "inc", "nasm"] +- AWK -> ["awk"] +- Batch File -> ["bat", "cmd"] +- BibTeX -> ["bib"] +- Bourne Again Shell (bash) -> [".bash_aliases", ".bash_completions", ".bash_functions", ".bash_login", ".bash_logout", ".bash_profile", ".bash_variables", ".bashrc", ".ebuild", ".eclass", ".profile", ".textmate_init", ".zlogin", ".zlogout", ".zprofile", ".zshenv", ".zshrc", "PKGBUILD", "ash", "bash", "sh", "zsh"] +- C -> ["c", "h"] +- C# -> ["cs", "csx"] +- C++ -> ["C", "c++", "cc", "cp", "cpp", "cxx", "h", "h++", "hh", "hpp", "hxx", "inl", "ipp"] +- ClojureC -> ["boot", "clj", "cljc", "cljs", "cljx"] +- CMake -> ["CMakeLists.txt", "cmake"] +- CMake C Header -> ["h.in"] +- CMake C++ Header -> ["h++.in", "hh.in", "hpp.in", "hxx.in"] +- CMakeCache -> ["CMakeCache.txt"] +- Crystal -> ["cr"] +- CSS -> ["css", "css.erb", "css.liquid"] +- D -> ["d", "di"] +- Dart -> ["dart"] +- Diff -> ["diff", "patch"] +- Dockerfile -> ["Dockerfile", "dockerfile"] +- EDN -> ["edn"] +- Elixir -> ["ex", "exs"] +- Elm -> ["elm"] +- Erlang -> ["Emakefile", "emakefile", "erl", "escript", "hrl"] +- F# -> ["fs", "fsi", "fsx"] +- Fortran (Fixed Form) -> ["F", "F77", "FOR", "FPP", "f", "f77", "for", "fpp"] +- Fortran (Modern) -> ["F03", "F08", "F90", "F95", "f03", "f08", "f90", "f95"] +- Fortran Namelist -> ["namelist"] +- Friendly Interactive Shell (fish) -> ["fish"] +- GDScript (Godot Engine) -> ["gd"] +- Generic Config -> [".dircolors", ".gitattributes", ".gitignore", ".gitmodules", ".inputrc", "Doxyfile", "cfg", "conf", "config", "dircolors", "gitattributes", "gitignore", "gitmodules", "ini", "inputrc", "mak", "mk", "pro"] +- Git Attributes -> [".gitattributes", "attributes", "gitattributes"] +- Git Commit -> ["COMMIT_EDITMSG", "MERGE_MSG", "TAG_EDITMSG"] +- Git Config -> [".gitconfig", ".gitmodules", "gitconfig"] +- Git Ignore -> [".gitignore", "exclude", "gitignore"] +- Git Link -> [".git"] +- Git Log -> ["gitlog"] +- Git Mailmap -> [".mailmap", "mailmap"] +- Git Rebase Todo -> ["git-rebase-todo"] +- GLSL -> ["comp", "frag", "fs", "fsh", "fshader", "geom", "glsl", "gs", "gsh", "gshader", "tesc", "tese", "vert", "vs", "vsh", "vshader"] +- Go -> ["go"] +- GraphQL -> ["gql", "graphql", "graphqls"] +- Graphviz (DOT) -> ["DOT", "dot", "gv"] +- Groovy -> ["Jenkinsfile", "gradle", "groovy", "gvy"] +- Handlebars -> ["handlebars", "handlebars.html", "hbr", "hbrs", "hbs", "hdbs", "hjs", "mu", "mustache", "rac", "stache", "template", "tmpl"] +- Haskell -> ["hs"] +- HTML -> ["htm", "html", "shtml", "xhtml"] +- HTML (ASP) -> ["asp"] +- HTML (EEx) -> ["html.eex", "html.leex"] +- HTML (Erlang) -> ["yaws"] +- HTML (Jinja2) -> ["htm.j2", "html.j2", "xhtml.j2", "xml.j2"] +- HTML (Rails) -> ["erb", "html.erb", "rails", "rhtml"] +- HTML (Tcl) -> ["adp"] +- Java -> ["bsh", "java"] +- Java Properties -> ["properties"] +- Java Server Page (JSP) -> ["jsp"] +- JavaScript -> ["htc", "js"] +- JavaScript (Rails) -> ["js.erb"] +- Jinja2 -> ["j2", "jinja", "jinja2"] +- JSON -> ["Pipfile.lock", "ipynb", "json", "sublime-build", "sublime-color-scheme", "sublime-commands", "sublime-completions", "sublime-keymap", "sublime-macro", "sublime-menu", "sublime-mousemap", "sublime-project", "sublime-settings", "sublime-theme"] +- Julia -> ["jl"] +- Kotlin -> ["kt", "kts"] +- LaTeX -> ["ltx", "tex"] +- Less -> ["css.less", "less"] +- Linker Script -> ["ld"] +- Lisp -> ["cl", "clisp", "el", "fasl", "l", "lisp", "lsp", "mud", "scm", "ss"] +- Literate Haskell -> ["lhs"] +- lrc -> ["lrc", "lyric"] +- Lua -> ["lua"] +- Makefile -> ["GNUmakefile", "Makefile", "Makefile.am", "Makefile.in", "OCamlMakefile", "mak", "make", "makefile", "makefile.am", "makefile.in", "mk"] +- Markdown -> ["markdn", "markdown", "md", "mdown"] +- MATLAB -> ["matlab"] +- MiniZinc (MZN) -> ["dzn", "mzn"] +- NAnt Build File -> ["build"] +- Nim -> ["nim", "nims"] +- Nix -> ["nix"] +- Objective-C -> ["h", "m"] +- Objective-C++ -> ["M", "h", "mm"] +- OCaml -> ["ml", "mli"] +- OCamllex -> ["mll"] +- OCamlyacc -> ["mly"] +- Pascal -> ["dpr", "p", "pas"] +- Perl -> ["pc", "pl", "pm", "pmc", "pod", "t"] +- PHP -> ["php", "php3", "php4", "php5", "php7", "phps", "phpt", "phtml"] +- Plain Text -> ["txt"] +- PowerShell -> ["ps1", "psd1", "psm1"] +- PureScript -> ["purs"] +- Python -> ["SConscript", "SConstruct", "Sconstruct", "Snakefile", "bazel", "bzl", "cpy", "gyp", "gypi", "pxd", "pxd.in", "pxi", "pxi.in", "py", "py3", "pyi", "pyw", "pyx", "pyx.in", "rpy", "sconstruct", "vpy", "wscript"] +- R -> ["R", "Rprofile", "r"] +- Racket -> ["rkt"] +- Rd (R Documentation) -> ["rd"] +- Reason -> ["re", "rei"] +- Regular Expression -> ["re"] +- Regular Expressions (Elixir) -> ["ex.re"] +- reStructuredText -> ["rest", "rst"] +- Ruby -> ["Appfile", "Appraisals", "Berksfile", "Brewfile", "Cheffile", "Deliverfile", "Fastfile", "Gemfile", "Guardfile", "Podfile", "Rakefile", "Rantfile", "Scanfile", "Snapfile", "Thorfile", "Vagrantfile", "capfile", "cgi", "config.ru", "fcgi", "gemspec", "irbrc", "jbuilder", "podspec", "prawn", "rabl", "rake", "rb", "rbx", "rjs", "ruby.rail", "simplecov", "thor"] +- Ruby Haml -> ["haml", "sass"] +- Ruby on Rails -> ["builder", "rxml"] +- Rust -> ["rs"] +- Sass -> ["sass"] +- Scala -> ["sbt", "sc", "scala"] +- SCSS -> ["scss"] +- SQL -> ["ddl", "dml", "sql"] +- SQL (Rails) -> ["erbsql", "sql.erb"] +- srt -> ["srt", "subrip"] +- Stylus -> ["styl", "stylus"] +- SWI-Prolog -> ["pro"] +- Swift -> ["swift"] +- Tcl -> ["tcl"] +- TeX -> ["cls", "sty"] +- Textile -> ["textile"] +- TOML -> ["Cargo.lock", "Gopkg.lock", "Pipfile", "tml", "toml"] +- TypeScript -> ["ts"] +- TypeScriptReact -> ["tsx"] +- VimL -> ["vim"] +- XML -> ["dtml", "opml", "rng", "rss", "svg", "tld", "xml", "xsd", "xslt"] +- YAML -> ["sublime-syntax", "yaml", "yml"] +``` + +Note: due to some issues with the JavaScript syntax, the TypeScript syntax will be used instead. +If + +If you want to highlight a language not on this list, please open an issue or a pull request on the [Zola repo](https://github.com/getzola/zola). +Alternatively, the `extra_syntaxes` configuration option can be used to add additional syntax files. + +If your site source is laid out as follows: + +``` +. +├── config.toml +├── content/ +│   └── ... +├── static/ +│   └── ... +├── syntaxes/ +│   ├── Sublime-Language1/ +│   │   └── lang1.sublime-syntax +│   └── lang2.sublime-syntax +└── templates/ + └── ... +``` + +you would set your `extra_syntaxes` to `["syntaxes", "syntaxes/Sublime-Language1"]` to load `lang1.sublime-syntax` and `lang2.sublime-syntax`. diff --git a/content/content/table-of-contents.md b/content/content/table-of-contents.md new file mode 100644 index 0000000..d541d86 --- /dev/null +++ b/content/content/table-of-contents.md @@ -0,0 +1,36 @@ ++++ +title = "Table of Contents" +weight = 60 ++++ + +Each page/section will automatically generate a table of contents for itself based on the headers generated with markdown. + +It is available in the template through the `page.toc` or `section.toc` variable. +You can view the [template variables](@/templates/pages-sections.md#table-of-contents) +documentation for information on its structure. + +Here is an example of using that field to render a two-level table of contents: + +```jinja2 + +``` + +While headers are neatly ordered in this example, it will work just as well with disjoint headers. + +Note that all existing HTML tags from the title will NOT be present in the table of contents to +avoid various issues. diff --git a/content/content/taxonomies.md b/content/content/taxonomies.md new file mode 100644 index 0000000..39e78a0 --- /dev/null +++ b/content/content/taxonomies.md @@ -0,0 +1,138 @@ ++++ +title = "Taxonomies" +weight = 90 ++++ + +Zola has built-in support for taxonomies. Taxonomies are a way for users to group content according to user-defined categories. + +## Definitions + +- Taxonomy: A category that can be used to group content +- Term: A specific group within a taxonomy +- Value: A piece of content that can be associated with a term + +## Example: a movie website + +Imagine that you want to make a website to display information about various movies. In that case you could use the following taxonomies: + +- Director +- Genres +- Awards +- Release year + +Then at build time Zola can create pages for each taxonomy listing all of the known terms as well as pages for each term in a taxonomy, listing all of the pieces of content associated with that term. + +Imagine again we have the following movies: +``` +- Shape of water <--- Value + - Director <--- Taxonomy + - Guillermo Del Toro <--- Term + - Genres <--- Taxonomy + - Thriller <--- Term + - Drama <--- Term + - Awards <--- Taxonomy + - Golden globe <--- Term + - Academy award <--- Term + - BAFTA <--- Term + - Release year <--- Taxonomy + - 2017 <--- Term + +- The Room: <--- Value + - Director <--- Taxonomy + - Tommy Wiseau <--- Term + - Genres <--- Taxonomy + - Romance <--- Term + - Drama <--- Term + - Release Year <--- Taxonomy + - 2003 <--- Term + +- Bright <--- Value + - Director <--- Taxonomy + - David Ayer <--- Term + - Genres <--- Taxonomy + - Fantasy <--- Term + - Action <--- Term + - Awards <--- Taxonomy + - California on Location Awards <--- Term + - Release Year <--- Taxonomy + - 2017 <--- Term +``` + +In this example the page for `Release year` would include links to pages for both 2003 and 2017, where the page for 2017 would list both Shape of Water and Bright. + +## Configuration + +A taxonomy has five variables: + +- `name`: a required string that will be used in the URLs, usually the plural version (i.e., tags, categories, etc.) +- `paginate_by`: if this is set to a number, each term page will be paginated by this much. +- `paginate_path`: if set, this path will be used by the paginated page and the page number will be appended after it. +For example the default would be page/1. +- `feed`: if set to `true`, a feed (atom by default) will be generated for each term. +- `lang`: only set this if you are making a multilingual site and want to indicate which language this taxonomy is for + +Insert into the configuration file (config.toml): + +⚠️ Place the taxonomies key in the main section and not in the `[extra]` section + +**Example 1:** (one language) + +```toml +taxonomies = [ + { name = "director", feed = true}, + { name = "genres", feed = true}, + { name = "awards", feed = true}, + { name = "release-year", feed = true}, +] +``` + +**Example 2:** (multilingual site) + +```toml +taxonomies = [ + {name = "director", feed = true, lang = "fr"}, + {name = "director", feed = true, lang = "eo"}, + {name = "director", feed = true, lang = "en"}, + {name = "genres", feed = true, lang = "fr"}, + {name = "genres", feed = true, lang = "eo"}, + {name = "genres", feed = true, lang = "en"}, + {name = "awards", feed = true, lang = "fr"}, + {name = "awards", feed = true, lang = "eo"}, + {name = "awards", feed = true, lang = "en"}, + {name = "release-year", feed = true, lang = "fr"}, + {name = "release-year", feed = true, lang = "eo"}, + {name = "release-year", feed = true, lang = "en"}, +] +``` + +## Using taxonomies + +Once the configuration is done, you can then set taxonomies in your content and Zola will pick them up: + +**Example:** + +```toml ++++ +title = "Shape of water" +date = 2019-08-15 # date of the post, not the movie +[taxonomies] +director=["Guillermo Del Toro"] +genres=["Thriller","Drama"] +awards=["Golden Globe", "Academy award", "BAFTA"] +release-year = ["2017"] ++++ +``` + +## Output paths + +In a similar manner to how section and pages calculate their output path: +- the taxonomy name is never slugified +- the taxonomy term (e.g. as specific tag) is slugified when `slugify.taxonomies` is enabled (`"on"`, the default) in the configuration + +The taxonomy pages are then available at the following paths: + +```plain +$BASE_URL/$NAME/ (taxonomy) +$BASE_URL/$NAME/$SLUG (taxonomy entry) +``` +Note that taxonomies are case insensitive so terms that have the same slug will get merged, e.g. sections and pages containing the tag "example" will be shown in the same taxonomy page as ones containing "Example" diff --git a/content/deployment/_index.md b/content/deployment/_index.md new file mode 100644 index 0000000..c5f27ac --- /dev/null +++ b/content/deployment/_index.md @@ -0,0 +1,6 @@ ++++ +title = "Deployment" +weight = 5 +sort_by = "weight" ++++ + diff --git a/content/deployment/github-pages.md b/content/deployment/github-pages.md new file mode 100644 index 0000000..437f9d3 --- /dev/null +++ b/content/deployment/github-pages.md @@ -0,0 +1,120 @@ ++++ +title = "GitHub Pages" +weight = 30 ++++ + +By default, GitHub Pages uses Jekyll (a ruby based static site generator), +but you can also publish any generated files provided you have an `index.html` file in the root of a branch called +`gh-pages` or `master`. In addition you can publish from a `docs` directory in your repository. That branch name can +also be manually changed in the settings of a repository. + +We can use any continuous integration (CI) server to build and deploy our site. For example: + + * [Github Actions](#github-actions) + * [Travis CI](#travis-ci) + +## Github Actions + +Using *Github Actions* for the deployment of your Zola-Page on Github-Pages is pretty easy. You basically need three things: + +1. A *Personal access token* to give the *Github Action* the permission to push into your repository. +2. Create the *Github Action*. +3. Check the *Github Pages* section in repository settings. + +Let's start with the token. + +For creating the token either click on [here](https://github.com/settings/tokens) or go to Settings > Developer Settings > Personal access tokens. Under the *Select Scopes* section, give it *repo* permissions and click *Generate token*. Then copy the token, navigate to your repository and add in the Settings tab the *Secret* `TOKEN` and paste your token in it. + +Next we need to create the *Github Action*. Here we can make use of the [zola-deploy-action](https://github.com/shalzz/zola-deploy-action). Go to the *Actions* tab of your repository, click on *set up a workflow yourself* to get a blank workflow file. Copy the following script into it and commit it afterwards. + +```yaml +# On every push this script is executed +on: push +name: Build and deploy GH Pages +jobs: + build: + name: shalzz/zola-deploy-action + runs-on: ubuntu-latest + steps: + # Checkout + - uses: actions/checkout@master + # Build & deploy + - name: shalzz/zola-deploy-action + uses: shalzz/zola-deploy-action@v0.12.0 + env: + # Target branch + PAGES_BRANCH: gh-pages + # Provide personal access token + TOKEN: ${{ secrets.TOKEN }} +``` + +This script is pretty simple, because the [zola-deploy-action](https://github.com/shalzz/zola-deploy-action) is doing everything for you. You just need to provide some details. For more configuration options check out the [README](https://github.com/shalzz/zola-deploy-action/blob/master/README.md). + +By commiting the action your first build is triggered. Wait until it's finished, then you should see in your repository a new branch *gh-pages* with the compiled *Zola* page in it. + +Finally we need to check the *Github Pages* section of the repository settings. Click on the *Settings* tab and scroll down to the *Github Pages* section. Check if the source is set to *gh-pages* branch and the directory is */ (root)*. You should also see your *Github Pages* link. + +There you can also configure a *custom domain* and *Enforce HTTPS* mode. Before configuring a *custom domains*, please check out [this](https://github.com/shalzz/zola-deploy-action/blob/master/README.md#custom-domain). + +##