Reference
Configuration
kvist has two places for settings. The server's file decides what may be published and where; a settings note in your vault decides how the site looks.
Which place?
kvist.toml server | _site.md vault | |
|---|---|---|
| Where | On the server, next to docker-compose.yml | A note in your vault, usually Kvist/_site.md |
| Holds | Publish rules, the site's address, limits, Cloudflare, the theme | Title, description, home page, menu links, theme settings |
| Takes effect | After docker compose restart kvist, on the next publish | On the next publish |
| Why there | A device or synced vault can't loosen the rules | You can change the look from Obsidian, on any device |
The plugin's own settings (server URL, site, token) are in Obsidian under Settings → kvist; see below.
kvist.toml uses TOML: key = "text", key = true, key = 10, lists like ["a", "b"], and [sections]. Lines starting with # are comments. The settings note uses ordinary Obsidian properties.
Server: kvist.toml
data_dir = "/data"
listen = "0.0.0.0:8080"
[[site]]
id = "garden"
base_url = "https://garden.example.com"
title = "My garden"
serve = true
[site.publish]
always_public_folders = ["Kvist"]
exclude_folders = ["Templates", "Private"]
expose_frontmatter = ["stage"]Top level
| Key | Default | |
|---|---|---|
data_dir | required | Where kvist stores everything. /data in Docker. |
listen | "127.0.0.1:8080" | Address and port to listen on. "0.0.0.0:8080" in Docker, so it can be reached from outside the container; docker-compose.yml decides who can. |
sync_ttl | "1h" | How long an unfinished upload may take. |
themes_dir | "themes" | Folder with extra themes, searched before the built-in ones. |
tls_cert, tls_key | none | Serve HTTPS directly, with a certificate you renew yourself. Not needed behind a proxy that handles HTTPS (Domains and HTTPS). |
[[site]]
One block per site. A server can host several sites, each with its own [[site]] block, domain and tokens.
| Key | Default | |
|---|---|---|
id | required | Short name used by the plugin and the commands: lowercase letters, digits and dashes. |
base_url | required | The site's address, e.g. https://garden.example.com. Must be the root of a domain; sub-paths are planned. |
title, description, author | empty | Defaults; the settings note can override them. |
language | "en" | Language code for pages and feeds, and for the theme's words (see Customizing). |
strict_line_breaks | false | Render a single line break as a space (Obsidian's Strict line breaks) instead of a line break. The settings note can override it. |
root_folder | automatic | The vault folder that is the site's root. Its notes and folders are published as if it were the whole vault: Kvist/Garden/Soil.md is at /garden/soil/, and the menu starts with Garden, not Kvist. By default it is the only folder in always_public_folders, if there is exactly one. "/" keeps the vault's own layout (/kvist/garden/soil/). Notes outside it keep their path, so a #public note at the vault's top is at /its-name/. When this changes, old addresses redirect to the new ones. |
serve | false | Let kvist serve the site itself. Keep true with the Docker setup. |
theme | "garden" | The theme: a built-in name, a folder in themes_dir, or a path. |
theme_overrides | none | Folder whose files replace the theme's files with the same path. |
[site.theme_params] | Theme settings; the settings note's values win. |
[site.publish]
See Publishing notes for how the rules combine.
| Key | Default | |
|---|---|---|
always_public_folders | [] | Folders whose notes are public. "/" means the whole vault. |
exclude_folders | [] | Folders that are never published, whatever their notes say. |
public_tag | "public" | Tag that publishes a note. |
private_tag | "private" | Tag that keeps a note private. |
frontmatter_key | "publish" | Property that publishes (true) or hides (false) a note. |
expose_frontmatter | [] | Note properties the theme may show. The garden theme uses stage. |
attachment_extensions | png, jpg, jpeg, gif, webp, svg, avif, pdf, txt, mp3, m4a, ogg, wav, mp4, webm, canvas | File types that may be published. Leave out canvas to publish no canvases. |
strip_image_metadata | true | Remove location, camera and author data from JPEG, PNG and WebP images. |
unpublished_links | "warn" | Links to private notes: "ignore", "warn", or "error" to stop the build. |
unpublished_embeds | "warn" | The same for embeds. |
[site.limits]
| Key | Default | |
|---|---|---|
max_file_size | 52428800 (50 MiB) | Largest file, in bytes. |
max_files | 20000 | Most notes and files in one site. |
[site.retention]
| Key | Default | |
|---|---|---|
revisions | 10 | Published versions kept for rollback. |
builds | 3 | Built copies of the site kept on disk. |
[site.cloudflare]
Clears Cloudflare's cache after every publish. See Running the server.
| Key | |
|---|---|
zone_id | The zone's ID. Purging is off without it. |
api_token_env | Name of the environment variable with the API token, e.g. "CF_API_TOKEN". |
api_token_file | Or: a file containing the token. |
Vault: the settings note
A note called _site.md, in any folder. It's never published as a page. Create or open it with kvist: Open site settings note.
---
title: Ada's garden
description: Notes on what I'm learning
author: Ada
language: en
home: "[[Welcome]]"
groups: [articles, projects]
accent: "#8a4f9e"
primary_links:
- "[[About]]"
secondary_links:
- "[[Reading list]]"
---| Property | |
|---|---|
title, description, author, language | Override the server's values. |
home | A published note to use as the home page: "[[Welcome]]" or a vault path. |
groups | Tags that group the menu. |
strict_line_breaks | true: a single line break is a space, not a line break. |
image | Default social preview image: "[[preview.png]]", a vault path or a web address. |
favicon | The browser tab icon: "[[icon.png]]", a vault path or a web address. PNG or SVG. |
primary_links, secondary_links | Menu links: at the top of the menu, and under Links. Each is a list of "[[Note]]", "[Text](https://…)", Text: https://… or a bare address. |
avatar (or logo), bio, profile_links | The profile in the menu. |
analytics, analytics_id, analytics_url | Visitor statistics with Plausible, Umami or GoatCounter. |
| Anything else | A theme setting. |
Empty properties keep their default. Obsidian's own properties (tags, aliases, cssclasses) are ignored. Server-only keys such as base_url or exclude_folders are ignored with a warning in the publish report.
Links to notes that aren't published are left out of the menu with a warning. Without secondary_links, the Links come from the list items in the note's text that are a single link, as in older settings notes; links inside %% comments %% and code blocks don't count.
Plugin settings
| Setting | Synced with the vault? | |
|---|---|---|
| Server URL | yes | Your site's address, e.g. https://garden.example.com. |
| Site | yes | The id from kvist.toml. |
| Token | no | This device's token. Never synced. |
| Device name | no | Shown in the server's log and in warnings. |
| Publish automatically | no | Publish after edits settle. One device only. |
| Wait before publishing | no | Seconds of quiet before an automatic publish (default 30, at least 5). |
Reset settings, at the bottom, clears all of these and this device's publish state, for example to connect the vault to a new site. Your notes are not touched.
The plugin speaks the language Obsidian is set to (Settings → General → Language): English and Swedish so far, and English for any other. The site's own language is set by language in the settings note.
Commands: Publish now, Toggle publish for current note, Open published page, Open publish report and Open site settings note.