Posted on 2023-07-08

I am currently learning how to build this site with Zola, their tutorials are decent, but I think they aren't clear enough about preisely the system image.

zola breaks sites into content, layout, and styling. content is the text, layout is the html, styling is the css

content is broken into sections and pages. each section is a container for pages. each section has an "_index.md" header that can establish variables. each page is another markdown file that again has a header of variables and a body of text. the variable header is enclosesed in "+++"-es.

layout is broken into templates. templates can have place-holders which are then filled by other templates that "extend" them. they can also access variables stored in the relavant mark down files as well as certain automatically generated values

styling is either normal css or sass.

building

$zola serve will build and host locally
$zola build will build and places the result in the directory called public by default

since im using neocities I can then go to the commandline and say $ neocities push public and it will recursively upload the directory

taxonomies

you can also have user defined categories called Taxonomies. these taxonomies have terms and values. terms are the pieces of metadata inside the taxonomy, for example colors, the values are objects associated with each piece of metadata.

We place the configuration of a taxonomy in the config.toml file.

taxonomies = [
    {name = "colors", feed = "true"},
    {name = "shape", feed = "false"}
]

you can then set the taxonomies per page in the header of each file

[taxonomies]
colors=["red", "blue"]
shape=["circle"]

the taxonomy pages are then visible at

$BASE_URL/$NAME/ (taxonomy)
$BASE_URL/$NAME/$SLUG (taxonomy entry)

tera

Zola uses the Tera html templating syntax.

markdown

zola uses common mark with shortcodes that allow you to nsert little macros. However, you can also just type raw html in the midst of a markdown document and it will be carried through. the basics:

#n is <hn>
- is bullet point
--- is a horizontal rule
*text* to emphasize
**text** to bold
\`` for code snippets, and triple for blocks
![text](url) to display an image
[text](url) to link

sass

As mentioned before, Zola uses Sass as a css preprocessor. Sass has two syntaxes: an extended css syntax, referred to as sassy css and indicated with a .scss filetype and indented syntax indicated with a .sass filetype. I'll be focussing on the scss syntax.

variables can be declared with $var_name:value; they are scoped so that variables declared inside a block are local to that block. you can add interpolation expressions anywhere in a scss document with a #{expression} the evaluated result of which will be inserted in place as an unquated string NOT a number. numbers can be inserted by using sass code as is. ie just using a variable name $var.

you can import other sass documents with @use. @import does the same thing but also imports the styles not just mixins and vars and functions.

mixins are importable styles that take the form of a style annotated with a @mixin before the style name and an optional list of arguments after @mixin style(args){rules}. we then use a mixin with the include keyword like so @include style(args);. arguments can be given default values by doing $arg:val. @include can also pass arguments by name not just positionally.

themes

sometimes you dont wanna build the look from scratch this is where themes come in.