TODO for 0.0.1 about zola

[Keats]

Pagination

A few cases to consider:

• simple blog, with/without pagination
• site: typically no pagination
• site + blog: pagination on some bits only potentially (the blog)
• random site with pagination on some sections (like a knowledge base for example)

Default is no pagination at all.

Then people can add paginations for whatever section they want. We need 3 elements for each pagination: (section_name, num_per_page, path_name).

Example of mixed site+blog content folder:

content
 - about.md
 - pricing.md
 - blog
   - article1.md

• section_name: for example you can use blog and it will generate pagination for all the pages in blog. The only way I can see it working for the basic blog is to have a magic name, like base that will work on the first level in the content folder
• num_per_page: how many pages on each page of the pagination
• path_name: what goes in the url for the pagination. For example, if I use "page", the second page will be mysite.com/page/2

We can potentially have several type of contents needing pagination, but since I'm not using pagination at all myself, one basic level should be fine to start with.

[Keats]

Sections

Each section should have an index page created automatically.
It should also contains the data of the child sections if possible so you can build some kind of layout like https://easyengine.io/tutorials/
The tricky thing: how to have different templates for different sections.

3 possible approaches, in order of preference:

• Allow a specific file for a section: https://gohugo.io/overview/source-directory/#content-for-home-page-and-other-list-pages
• Define the mapping in config.toml
• Automatically map section name to a template

Mapping in config

Something like

[[section_templates]]
name = "post"
template = "posts.html"

[[section_templates]]
name = "knowledge-base"
template = "kb.html"

The _index.md approach is the most flexible, and ensure those list appear in sitemap and can have titles/specific layouts

See http://bepsays.com/en/2016/12/19/hugo-018/ for details on how Hugo solved that

One important thing is how to differentiate post in a folder with a content from a section. Maybe only create a section when a file named _index.md is created? It's also more explicit this way: people can decide whether to have a section page or not rather than having one 100% of the time

Test site

.
└── posts
    ├── fixed-slug.md
    ├── fixed-url.md
    ├── _index.md
    ├── no-section
    │   └── simple.md
    ├── python.md
    ├── simple.md
    ├── tutorials
    │   ├── devops
    │   │   ├── docker.md
    │   │   ├── _index.md
    │   │   └── nix.md
    │   ├── _index.md
    │   └── programming
    │       ├── _index.md
    │       ├── python.md
    │       └── rust.md
    └── with-assets
        ├── index.md
        └── with.js

Only 4 sections (4 _index.md) but some are children of others.
We want to get the children section as well so when rendering the tutorials sections, we would have access to the the pages of devops and programming as well if we want to render some kind of TOC

[Keats]

(Architecture) Design of Pages (Page, Section, RSS, Sitemap, Index)

Index

Nothing to do here, there's the index.html template and we can just pass all the site data

RSS/Sitemap

Very basic templates, nothing to do there it's already working ok

Page

The current design feels ok I think

Section

Having section as a Page is a bit annoying as they have very little in common. A section will only have a frontmatter and no content. We could have a enum with two variants: Page and Section but it doesn't seem worth the hassle.
Possible solution: a Section struct. When encountering a _index.md in parse_site, we could create a Section struct instead of a Page struct.
Section will only have as little info as required: a frontmatter, some path infos and 2 fields filled later: pages and subsections, pages only containing the immediate pages in that section.
This allows pages and sections to have different render_html methods and make it easier to handle things like sorting sections only, for example with a weight field.
The site would hold those Section and, when done with parsing, could populate the pages and subsections with the correct info. Rendering should be much easier if we have structs as well.