Zola Tutorial 1: Content

Zola uses directories to manage site structure. Everything under content is content. Each subdirectory can be a section, and .md files inside a section are pages. A subdirectory inside a section can also represent a page, with extra files used as page resources.

A section’s _index.md file defines section metadata and can also contain content displayed on the section page. Page files can define their own metadata at the top. This metadata follows TOML syntax and is called front matter.

Resource Files

Non-Markdown files placed under a section or page directory are resource files. During build, they are copied into the output content directory. Pages can reference them with relative paths.

Example:

└── research
    ├── latest-experiment
    │   ├── index.md
    │   └── yavascript.js
    ├── _index.md
    └── research.jpg

Here, latest-experiment is a page. index.md contains page content and can reference yavascript.js. The section _index.md can reference research.jpg, for example to display an image on the section list page.

Files can be ignored during build through config.toml:

ignored_content = ["code_articles/**/{Cargo.lock,target}, *.rs"]

Static Resources

Consider this structure:

└── content
    └── blog
        ├── configuration
        │    └── index.md
        └── _index.md

The first index.md maps to /blog/configuration/. If this page needs images, there are several options:

• Put images under content/blog/configuration and reference them relatively.
• Put images under static/blog/configuration and reference them with a similar path.
• Put shared images under a global directory such as static/images, then reference them as /images/<filename>.

For small sites, a shared image directory is often enough. For larger content-heavy sites, colocated resources are easier to manage.

Sections

Any directory under content that contains _index.md is a section. If a directory has Markdown files but no _index.md, those files are still generated as pages, but the directory is not a section in the same sense.

The home page is also a section. It is usually represented by content/_index.md. If this file does not exist, the root section has no content or metadata.

Section front matter uses TOML between +++ markers:

+++
title = "List of blog posts"
sort_by = "date"
template = "blog.html"
page_template = "blog-page.html"
+++

After the closing +++, Markdown content can follow. Templates can access it through section.content. Even if you do not need metadata, the opening and closing markers are still required for section files.

Zola recommends TOML for front matter, but YAML can also be used by switching the delimiters to ---.

Common section front matter fields include:

• title and description
• draft: if true, the section is only generated with --drafts
• sort_by: date, update_date, title, title_bytes, weight, slug, or none
• weight: used to sort subsections
• template: template used to render the section
• page_template: template used by pages inside the section
• paginate_by and paginate_path
• insert_anchor_links
• in_search_index
• render
• redirect_to
• transparent
• aliases
• generate_feed
• [extra] for custom data

Drafts, Pagination, And Sorting

If draft = true, the section and its child sections are not generated unless zola build, zola serve, or zola check is run with --drafts.

Set paginate_by to a number greater than zero to enable pagination. The default page path is page/1, and paginate_path can change that.

Templates often iterate over section.pages:

{% for post in section.pages %}
 <h1><a href="{{ post.permalink }}">{{ post.title }}</a></h1>
{% endfor %}

The order follows sort_by. If pages are missing the required sort field, Zola may warn and skip them. If multiple pages share the same date, weight, or order, their permalinks are used for tie-breaking.

paginate_reversed = true reverses the order.

Subsections are sorted only by weight. If weight is missing or duplicated, their order is not reliable.

Pages

Markdown files under content are pages, except _index.md, which defines a section. Another special filename is index.md, which generates a page named after its directory. For example, content/about/index.md becomes /about/.

Other Markdown filenames generate paths from the filename. content/about.md and content/about/index.md both produce /about/, but the directory form makes colocated resources easier.

If a filename starts with a date, such as 2018-10-10-hello-world.md, the date becomes the page date unless front matter overrides it. The rest of the filename becomes the page path. If slugify.paths_keep_dates = true, this behavior is disabled.

Page Path Rules

A page path can come from:

• slug in front matter
• The file name
• path in front matter, which overrides both

If slugify.paths = "on", paths are slugified. If it is safe, only certain unsafe characters are removed. If it is off, paths are not processed. For non-ASCII paths, safe or off may be needed.

Example:

+++
title = "L'élevage de chèvres, la carrière alternative de tous dévelopeurs'"
slug = "élevage-chèvre-carrière-alternative"
+++

With safe or off, the path keeps the non-ASCII characters. With on, it becomes an ASCII slug.

Common page front matter fields include:

• title
• description
• date
• updated
• weight
• draft
• slug
• path
• aliases
• authors
• in_search_index

This separation between sections, pages, and resources is the core of Zola’s content model.

WeChat

Follow ZiCode on WeChat

If this post was useful, you can follow later updates on WeChat as well.

X / Twitter

Follow @ax2_zicode

Faster technical notes, short thoughts, and new-post alerts are posted on X.

X Open X Profile @ax2_zicode