From e8041c74df60b97e72d0ab68a3f047498214d180 Mon Sep 17 00:00:00 2001 From: "Elf M. Sternberg" Date: Wed, 27 Apr 2022 07:24:24 -0700 Subject: [PATCH] Added a lot more content to the Zola page. Saving because editing is coming. --- content/docs/zola/_index.md | 106 ++++++++++++++++++++++++++++++++++-- 1 file changed, 100 insertions(+), 6 deletions(-) diff --git a/content/docs/zola/_index.md b/content/docs/zola/_index.md index cd92f55..393db8f 100644 --- a/content/docs/zola/_index.md +++ b/content/docs/zola/_index.md @@ -7,10 +7,11 @@ template = "docs/section.html" sort_by = "weight" weight = 4 draft = false +[taxonomies] +documentation=["Reference"] +categories=["Web Development", "Static Site Generation", "Zola"] +++ -# Zola - [Zola](https://getzola.org) is a static site generator written in [Rust](../rust). It builds an entire web page out of a structured markdown collection and a collection of HTML templates. The templating language is called @@ -32,7 +33,7 @@ The following files and folders define a basic Zola project - `config.toml`: A configuration file in the [TOML](https://toml.io/en/) configuration language. Can contain a lot of information that will be made available to *all* pages in the system. -- `content/`: The structured content folder. +- `content/`: The structured content folder. All your "living" stuff goes here. - `sass/`: [Sass](../sass) is a CSS preprocessor language that makes CSS easier. - `static/`: Static content such as images, fonts, and Javascript - `templates`: The HTML templates (and includes, etc) that define the website's @@ -320,6 +321,24 @@ some optional content. The TOML header _may_ specify which template to use to render the section info, otherwise Zola falls back to the default at `./templates/section.html`. +The arguments that con be placed into the TOML header of a the `_index.md` file are: + +- `title`: a string +- `description`: a string +- `draft`: `true`/`false` if this section should be included in builds +- `sort_by`: Sorting function to use: `date`, `title`, `weight`, or `none` +- `weight`: Used to provide subsection weight to a parent section +- `template`: The template to render this section. Defaults to `./templates/section.html` +- `page_template`: The default template to render pages in this section. Pages with this field specified overide this setting +- `paginate_by`: Number of pages to paginate by. Set to `0` for no pagination +- `paginate_path`: The prefix for paginations. Default to "page" +- `paginate_reversed`: boolean +- `insert_anchor_links`: One of `left`, `right`, or `none`. Specifies whether an anchor-link should be provided for every header item. Probably overridable by the template. +- `in_search_index`: Include this section in the search index. Only matters if search is enabled +- `transparent`: `true`/`false`, specifies if this section should be inherited by the parent +- `aliases`: An array of paths to redirect to this folder +- `[extra]`: Your extra data block + The context for a section page contains the following fields, which will be available to the template: @@ -342,6 +361,81 @@ available to the template: ### Pages A page is _either_ a markdown file within the same folder as its section, or it -is in `index.md` (note the lack of prefix underscore!) file in a separate -folder. The latter syntax is preferred if the file has associated assets, such -as javascript or images. +is in a subfolder with a file named `index.md` (note the lack of prefix +underscore!). The latter syntax is preferred if the file has associated assets, +such as JavaScript or images, that you want to load alongside the content within +the markdown page. + +The following items can appear in the TOML header of a page: + +- `title`: The title of this page. +- `description`: A description of this page +- `date`: Date this page was published +- `updated`: Date this page was updated +- `weight`: A number, used for sorting +- `draft`: Boolean. Specifies if this page should be rendered at build time +- `slug`: String. The slug Zola should use when generating the URL +- `path`: A manually specified absolute path to this content +- `aliases`: An array of former urls that lead here, to redirect people here +- `in_search_index`: If set to false and search is enabled, this page will not be included +- `template`: The template used to render this page. Defaults to `./templates/page.html` +- `[taxonomies]`: The taxonomies for this page +- `[extra]`: Your own extra data + +Pages have the following information in their context: + +- `content`: The markdown content from the page's file +- `title`: The title, if present in the TOML block +- `description`: The description +- `date`: The date this file was added +- `updated`: The date this file was last updated +- `slug`: The slug name of this file +- `path`: The path to this file +- `draft`: true/false, will tell Zola not to include this file during builds +- `components`: The path, split by '/' +- `permalink`: The URL Zola generates for this file +- `summary`: A provided string +- `taxonomies`: The taxonomies list, if any +- `extra`: The extras block +- `toc`: An array of `Header` objects as derived from the Markdown +- `word_count`: A naive word count +- `reading_time`: A primitive reading time, in minutes +- `earlier`: The content of the previous page, if the section header entry 'sort_by' is set to 'date.' +- `later`: The content of the next page +- `heavier`: The content of the previous page, if the section header entry 'sort_by' is set to 'weight' +- `lighter`: The content of the next page +- `year`: Year as a number. +- `month`: Month as a number. +- `day`: Day as a number. +- `assets`: An array of assets available to this page. +- `ancestors`: An array of parent paths, with the root being the last one. + +### Pagination + +Pagination is provided by a `Paginator` object available to the section page. +The paginator will automatically generate multiple pages for the section, and +will provide links to earlier/later pages within the collection. + +### Shortcodes + +Shortcodes are chunks of HTML or Markdown that you can store in the +`./templates/shortcodes` folder. Shortcodes will be processed for variables, and +Zola will create a corresponding named hook that will take those variables as +named parameters, much like a Tera function, and return the processed HTML. + +### Internal links + +The relationship between a Markdown file and its generated content is +deterministic, but not always readily apparent. If you want to link to content +in another markdown file, you can use the link syntax `[my +link](@/pages/about.md#example-code)`, which will generate a URL to the generated +copy of that page, and will provide a header link to the header entitled +"Example Code". + +### Taxonomies + +Taxonomies are a primitive organizational mechanism. You can create a list of +taxonomies in the `config.toml` file, and then provide entries for those +taxonomies in pages; those pages will then be included in the `taxonomies` +collection. The Taxonomy pages are generated with list of various taxonomies +and the collections of pages that relate to the taxonomy.