Zola Integration Guide

This guide provides resources and information for integrating Sveltia CMS with Zola, a fast static site generator written in Rust.

Starter Templates

Here are some starter templates built by the community using Zola:

• Zola Sveltia Source by husenunicorn

Disclaimer

These third-party resources are not necessarily reviewed by the Sveltia CMS team. We are not responsible for their maintenance or support. Please contact the respective authors for any issues or questions.

Examples

See real-world examples of Zola integrations in our Showcase. Most of the listed sites include links to their source code, so you can explore how they implemented Sveltia CMS with Zola.

Setup

Adding the Admin Page

Zola serves static files from the static folder. Create static/admin/index.html and static/admin/config.yml as described in the Getting Started guide. The admin page is then available at /admin/ on the development server started with zola serve as well as on the built site.

Configuration

Zola stores content in the content folder, where each subfolder with an _index.md file is a section, and the other Markdown files in it are pages. The following example manages the pages of a blog section in content/blog:

media_folder: static/images
public_folder: /images
collections:
  - name: blog
    label: Blog
    folder: content/blog
    format: toml-frontmatter
    create: true
    fields:
      - { name: title, label: Title }
      - { name: date, label: Date, widget: datetime, type: date }
      - { name: description, label: Description, required: false }
      - { name: draft, label: Draft, widget: boolean, default: false }
      - name: taxonomies
        label: Taxonomies
        widget: object
        fields:
          - { name: tags, label: Tags, widget: list, required: false }
      - name: extra
        label: Extra
        widget: object
        required: false
        fields:
          - { name: image, label: Image, widget: image, required: false }
      - { name: body, label: Body, widget: markdown }

Some notes on this configuration:

• Zola’s front matter is usually written in TOML with +++ delimiters, so the format option is set to toml-frontmatter. YAML front matter is also supported by Zola, in which case the option can be omitted.
• Zola accepts a date in the YYYY-MM-DD or RFC 3339 format. The type: date option of the DateTime field saves a date without time. If you need the time as well, remove the type option and add output_utc: true so the value is saved with a time zone, as required by RFC 3339.
• Taxonomy terms like tags are stored in the taxonomies table, using the taxonomy names defined in zola.toml, so an Object field is used to group them. Custom properties go in the extra table in the same way.
• The section’s own _index.md file is not part of this collection. You can manage it with the index_file collection option or a file collection.

Support for Zola

We have implemented specific features to enhance the integration of Sveltia CMS with Zola:

• Entry-relative media folders: Store media files in folders relative to their associated entries, following Zola’s asset colocation convention.
• Nested collections: Manage a tree of sections as a folder tree in the sidebar, where each entry is stored as an _index.md file in its own folder and can be moved along with its children.
• Entry redirects: Out-of-the-box support for Zola’s aliases front matter property, which is updated when the entry slug is changed in Sveltia CMS.
• Manual entry reordering: Use the reorder option to add the weight property to entries for controlling their order in Zola.
• The value_type number field option supports int/string and float/string value types, which are useful for Zola sites that store numbers as strings in front matter. (Discussion)
• The omit_default_locale_from_file_path i18n option allows omitting the locale suffix from filenames for entries in the default locale, which is useful for multilingual Zola sites. (Discussion)