Site Configuration

Search (build_search_index)

Enables or disables the search functionality for your blog.

• Type: Boolean
• Default: false
• Usage: build_search_index = false

When enabled, a search index will be generated for your blog, allowing visitors to search for specific content. Additionally, a search button will be displayed in the navigation bar.

Configure the search like this:

build_search_index = true

[search]
include_title = true
include_description = true
include_path = true
include_content = true
index_format = "elasticlunr_json"

Theme Mode (theme)

Sets the color theme for your blog.

• Type: String
• Options:
  • "light": Always using the light theme
  • "dark": Always using the dark theme
  • "auto": Automatically uses the system theme
  • "toggle": Automatically uses the system theme, but also shows buttons to change it.
• Default: "toggle"
• Usage: theme = "toggle"

Menu

Defines the navigation menu items for your blog.

• Type: Array of objects
• Default: []
• Usage:

  menu = [
    { name = "/posts", url = "/posts", weight = 1 },
    { name = "/projects", url = "/projects", weight = 2 },
    { name = "/about", url = "/about", weight = 3 },
    { name = "/tags", url = "/tags", weight = 4 },
  ]
  

Logo

Defines the site logo image file.

• Type: String
• Usage:

  logo = "site_logo.svg"
  

Socials

Defines the social media links.

• Type: Array of objects
• Default: []
• Usage:

  socials = [
    { name = "twitter", url = "https://twitter.com/not_matthias", icon = "twitter" },
    { name = "github", url = "https://github.com/not-matthias/", icon = "github" },
  ]
  

Social links will open in a new tab if external_links_target_blank is set to true in the [markdown] section of your config.

Table of Contents (toc)

Enables or disables the table of contents for posts.

• Type: Boolean
• Default: true
• Usage: toc = true

When enabled, a table of contents will be generated for posts, making it easier for readers to navigate through longer articles.

Note: This feature adds additional JavaScript to your site.

CDN Usage (use_cdn)

Determines whether to use a Content Delivery Network (CDN) for assets.

• Type: Boolean
• Default: false
• Usage: use_cdn = false

When set to true, the theme will attempt to load assets from a CDN, which can improve loading times for visitors from different geographic locations.

Favicon (favicon)

Specifies the path to the favicon image for your blog.

• Type: String
• Default: "/icon/favicon.png"
• Usage: favicon = "/icon/favicon.png"

This sets the small icon that appears in the browser tab for your website.

Custom Stylesheets (stylesheets)

Allows you to add custom stylesheets to your blog.

• Type: Array of files located in the static directory
• Default: []
• Usage:

  stylesheets = [
    "custom.css",           # static/custom.css
    "/css/another.css"      # static/css/another.css
  ]
  

Fancy Code Styling (fancy_code)

Enables enhanced styling for code blocks.

• Type: Boolean
• Default: true
• Usage: fancy_code = true

This option adds the language label and a copy button.

Dynamic Notes (dynamic_note)

Allows for the creation of togglable note sections in your content.

• Type: Boolean
• Default: true
• Usage: dynamic_note = true

When enabled, you can create expandable/collapsible note sections in your blog posts.

Character Shortcodes

We support custom character shortcodes for adding dialogue and interactive characters to your blog posts. You can use them via shortcodes:

{{ /* character(name="character-name", body="Character dialogue text") */ }}

These are the supported parameters:

• name (optional): The identifier for the character. Used to determine styling and appearance.
• body (optional): The dialogue text for the character. Works with inline shortcodes.
• position (optional): Position the character on the left or right. Values: "left" or default (right)

Isn't it amazing?

Yes! And it's really easy to use

We can even use multiple lines with code:

fn main() {
  println!("Hey there!");
}

Anchor Links

You can add anchor links by adding the following to your _index.md:

insert_anchor_links = "heading"

Taxonomy sorting

You can sort the taxonomies page with the following config:

[extra.taxonomies]
sort_by = "page_count"         # e.g. name, page_count
reverse = true

The sort_by argument is directly passed to the sort_by function:

{% set sort_by = config.extra.taxonomies.sort_by | default(value="name") %}
{% set terms = terms | default(value=[]) | sort(attribute=sort_by) %}

{% if config.extra.taxonomies.reverse | default(value=false) %}
    {% set terms = terms | reverse %}
{% endif %}

{% for term in terms %}
    <li>
        <a href="{{ term.permalink | safe }}">
            {{ term.name }} ({{ term.pages | length }} post{{ term.pages | length | pluralize }})
        </a>
    </li>
{% endfor %}

Possible values include anything within the TaxonomyTerm object:

name: String;
slug: String;
path: String;
permalink: String;
pages: Array<Page>;
page_count: Number;

Examples:

• name to sort by name
• page_count to sort by page count

Analytics

Enable or disable analytics tracking:

[extra.analytics]
enabled = false

After enabling analytics, configure GoatCounter or Umami.

GoatCounter

Configure GoatCounter analytics:

[extra.analytics.goatcounter]
user = "your_user"           # Your GoatCounter username
host = "example.com"         # Optional: Custom host

Umami Analytics

Configure Umami analytics:

[extra.analytics.umami]
website_id = "43929cd1-1e83...."                    # Your Umami website ID
host_url = "https://stats.mywebsite.com"            # Optional: Custom host URL

Fediverse Author Attribution

Enable fediverse author attribution to add a meta tag for fediverse platforms:

[extra]
fediverse = true
fediverse_creator = "@[email protected]"

• Type: Boolean
• Default: false
• Usage: fediverse = true

When enabled, this adds a fediverse:creator meta tag to your site's HTML header, allowing fediverse platforms to attribute content to your account. Set fediverse_creator to your fediverse handle in the format @user@instance.

Page configuration

Source code (repo_view)

Do you want to link to the source code of your blog post? You can turn on the repo_view inside the [extra] section of your blog post.

[extra]
repo_view = true
repo_url = "https://github.com/not-matthias/apollo/tree/main/content" # Alternatively add the repo here

The repo_url can be set in the [extra] section or in your config.toml.

Comments (comment)

Enables or disables the comment system for posts.

• Type: Boolean
• Default: false
• Usage: comment = false

After making comment = true in [extra] section of you post, save your script from Giscus to templates/_giscus_script.html. When enabled, this allows readers to leave comments on your blog posts. This feature has to be set for each individual post and is not supported at higher levels.

Example configuration in content/posts/configuration.md:

+++
title = "Configuring Apollo"

[extra]
comment = true
+++

Comments via utterances can be configured in template/_giscus_script.html like this:

<script src="https://utteranc.es/client.js"
        repo="YOUR_NAME/YOUR_REPO"
        issue-term="pathname"
        theme="github-light"
        crossorigin="anonymous"
        async>
</script>

Cards Page

The cards.html template allows you to display a list of items in a card format. This is ideal for showcasing projects, but can be used for any list of items you want to display in a visually appealing way.

To create a cards page, you need to create a _index.md file in a content directory (e.g., content/projects). The following front matter is recommended:

+++
title = "Projects"
sort_by = "weight"
template = "cards.html"
[extra]
cards_columns = 3
card_media_height = 200
+++

• cards_columns: Set exact number of columns (2, 3, 4) or omit for default 2-column layout
• card_media_height: Control the height of card media area in pixels (default: 300)

Each item in the list should be a separate markdown file in the same directory. The following front matter is supported:

• title: The title of the item.
• description: A short description of the item.
• weight: The order in which the item appears on the page.
• local_image: A path to a local image for the item's thumbnail. See the Local Image section for more details.
• local_video: A path to a local video for the item's thumbnail. See the Local Video section for more details.
• remote_video: A URL to a remote video for the item's thumbnail.
• link_to: A URL the card should link to.

Talks Page

To create a talks page, you need to create a _index.md file in the content/talks directory. The following front matter is recommended:

+++
title = "Talks"
sort_by = "date"
template = "talks.html"
+++

Each talk should be a separate markdown file in the content/talks directory. The following front matter is supported:

• title: The title of the talk.
• description: A short description of the talk.
• date: The date of the talk (displayed with a calendar icon).
• local_image: A path to a local image for the item's thumbnail. See the Local Image section for more details.
• video: A map with a link and thumbnail for the talk video.
• organizer: A map with a name and link for the event organizer (displayed with a location icon).
• slides: A URL to the presentation slides.
• code: A URL to the source code.

Local Image

The local_image front matter parameter allows you to specify a path to a local image that will be used as the thumbnail for a page. This is particularly useful for social media previews and other places where a representative image is needed.

The path resolution for local_image works as follows:

• If the path starts with a /, it is treated as an absolute path from the content directory. For example, local_image = "/projects/project-1.jpg" will resolve to content/projects/project-1.jpg.
• If the path does not start with a /, it is treated as a relative path. The theme will prepend the section.path to the local_image path. For example, if you are in a page at content/posts/my-post/index.md and you set local_image = "thumbnail.png", the theme will look for the image at posts/my-post/thumbnail.png.

Local Video

The local_video front matter parameter allows you to specify a path to a local video file that will be displayed as the thumbnail for a page. This is particularly useful for showcasing projects with dynamic content.

The path resolution for local_video works the same as local_image:

• If the path starts with a /, it is treated as an absolute path from the content directory. For example, local_video = "/projects/demo.mp4" will resolve to content/projects/demo.mp4.
• If the path does not start with a /, it is treated as a relative path. The theme will prepend the section.path to the local_video path. For example, if you are in a page at content/projects/my-project/index.md and you set local_video = "demo.webm", the theme will look for the video at projects/my-project/demo.webm.

Remote Video

The remote_video front matter parameter allows you to specify a URL to a remote video file that will be displayed as the thumbnail for a page.

Example usage:

[extra]
remote_video = "https://example.com/videos/demo.mp4"

The browser will automatically detect the video format, so you don't need to worry about specifying the MIME type.

Guide de Configuration Apollo (FR)

Ce guide explique toutes les options de configuration du theme Apollo pour Zola.

Configuration Generale du Site

Ces options se trouvent a la racine du fichier config.toml :

Exemple :

base_url = "https://monsite.com/"
title = "Mon Super Blog"
description = "Un blog sur le developpement web"
build_search_index = true
generate_feeds = true
compile_sass = true
minify_html = true
taxonomies = [{ name = "tags" }]

Configuration Recherche

Section [search] - Configure le comportement de la recherche :

Exemple :

[search]
include_title = true
include_description = true
include_path = true
include_content = true
index_format = "elasticlunr_json"

Configuration Markdown

Section [markdown] - Configure le rendu du Markdown :

Exemple :

[markdown]
highlight_code = true
highlight_theme = "css"
highlight_themes_css = [
  { theme = "ayu-dark", filename = "syntax-theme-dark.css" },
  { theme = "ayu-light", filename = "syntax-theme-light.css" },
]

Themes de coloration disponibles :

• ayu-dark / ayu-light
• base16-ocean-dark / base16-ocean-light
• dracula
• gruvbox-dark / gruvbox-light
• monokai
• nord
• one-dark
• solarized-dark / solarized-light
• Et bien d'autres...

Options Extra

Section [extra] - Options specifiques au theme Apollo :

Theme Visuel

Fonctionnalites

Fediverse (Mastodon, etc.)

Exemple complet :

[extra]
theme = "toggle"
toc = true
use_cdn = false
favicon = "/icon/favicon.png"
fancy_code = true
dynamic_note = true
mathjax = true
mathjax_dollar_inline_enable = true
repo_url = "https://github.com/user/repo/tree/main/content/"
fediverse = false
fediverse_creator = ""

Menu Navigation

Definit les liens dans la barre de navigation :

menu = [
    { name = "/posts", url = "/posts", weight = 1 },
    { name = "/projects", url = "/projects", weight = 2 },
    { name = "/talks", url = "/talks", weight = 3 },
    { name = "/about", url = "/about", weight = 4 },
    { name = "/tags", url = "/tags", weight = 5 },
]

Reseaux Sociaux

Definit les icones de reseaux sociaux affichees :

socials = [
    { name = "twitter", url = "https://twitter.com/username", icon = "twitter" },
    { name = "github", url = "https://github.com/username", icon = "github" },
    { name = "linkedin", url = "https://linkedin.com/in/username", icon = "linkedin" },
    { name = "mastodon", url = "https://mastodon.social/@user", icon = "mastodon" },
]

Icones disponibles :

Configuration Analytics

Activer les analytics :

[extra.analytics]
enabled = true

GoatCounter (respectueux de la vie privee) :

[extra.analytics.goatcounter]
user = "votre_username"
host = "goatcounter.com"

Umami (auto-hebergeable) :

[extra.analytics.umami]
website_id = "votre-website-id"
host_url = "https://stats.votresite.com"

Google Analytics :

[extra.analytics.google]
tracking_id = "G-XXXXXXXXXX"

Configuration des Pages Individuelles

Options pour les pages individuelles (dans le frontmatter +++...+++) :

+++
title = "Titre de l'article"
date = "2024-01-15"
updated = "2024-02-01"
description = "Description pour le SEO"
draft = false

[taxonomies]
tags = ["rust", "web", "tutorial"]

[extra]
comment = true
repo_view = true
toc = false
local_image = "image.jpg"
+++

Pages Projets Cards

Dans content/projects/_index.md :

+++
title = "Projets"
sort_by = "weight"
template = "cards.html"

[extra]
cards_columns = 3
card_media_height = 200
+++

Pour chaque projet :

+++
title = "Nom du Projet"
description = "Description courte"
weight = 1

[extra]
local_image = "screenshot.png"
link_to = "https://github.com/user/project"
+++

Pages Talks Configuration

Dans content/talks/_index.md :

+++
title = "Talks"
sort_by = "date"
template = "talks.html"
+++

Pour chaque talk :

+++
title = "Titre de la Presentation"
description = "Resume du talk"
date = "2024-03-15"

[extra]
local_image = "thumbnail.webp"

[extra.video]
link = "https://youtube.com/watch?v=xxx"
thumbnail = "https://img.youtube.com/vi/xxx/0.jpg"

[extra.organizer]
name = "Nom de la Conference"
link = "https://conference.com"

slides = "https://slides.com/user/talk"
code = "https://github.com/user/talk-code"
+++

Resume Valeurs par Defaut

Conseils

1. Commencez simple : Utilisez les valeurs par defaut et personnalisez progressivement
2. Testez localement : zola serve recharge automatiquement
3. Validez votre TOML : Une erreur de syntaxe peut casser le site
4. Sauvegardez : Commitez vos changements regulierement