Zola

https://www.getzola.org/documentation
Admin
Zola is a static site generator (SSG) written in Rust that uses the Tera template engine to...
Tokens:34,843
Snippets:456
Trust Score:9.8
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Zola via Package Managers

Source: https://www.getzola.org/documentation/getting-started/installation

Installation commands for pkgsrc, Snapcraft, and Flatpak.

```bash
$ pkgin install zola
```

```bash
$ snap install --edge zola
```

```bash
$ flatpak install flathub org.getzola.zola
```

```bash
$ flatpak run org.getzola.zola [command]
```

```bash
$ alias zola="flatpak run org.getzola.zola"
```

--------------------------------

### Install Edgio CLI

Source: https://www.getzola.org/documentation/deployment/edgio

Install the global Edgio command-line interface.

```bash
npm i -g @edgio/cli
```

--------------------------------

### Install Zola on Windows

Source: https://www.getzola.org/documentation/getting-started/installation

Installation options for Windows using Winget, Scoop, or Chocolatey.

```bash
$ winget install getzola.zola
```

```bash
$ scoop install zola
```

```bash
$ choco install zola
```

--------------------------------

### Install Zola in GitHub Actions

Source: https://www.getzola.org/documentation/getting-started/installation

Example configuration for using the taiki-e/install-action in a CI workflow.

```yaml
jobs:
  foo:
    steps:
      - uses: taiki-e/install-action@v2
        with:
          tool: zola@0.19.1
      # ...
```

--------------------------------

### Start the Zola development server

Source: https://www.getzola.org/documentation/getting-started

Run the Zola server to build the site and enable live reloading.

```bash
$ zola serve
Building site...
Checking all internal links with anchors.
> Successfully checked 0 internal link(s) with anchors.
-> Creating 0 pages (0 orphan) and 0 sections
Done in 13ms.

Web server is available at http://127.0.0.1:1111

Listening for changes in .../myblog/{zola.toml,content,sass,static,templates}
Press Ctrl+C to stop
```

--------------------------------

### Install a theme via Git

Source: https://www.getzola.org/documentation/themes/installing-and-using-themes

Use Git to clone a theme repository directly into the themes directory.

```bash
$ cd themes
$ git clone <theme repository URL>
```

--------------------------------

### Install Zola on NixOS

Source: https://www.getzola.org/documentation/getting-started/installation

Configuration for NixOS system packages or standalone nix-env installation.

```nix
environment.systemPackages = [
  pkgs.zola
];
```

```bash
nix-env -iA nixpkgs.zola
```

--------------------------------

### Run Docker Image

Source: https://www.getzola.org/documentation/deployment/docker-image

Command to start the container and map port 8000 for local testing.

```bash
docker run --rm -p 8000:80 my_website:latest
```

--------------------------------

### Configure Translations

Source: https://www.getzola.org/documentation/getting-started/configuration

Example configuration for setting the default language and translation strings.

```toml
[translations]
title = "Un titre"
```

--------------------------------

### Configure GitHub-style Alerts

Source: https://www.getzola.org/documentation/getting-started/configuration

Example of the Markdown syntax and resulting HTML for GitHub-style alerts.

```markdown
> [!NOTE]
> alert note
```

```html
<blockquote class="markdown-alert-note">
<p>alert note</p>
</blockquote>
```

--------------------------------

### Pagination Template Implementation

Source: https://www.getzola.org/documentation/templates/pagination

Example of iterating through paginated pages and displaying navigation links in a template.

```html
<div class="posts">
    {% for page in paginator.pages %}
        <article class="post">
            {{ post_macros::title(page=page) }}
            <div class="post__summary">
                {{ page.summary | safe }}
            </div>
            <div class="read-more">
                <a href="{{ page.permalink }}">Read more...</a>
            </div>
        </article>
    {% endfor %}
</div>
<nav class="pagination">
    {% if paginator.previous %}
        <a class="previous" href="{{ paginator.previous }}">‹ Previous</a>
    {% endif %}
    {% if paginator.next %}
        <a class="next" href="{{ paginator.next }}">Next ›</a>
    {% endif %}
</nav>
```

--------------------------------

### Combined Annotation Example

Source: https://www.getzola.org/documentation/content/syntax-highlighting

Example demonstrating multiple annotations applied to a single code block.

```scss
10pre mark {
12  display: block;
13  color: currentcolor;
14}
15pre table td:nth-of-type(1) {
17  color: #6b6b6b;
18  font-style: italic;
19}
```

--------------------------------

### Install Zola on Linux Distributions

Source: https://www.getzola.org/documentation/getting-started/installation

Commands for installing Zola via native package managers on Arch, Alpine, Debian, Gentoo, Void, FreeBSD, OpenBSD, and openSUSE.

```bash
$ pacman -S zola
```

```bash
$ apk add zola
```

```bash
$ sudo dpkg -i zola_<version>_amd64_debian_<debian_version>.deb
```

```bash
$ sudo emerge --ask www-apps/zola
```

```bash
$ sudo xbps-install zola
```

```bash
$ pkg install zola
```

```bash
$ doas pkg_add zola
```

```bash
$ sudo zypper install zola
```

```bash
$ sudo zypper addrepo https://download.opensuse.org/repositories/utilities/15.6/utilities.repo
$ sudo zypper refresh
$ sudo zypper install zola
```

--------------------------------

### Extended robots.txt with include

Source: https://www.getzola.org/documentation/templates/robots

Example of extending the robots.txt file by including additional content from another template file.

```text
User-agent: *
Disallow:
Allow: /
Sitemap: {{ get_url(path="sitemap.xml") }}

{% include "path/to/other/robots.txt" %}
```

--------------------------------

### Install Zola on macOS

Source: https://www.getzola.org/documentation/getting-started/installation

Use Homebrew or MacPorts to install Zola on macOS systems.

```bash
$ brew install zola
```

```bash
$ sudo port install zola
```

--------------------------------

### Example Directory Structure

Source: https://www.getzola.org/documentation/content

A simplified representation of a Zola content directory structure showing how Markdown files are mapped to URLs.

```text
.
└── content
    └── blog
        ├── configuration
        │    └── index.md // -> https://mywebsite.com/blog/configuration/
        └── _index.md // -> https://mywebsite.com/blog/
```

--------------------------------

### Pushing Changes to Trigger Build

Source: https://www.getzola.org/documentation/deployment/sourcehut

Example output after pushing changes to the repository, which automatically triggers the Sourcehut build job.

```bash
$ git push
Enumerating objects: 5, done.
...
remote: Build started:
remote: https://builds.sr.ht/~your_username/job/430625 [.build.yml]
To git.sr.ht:~your_username/www
   fbe9afa..59ae556  master -> master
```

--------------------------------

### YouTube Shortcode Usage

Source: https://www.getzola.org/documentation/content/shortcodes

Examples of how to invoke the YouTube shortcode with various parameters in Zola content files.

```text
{{ youtube(id="dCKeXuVHl1o") }}

{{ youtube(id="dCKeXuVHl1o", playlist="RDdQw4w9WgXcQ") }}

{{ youtube(id="dCKeXuVHl1o", autoplay=true) }}

{{ youtube(id="dCKeXuVHl1o", autoplay=true, class="youtube") }}
```

--------------------------------

### Sass Directory Structure Example

Source: https://www.getzola.org/documentation/content/sass

Visual representation of how Zola maps Sass source files to the public CSS output directory.

```text
.
└── sass
    ├── style.scss // -> ./public/style.css
    ├── indented_style.sass // -> ./public/indented_style.css
    ├── _include.scss # This file won't get put into the `public` folder, but other files can @import it.
    ├── assets
    │   ├── fancy.scss // -> ./public/assets/fancy.css
    │   ├── same_name.scss // -> ./public/assets/same_name.css
    │   ├── same_name.sass # CONFLICT! This has the same base name as the file above, so Zola will return an error.
    │   └── _common_mixins.scss # This file won't get put into the `public` folder, but other files can @import it.
    └── secret-side-project
        └── style.scss // -> ./public/secret-side-project/style.css
```

--------------------------------

### Custom Zola binary installation command

Source: https://www.getzola.org/documentation/deployment/vercel

A shell command to download and extract a specific Zola binary version, intended for use in the Vercel dashboard 'Install Command' field.

```bash
v=${ZOLA_VERSION:+tags/v$ZOLA_VERSION};curl -fsSL https://api.github.com/repos/getzola/zola/releases/${v:-latest}|grep -o '"browser_download_url": *"[^"]*x86_64-unknown-linux-'${ZOLA_LIBC:-musl}'\.tar\.gz"'|cut -d'"' -f4|xargs curl -fsSL|tar -xz
```

--------------------------------

### Heading ID generation examples

Source: https://www.getzola.org/documentation/content/linking

Shows how Zola automatically generates unique slugs for headings, including handling duplicate text.

```markdown
# Something exciting! <- something-exciting
## Example code <- example-code

# Something else <- something-else
## Example code <- example-code-1
```

--------------------------------

### Configure GitHub Actions for Zola Deployment

Source: https://www.getzola.org/documentation/deployment/azure-static-webapps

Update the auto-generated GitHub Actions workflow to include Zola installation and build steps.

```yaml
# .github/workflows/azure-static-web-apps-<web-app-name>
name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
          lfs: false
      - uses: taiki-e/install-action@v2
        with:
          tool: zola@0.21.0
      - name: Build Static Site
        run: zola build
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_<WEB_APP_NAME>}}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
          action: "upload"
          ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
          # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
          app_location: "./public" # App source code path
          api_location: "" # Api source code path - optional
          output_location: "" # Built app content directory - optional
          ###### End of Repository/Build Configurations ######

  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN<WEB_APP_NAME> }}
          action: "close"
```

--------------------------------

### Initialize package.json

Source: https://www.getzola.org/documentation/deployment/edgio

Create a package.json file in the project root.

```bash
npm init -y
```

--------------------------------

### Initialize Edgio

Source: https://www.getzola.org/documentation/deployment/edgio

Initialize the project configuration for Edgio.

```bash
edgio init
```

--------------------------------

### Build with custom configuration file

Source: https://www.getzola.org/documentation/getting-started/cli-usage

Uses a specific configuration file instead of the default zola.toml.

```bash
$ zola --config config.staging.toml build
```

--------------------------------

### Initialize a Zola project

Source: https://www.getzola.org/documentation/getting-started/cli-usage

Creates the Zola directory structure in the specified or current directory.

```bash
$ zola init my_site
$ zola init
```

--------------------------------

### Serve with a custom configuration file

Source: https://www.getzola.org/documentation/getting-started/cli-usage

Specify a configuration file other than the default zola.toml.

```bash
$ zola --config config.staging.toml serve
```

--------------------------------

### Build the site

Source: https://www.getzola.org/documentation/getting-started/cli-usage

Generates the site into the public directory, deleting any existing content in that directory.

```bash
$ zola build
```

--------------------------------

### Deploy to Edgio

Source: https://www.getzola.org/documentation/deployment/edgio

Execute the deployment process to push the site to Edgio.

```bash
edgio deploy
```

--------------------------------

### Initialize Git Repository

Source: https://www.getzola.org/documentation/deployment/zeabur

Commands to initialize a local Git repository and commit the initial project files.

```bash
git init
git add .
git commit -m "Initial commit"
```

--------------------------------

### Movie Taxonomy Structure Example

Source: https://www.getzola.org/documentation/content/taxonomies

A conceptual representation of how movies are associated with taxonomies and terms in Zola.

```text
- Shape of water                             Value
  - Director ............................ Taxonomy
    - Guillermo Del Toro                      Term
  - Genres .............................. Taxonomy
    - Thriller                                Term
    - Drama                                   Term
  - Awards .............................. Taxonomy
    - Golden globe                            Term
    - Academy award                           Term
    - BAFTA                                   Term
  - Release year ........................ Taxonomy
    - 2017                                    Term

- The Room                                   Value
  - Director ............................ Taxonomy
    - Tommy Wiseau                            Term
  - Genres .............................. Taxonomy
    - Romance                                 Term
    - Drama                                   Term
  - Release Year ........................ Taxonomy
    - 2003                                    Term

- Bright                                     Value
  - Director ............................ Taxonomy
    - David Ayer                              Term
  - Genres .............................. Taxonomy
    - Fantasy                                 Term
    - Action                                  Term
  - Awards .............................. Taxonomy
    - California on Location Awards           Term
  - Release Year ........................ Taxonomy
    - 2017                                    Term
```

--------------------------------

### Zola Initialization Prompts

Source: https://www.getzola.org/documentation/getting-started

Interactive configuration prompts displayed during site initialization.

```text
> What is the URL of your site? (https://example.com):
> Do you want to enable Sass compilation? [Y/n]:
> Do you want to enable syntax highlighting? [y/N]:
> Do you want to build a search index of the content? [y/N]:
```

--------------------------------

### Create a blog post

Source: https://www.getzola.org/documentation/getting-started

Define post metadata in TOML format followed by the Markdown content.

```markdown
+++
title = "My first post"
date = 2019-11-27
+++

This is my first blog post.
```

```markdown
+++
title = "My second post"
date = 2019-11-28
+++

This is my second blog post.
```

--------------------------------

### Build Zola Application

Source: https://www.getzola.org/documentation/deployment/edgio

Generate the static site files using the Zola build command.

```bash
zola build
```

--------------------------------

### Build Docker Image

Source: https://www.getzola.org/documentation/deployment/docker-image

Command to build the website image from the current directory.

```bash
docker build -t my_website:latest .
```

--------------------------------

### Configure Netlify build settings with netlify.toml

Source: https://www.getzola.org/documentation/deployment/netlify

Use this configuration file to define build commands, publish directories, and environment variables for automatic deployments and preview branches.

```toml
[build]
# This assumes that the Zola site is in a docs folder. If it isn't, you don't need
# to have a `base` variable but you do need the `publish` and `command` variables.
base    = "docs"
publish = "docs/public"
command = "zola build"

[build.environment]
# Set the version name that you want to use and Netlify will automatically use it.
ZOLA_VERSION = "0.13.0"

# The magic for deploying previews of branches.
# We need to override the base url with whatever url Netlify assigns to our
# preview site.  We do this using the Netlify environment variable
# `$DEPLOY_PRIME_URL`.

[context.deploy-preview]
command = "zola build --base-url $DEPLOY_PRIME_URL"
```

--------------------------------

### get_url

Source: https://www.getzola.org/documentation/templates/overview

Gets the permalink for a given path, supporting internal links, static files, language-aware URLs, and cache busting.

```APIDOC
## get_url

### Description
Retrieves the permalink for a specified path. Supports internal Markdown files (prefixed with @/), static files, and language-aware URL generation.

### Parameters
- **path** (string) - Required - The path to the file or internal resource.
- **lang** (string) - Optional - Language code for multilingual websites.
- **trailing_slash** (boolean) - Optional - Whether to force a trailing slash in the URL.
- **cachebust** (boolean) - Optional - Whether to append a SHA256 hash to the URL for cache busting.

### Example
{% set url = get_url(path="@/blog/_index.md", lang="en", trailing_slash=true) %}
```

--------------------------------

### Sourcehut Build Manifest for Zola

Source: https://www.getzola.org/documentation/deployment/sourcehut

A .build.yml configuration file that installs dependencies, builds the Zola site, and publishes it to Sourcehut Pages.

```yaml
image: alpine/edge
packages:
  - hut
  - zola
oauth: pages.sr.ht/PAGES:RW
environment:
  site: your_username.srht.site
sources:
  - https://git.sr.ht/~your_username/my-website
tasks:
  - build: |
      cd my-website
      zola build
  - package: |
      cd my-website
      tar -C public -cvz . > ../site.tar.gz
  - upload: |
      hut pages publish -d $site site.tar.gz
```

--------------------------------

### Build Zola from Source

Source: https://www.getzola.org/documentation/getting-started/installation

Commands to compile Zola from the Git repository using Cargo.

```bash
$ cargo install --locked --git https://github.com/getzola/zola
$ zola --version
```

```bash
$ cargo install --locked --no-default-features --features=native-tls --git https://github.com/getzola/zola
```

--------------------------------

### Build with custom output directory

Source: https://www.getzola.org/documentation/getting-started/cli-usage

Specifies a custom output directory instead of the default public folder.

```bash
$ zola build --output-dir $DOCUMENT_ROOT
```

--------------------------------

### load_data

Source: https://www.getzola.org/documentation/templates/overview

Loads data from a remote URL using GET or POST requests with support for custom headers, formats, and body content.

```APIDOC
## load_data

### Description
Loads data from a remote URL. Supports HTTP GET and POST methods, custom headers, and automatic parsing of formats like JSON.

### Parameters
- **url** (string) - Required - The remote URL to fetch.
- **format** (string) - Optional - The format to parse the response (e.g., "json", "plain").
- **method** (string) - Optional - The HTTP method to use ("GET" or "POST"). Defaults to "GET".
- **body** (string) - Optional - The request body content for POST requests.
- **content_type** (string) - Optional - The mimetype of the request body.
- **headers** (array) - Optional - A list of strings representing HTTP headers to include in the request.

### Example
{% set response = load_data(url="https://api.github.com/repos/getzola/zola", format="json") %}
```

--------------------------------

### Initialize Zola in a git repository

Source: https://www.getzola.org/documentation/getting-started/cli-usage

Initializes a Zola site within an existing git repository.

```bash
$ git init
$ zola init
```

--------------------------------

### Custom Zola configuration in vercel.json

Source: https://www.getzola.org/documentation/deployment/vercel

An alternative to dashboard settings that defines the framework, install command, build command, and output directory for custom Zola binary usage.

```json
{
    "framework": null,
    "installCommand": "v=${ZOLA_VERSION:+tags/v$ZOLA_VERSION};curl -fsSL https://api.github.com/repos/getzola/zola/releases/${v:-latest}|grep -o '\"browser_download_url\": *\"[^\"]*x86_64-unknown-linux-'${ZOLA_LIBC:-musl}'\\.tar\\.gz\"'|cut -d'\"' -f4|xargs curl -fsSL|tar -xz",
    "buildCommand": "./zola build",
    "outputDirectory": "public"
}
```

--------------------------------

### Create a Dockerfile for Zola

Source: https://www.getzola.org/documentation/deployment/flyio

A multi-stage Dockerfile that builds the Zola site and serves it using a static web server.

```dockerfile
FROM ghcr.io/getzola/zola:v0.17.2 AS builder

WORKDIR /app
COPY . .
RUN ["zola", "build"]

FROM joseluisq/static-web-server:2
COPY --from=builder /app/public /public
ENV SERVER_PORT 8080
```

--------------------------------

### Serve the site with various configurations

Source: https://www.getzola.org/documentation/getting-started/cli-usage

Common usage patterns for the zola serve command, including port, interface, and base URL overrides.

```bash
$ zola serve
$ zola serve --port 2000
$ zola serve --interface 0.0.0.0
$ zola serve --interface 0.0.0.0 --port 2000
$ zola serve --interface 0.0.0.0 --base-url 127.0.0.1
$ zola serve --interface 0.0.0.0 --base-url /
$ zola serve --interface 0.0.0.0 --port 2000 --output-dir www/public
$ zola serve --open
```

--------------------------------

### Deploy site manually via Netlify API

Source: https://www.getzola.org/documentation/deployment/netlify

Use this curl command to upload a zipped public directory to Netlify when manual deployment is required.

```bash
curl -H "Content-Type: application/zip" \
     -H "Authorization: Bearer PERSONAL_ACCESS_TOKEN_FROM_STEP_1" \
     --data-binary "@FILE_NAME.zip" \
     https://api.netlify.com/api/v1/sites/SITE_NAME.netlify.com/deploys
```

--------------------------------

### Configure routes.js

Source: https://www.getzola.org/documentation/deployment/edgio

Define the routing configuration to serve static files from the public directory.

```javascript
// This file was added by edgio init.
// You should commit this file to source control.

import { Router } from '@edgio/core/router'

export default new Router().static('public')
```

--------------------------------

### Create a Zola build script

Source: https://www.getzola.org/documentation/deployment/cloudflare-workers

A shell script to download the Zola binary, update submodules, and execute the build process.

```bash
#!/usr/bin/env bash
main() {
    ZOLA_VERSION=0.22.1

    curl -sLJO "https://github.com/getzola/zola/releases/download/v${ZOLA_VERSION}/zola-v${ZOLA_VERSION}-x86_64-unknown-linux-gnu.tar.gz"
    tar -xf zola-v${ZOLA_VERSION}-x86_64-unknown-linux-gnu.tar.gz

    git submodule update --init --recursive

    ./zola build
}

set -euo pipefail
```

--------------------------------

### Multi-stage Dockerfile for Zola

Source: https://www.getzola.org/documentation/deployment/docker-image

Uses the official Zola image to build the project and copies the output to a static-web-server image.

```dockerfile
FROM ghcr.io/getzola/zola:v0.22.1 AS zola

COPY . /project
WORKDIR /project
RUN ["zola", "build"]

FROM ghcr.io/static-web-server/static-web-server:2
WORKDIR /
COPY --from=zola /project/public /public
```

--------------------------------

### Default robots.txt configuration

Source: https://www.getzola.org/documentation/templates/robots

Standard robots.txt template using the get_url function to point to the sitemap.

```text
User-agent: *
Disallow:
Allow: /
Sitemap: {{ get_url(path="sitemap.xml") }}
```

--------------------------------

### Configure Markdown and Link Settings

Source: https://www.getzola.org/documentation/getting-started/configuration

General settings for Markdown parsing, including external link behavior, smart punctuation, and GitHub-style alerts.

```toml
external_links_no_referrer = false

external_links_external = true

smart_punctuation = false

definition_list = false

lazy_async_image = false

bottom_footnotes = false

github_alerts = false

insert_anchor_links = "none"
```

--------------------------------

### Configure GitLab CI/CD for Zola

Source: https://www.getzola.org/documentation/deployment/gitlab-pages

Create a .gitlab-ci.yml file to define the deployment pipeline. Specify the desired Zola version in the ZOLA_VERSION variable.

```yaml
stages:
  - deploy

default:
  image: debian:stable-slim

variables:
  # The runner will be able to pull your Zola theme when the strategy is
  # set to "recursive".
  GIT_SUBMODULE_STRATEGY: "recursive"

  # Make sure you specify a version of Zola here.
  # Use the semver format (x.y.z) to specify a version.
  # For example: "0.17.2" or "0.18.0".
  ZOLA_VERSION:
    description: "The version of Zola used to build the site."
    value: ""

pages:
  stage: deploy
  script:
    - |
      apt-get update
      DEBIAN_FRONTEND=noninteractive apt-get install --assume-yes --no-install-recommends wget ca-certificates
      zola_url="https://github.com/getzola/zola/releases/download/v${ZOLA_VERSION}/zola-v${ZOLA_VERSION}-x86_64-unknown-linux-gnu.tar.gz"
      if ! wget --quiet --spider $zola_url; then
        echo "A Zola release with the specified version could not be found."
        exit 1
      fi
      wget $zola_url
      tar -xzf *.tar.gz
      ./zola build --base-url $CI_PAGES_URL

  artifacts:
    paths:
      # This is the directory whose contents will be deployed to the GitLab Pages server.
      # GitLab Pages expects a directory with this name by default.
      - public

  rules:
    # This rule makes it so that your website is published and updated only when
    # you push to the default branch of your repository (e.g. "master" or "main").
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```

--------------------------------

### Enable CJK search indexing

Source: https://www.getzola.org/documentation/content/multilingual

Build Zola with specific features to enable search indexing support for Chinese and Japanese.

```bash
cargo build --features indexing-ja --features indexing-zh
```

--------------------------------

### Dual Theme Configuration

Source: https://www.getzola.org/documentation/content/syntax-highlighting

Configuration keys for setting light and dark themes in the [markdown.highlighting] section.

```toml
light_theme = "github-light"                                                                                     
dark_theme = "github-dark"
```

--------------------------------

### Define a content section

Source: https://www.getzola.org/documentation/getting-started

Configure a section using TOML variables in an _index.md file. The opening and closing +++ delimiters are mandatory.

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

--------------------------------

### Configure Syntax Highlighting

Source: https://www.getzola.org/documentation/getting-started/configuration

Settings for the Markdown syntax highlighter, including theme selection and extra grammars.

```toml
[markdown.highlighting]
error_on_missing_language = false

style = "inline"

theme = ""

light_theme = ""
dark_theme = ""

extra_grammars = []

extra_themes = []
```

--------------------------------

### Final Directory Structure

Source: https://www.getzola.org/documentation/getting-started

The directory structure after adding blog content and templates.

```text
├── zola.toml
├── content/
│   └── blog/
│       ├── _index.md
│       ├── first.md
│       └── second.md
├── sass/
├── static/
├── templates/
│   ├── base.html
│   ├── blog-page.html
│   ├── blog.html
│   └── index.html
└── themes/
```

--------------------------------

### Run Zola with Docker

Source: https://www.getzola.org/documentation/getting-started/installation

Commands for pulling the Zola image and executing build or serve tasks.

```bash
$ docker pull ghcr.io/getzola/zola:v0.19.1
```

```bash
$ docker run -u "$(id -u):$(id -g)" -v $PWD:/app --workdir /app ghcr.io/getzola/zola:v0.19.1 build
```

```bash
$ docker run -u "$(id -u):$(id -g)" -v $PWD:/app --workdir /app -p 8080:8080 ghcr.io/getzola/zola:v0.19.1 serve --interface 0.0.0.0 --port 8080 --base-url localhost
```

--------------------------------

### Build from a different root directory

Source: https://www.getzola.org/documentation/getting-started/cli-usage

Processes a project located in a different directory using the root flag.

```bash
$ zola --root /path/to/project build
```

--------------------------------

### CSS Import for Class-based Highlighting

Source: https://www.getzola.org/documentation/content/syntax-highlighting

Importing generated CSS files based on user color scheme preference.

```css
@import url("giallo-dark.css") (prefers-color-scheme: dark);
@import url("giallo-light.css") (prefers-color-scheme: light);
```

--------------------------------

### Configure Slugification

Source: https://www.getzola.org/documentation/getting-started/configuration

Settings for generating URL slugs for paths, taxonomies, and anchors.

```toml
[slugify]
paths = "on"
taxonomies = "on"
anchors = "on"
paths_keep_dates = false
```

--------------------------------

### Gallery Shortcode Implementation

Source: https://www.getzola.org/documentation/content/image-processing

Iterates through page assets, filters for image files, and generates a clickable gallery.

```html
<div>
{% for asset in page.assets -%}
  {%- if asset is matching("[.](jpg|png)$") -%}
    {% set image = resize_image(path=asset, width=240, height=180) %}
    <a href="{{ get_url(path=asset) }}" target="_blank">
      <img src="{{ image.url }}" />
    </a>
  {%- endif %}
{%- endfor %}
</div>
```

--------------------------------

### Base Template

Source: https://www.getzola.org/documentation/getting-started

The base HTML layout file for the site.

```html
<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="utf-8">
  <title>MyBlog</title>
</head>

<body>
  <section class="section">
    <div class="container">
      {% block content %} {% endblock content %}
    </div>
  </section>
</body>

</html>
```

--------------------------------

### Configure Dynamic Build Command

Source: https://www.getzola.org/documentation/deployment/cloudflare-pages

Use this command in the Cloudflare Pages build settings to ensure assets load correctly on preview branches by dynamically setting the base URL.

```bash
if [ "$CF_PAGES_BRANCH" = "main" ]; then zola build; else zola build --base-url $CF_PAGES_URL; fi
```

--------------------------------

### Push Project to GitHub

Source: https://www.getzola.org/documentation/deployment/zeabur

Commands to link a local repository to a remote GitHub repository and push the main branch.

```bash
git remote add origin <your-github-repo-url>
git branch -M main
git push -u origin main
```

--------------------------------

### Create a Markdown-based data shortcode

Source: https://www.getzola.org/documentation/content/shortcodes

Define a shortcode in templates/shortcodes/books.md that loads external TOML data and renders it as Markdown.

```jinja2
{% set data = load_data(path=path) -%}
{% for book in data.books %}
### {{ book.title }}

{{ book.description | safe }}
{% endfor %}
```

--------------------------------

### Taxonomy Output Path Patterns

Source: https://www.getzola.org/documentation/content/taxonomies

Standard URL structures for taxonomy list and entry pages.

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

--------------------------------

### resize_image(path, width, height, op, format, quality, speed)

Source: https://www.getzola.org/documentation/content/image-processing

Processes an image by resizing it based on the provided arguments and returns an object containing the new URL and dimensions.

```APIDOC
## resize_image(path, width, height, op, format, quality, speed)

### Description
Processes an image file, resizing it according to the specified dimensions and operation, and returns an object containing the resulting asset information.

### Parameters
- **path** (String) - Required - The path to the source image.
- **width** (u32) - Required - The target width in pixels.
- **height** (u32) - Required - The target height in pixels.
- **op** (String) - Optional - Resize operation: "scale", "fit_width", "fit_height", "fit", or "fill" (default).
- **format** (String) - Optional - Encoding format: "auto" (default), "jpg", "png", "webp", or "avif".
- **quality** (u32) - Optional - Quality setting for JPEG, WebP, or AVIF.
- **speed** (u32) - Optional - Encoding speed for AVIF (1-10).

### Response
- **url** (String) - The final URL for the processed asset.
- **static_path** (String) - The path to the static asset generated.
- **width** (u32) - New image width.
- **height** (u32) - New image height.
- **orig_width** (u32) - Original image width.
- **orig_height** (u32) - Original image height.
```

--------------------------------

### Link to continue reading

Source: https://www.getzola.org/documentation/content/page

Use this HTML snippet to create a link that jumps directly to the summary cutoff point.

```html
<a href="{{ page.permalink }}#continue-reading">Continue Reading</a>
```

--------------------------------

### Directory Structure for Asset Colocation

Source: https://www.getzola.org/documentation/content

Organize pages with assets by using a dedicated directory containing an index.md file.

```text
└── research
    ├── latest-experiment
    │   ├── index.md
    │   └── javascript.js
    ├── _index.md
    └── research.jpg
```

--------------------------------

### Default Zola Directory Structure

Source: https://www.getzola.org/documentation/getting-started/directory-structure

The standard file and directory layout generated after running the zola init command.

```text
.
├── zola.toml
├── content
├── sass
├── static
├── templates
└── themes

5 directories, 1 file
```

--------------------------------

### Blog Listing Template

Source: https://www.getzola.org/documentation/getting-started

Template for listing blog posts using a loop over section pages.

```html
{% extends "base.html" %}

{% block content %}
<h1 class="title">
  {{ section.title }}
</h1>
<ul>
  <!-- If you are using pagination, section.pages will be empty.
       You need to use the paginator object -->  
  {% for page in section.pages %}
  <li><a href="{{ page.permalink | safe }}">{{ page.title }}</a></li>
  {% endfor %}
</ul>
{% endblock content %}
```

--------------------------------

### Retrieve a page with get_page

Source: https://www.getzola.org/documentation/templates/overview

Fetches a page object based on its path relative to the content directory.

```Tera
{% set page = get_page(path="blog/page2.md") %}
```

```Tera
{% set page = get_page(path="blog/page2.md", lang="fr") %}

{# If "fr" is the default language, this is equivalent to #}
{% set page = get_page(path="blog/page2.md") %}

{# If "fr" is not the default language, this is equivalent to #}
{% set page = get_page(path="blog/page2.fr.md") %}
```

--------------------------------

### Add a Zola theme as a submodule

Source: https://www.getzola.org/documentation/deployment/gitlab-pages

Use git submodules to ensure themes are included in the repository. Ensure the theme URL uses the https protocol.

```bash
git submodule add {THEME_URL} themes/{THEME_NAME}
```

```bash
git submodule add https://github.com/getzola/hyde.git themes/hyde
```

--------------------------------

### Define and use shortcodes with a body

Source: https://www.getzola.org/documentation/content/shortcodes

Define a template using the body variable and invoke it using the percent sign syntax in markdown.

```html
<blockquote>
    {{ body }} <br>
    -- {{ author }}
</blockquote>
```

```markdown
As someone said:

{% quote(author="Vincent") %}
A quote
{% end %}
```

--------------------------------

### Taxonomy Output Paths with Root

Source: https://www.getzola.org/documentation/content/taxonomies

URL structures when the taxonomy_root configuration option is enabled.

```text
$BASE_URL/$TAXONOMY_ROOT/$NAME/ (taxonomy)
$BASE_URL/$TAXONOMY_ROOT/$NAME/$SLUG (taxonomy entry)
```

--------------------------------

### Calling Gallery Shortcode

Source: https://www.getzola.org/documentation/content/image-processing

Syntax for invoking the gallery shortcode within a Markdown file.

```text
{{ gallery() }}
```

--------------------------------

### Configure Zola Section Front Matter

Source: https://www.getzola.org/documentation/content/section

Use this template in _index.md to define section metadata. The opening and closing +++ delimiters are mandatory.

```toml
title = ""

description = ""

# A draft section is only loaded if the `--drafts` flag is passed to `zola build`, `zola serve` or `zola check`.
draft = false

# Used to sort pages by "date", "update_date", "title", "title_bytes", "weight", "slug" or "none". See below for more information.
sort_by = "none"

# Used by the parent section to order its subsections.
# Lower values have higher priority.
weight = 0

# Template to use to render this section page.
template = "section.html"

# The given template is applied to ALL pages below the section, recursively.
# If you have several nested sections, each with a page_template set, the page
# will always use the closest to itself.
# However, a page's own `template` variable will always have priority.
# Not set by default.
page_template =

# This sets the number of pages to be displayed per paginated page.
# No pagination will happen if this isn't set or if the value is 0.
paginate_by = 0

# If set, this will be the path used by the paginated page. The page number will be appended after this path.
# The default is page/1.
paginate_path = "page"

# If set, pagination will happen in a reversed order.
paginate_reversed = false

# This determines whether to insert a link for each header like the ones you can see on this site if you hover over
# a header.
# The default template can be overridden by creating an `anchor-link.html` file in the `templates` directory.
# This value can be "left", "right", "heading" or "none".
# "heading" means the full heading becomes the text of the anchor.
insert_anchor_links = "none"

# If set to "true", the section pages will be in the search index. This is only used if
# `build_search_index` is set to "true" in the Zola configuration file.
in_search_index = true

# If set to "true", the section homepage is rendered.
# Useful when the section is used to organize pages (not used directly).
render = true

# This determines whether to redirect when a user lands on the section. Defaults to not being set.
# Useful for the same reason as `render` but when you don't want a 404 when
# landing on the root section page.
# Example: redirect_to = "documentation/content/overview"
redirect_to =

# If set to "true", the section will pass its pages on to the parent section. Defaults to `false`.
# Useful when the section shouldn't split up the parent section, like
# sections for each year under a posts section.
transparent = false

# Use aliases if you are moving content but want to redirect previous URLs to the
# current one. This takes an array of paths, not URLs.
aliases = []

# If set to "true", feed files will be generated for this section at the
# section's root path. This is independent of the site-wide variable of the same
# name. The section feed will only include posts from that respective feed, and
# not from any other sections, including sub-sections under that section.
generate_feeds = false

# Your own data.
[extra]
```

--------------------------------

### Define output path via frontmatter slug

Source: https://www.getzola.org/documentation/content/page

Use the slug key in frontmatter to override the default path generation.

```toml
+++
title = "L'élevage de chèvres, la carrière alternative de tous dévelopeurs'"
slug = "élevage-chèvre-carrière-alternative"
+++
This is my article.
```

--------------------------------

### Define and use shortcodes with no arguments

Source: https://www.getzola.org/documentation/content/shortcodes

Shortcodes without arguments still require empty parentheses to be correctly parsed.

```html
<aside>
    {{ body }}
</aside>
```

```markdown
Readers can refer to the aside for more information.

{% aside() %}
An aside
{% end %}
```

--------------------------------

### Retrieve taxonomy data with get_taxonomy

Source: https://www.getzola.org/documentation/templates/overview

Fetches the full taxonomy configuration and items for a specific kind.

```Tera
{% set categories = get_taxonomy(kind="categories") %}
```

```text
kind: TaxonomyConfig;
items: Array<TaxonomyTerm>;
lang: String;
permalink: String;
```

--------------------------------

### Configure Wrangler for Zola

Source: https://www.getzola.org/documentation/deployment/cloudflare-workers

The wrangler.toml file defines the build command and the output directory for the static site assets.

```toml
name = "blog"
compatibility_date = "2026-01-22"

[build]
command = "./build.sh"

[assets]
directory = "./public"
```

--------------------------------

### Build with custom base URL

Source: https://www.getzola.org/documentation/getting-started/cli-usage

Overrides the base_url configuration value during the build process.

```bash
$ zola build --base-url $DEPLOY_URL
```
Tokens:
Raw