Added a lot more content to the Zola page. Saving because editing is coming.

This commit is contained in:
Elf M. Sternberg 2022-04-27 07:24:24 -07:00
parent 8ae58c95a8
commit e8041c74df
1 changed files with 100 additions and 6 deletions

View File

@ -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.