Guides

Writing notes

Write the way you already do in Obsidian. Most of what you use renders on the site the same way, and a few note properties let you fine-tune titles, dates and addresses.

What works

Single line breaks are kept as line breaks, as in Obsidian's reading view. If you turned on Strict line breaks in Obsidian, set strict_line_breaks: true in the settings note and a single line break becomes a space, as there; an empty line still starts a new paragraph.

What doesn't work (yet)

Queries from plugins like Dataview and Bases, Excalidraw drawings (other than an exported image) and Markdown-style note embeds don't work on the site yet. The Roadmap has the details, and what's planned.

Canvases

A canvas (a .canvas file) is published as a page of its own, with its cards and arrows where you placed them. When the board is wider than the page, it scrolls.

• A canvas in an always-public folder is published by itself. Any other canvas is published when a published note links to it ([[Board.canvas]]) or embeds it (![[Board.canvas]]), like an image. A canvas in an excluded folder never is.
• Text cards are Markdown, with links, embeds and tags as in a note. File cards show the note or image they point to, and link cards are links.
• A card showing a private note or file is left out, together with the arrows to and from it. Its links to private notes are plain text, as in notes.
• Cards showing private notes or files are taken out before the canvas leaves your device, so their names never reach your server. Links to private notes inside text cards go up as written, like links in a note, and become plain text on the site.
• The canvas's address is its name with -canvas at the end: Board.canvas is at /board-canvas/, so a note named Board can sit beside it. Its title is the file name; canvases have no properties.

Note properties

Properties (frontmatter) at the top of a note control how it appears. All are optional.

---
title: A better title than the file name
description: One sentence for search results and link previews.
created: 2026-09-01
updated: 2026-10-02
tags: [articles, writing]
aliases: [Another name]
permalink: /about/
order: 1
publish: true
stage: budding
---

Other properties stay private: they are never put on the site unless the server lists them in expose_frontmatter (which is how stage is enabled in the default config).

Page addresses

A note's address comes from its path inside the folder you publish from: each part is lowercased, and spaces and punctuation become dashes. When you publish one folder (always_public_folders = ["Kvist"]), that folder is the site's root, so Kvist itself doesn't appear in addresses or the menu. The examples below assume that.

A note can't take an address the site uses itself, like /tags/: a note called Tags right in your published folder stops the build with a message saying so. Rename it or give it a permalink. To keep the folder in addresses instead, set root_folder = "/" on the server.

Renaming or moving a note changes its address. The server remembers the old one and sends visitors on to the new address, so links from elsewhere keep working. It finds the note again by its path (when only a permalink or a folder changed), by its unchanged text, or by its file name if no other new note has that name. A note that is no longer published isn't redirected to, and writing a new note at an old address replaces the redirect. If two notes would get the same address, the build stops and names both, and your site keeps showing the previous version until you fix it.

Folder notes

A note named like its folder (Recipes/Recipes.md) or called index.md is the folder's folder note. It becomes the folder's page: instead of a plain list of notes, /recipes/ shows the folder note, with the folder's notes in the list beside it. The folder note isn't one of those notes, so it isn't in that list, in the folder's count or among the recent notes on the home page. Its sort property sets the order of the folder's notes, and its icon property the folder's icon. A folder without a folder note still gets a page, with its notes listed.

Folder icons

Give a folder its own icon with the icon property on its folder note:

---
icon: 🍳
---

The icon shows beside the folder in the menu, in the list of notes and on the home page cards. It can be an emoji or the name of an icon the built-in theme draws: archive, book, book-open, briefcase, calendar, camera, chat, code, file, flask, globe, heart, home, image, leaf, lightbulb, mail, map, music, pen, play, star, tag and user. The names follow Lucide, and if you use the Iconize plugin's icon property, its Lucide names (LiBookOpen) work too. A name the theme doesn't know shows the plain folder. The folder note must be published; a folder without one keeps the plain folder.

The order of notes

A folder lists its newest notes first, by their “Tended” date (updated), like tag pages and the home page do. A note without an updated property uses the time its file last changed, which can move when you sync or copy the vault, so give it one to keep its place.

To choose another order for a folder, set sort on its folder note (Recipes/Recipes.md or Recipes/index.md):

To pin a note to the top, give it an order (or weight) number. Notes with one come first, lowest number first, and the rest follow in the folder's order:

---
order: 1
---

The order is used by the list beside a note, the folder's page and the menu. Subfolders are listed A to Z. A sort value kvist doesn't know is ignored, with a warning in the publish report.

The home page

By default the home page shows your site's title and description, cards for your folders or menu groups, and a list of recently updated notes. To use one of your notes instead, put a note named index.md at the top of your published folder (Kvist/index.md, or Kvist/Kvist.md, named like the folder), or set home in the settings note:

---
home: "[[Welcome]]"
---

The home note is the home page, so it isn't listed in its folder or among the recent notes.

Tags

Every tag on a published note gets a page at /tags/<tag>/ listing its notes, newest first. /tags/ shows every topic as a card with its size, its newest notes and its sub-tags, with a filter and an A–Z or “most notes” order. Nested tags like #projects/kvist get their own page, and the parent tag's page includes them. Tags can also group the menu.

Preview before publishing

To see your site on your computer before publishing, run kvist's preview server. It needs the kvist program (see the command line) and a copy of your server's kvist.toml, so it applies the same rules:

kvist dev --dir ~/Documents/MyVault --config kvist.toml

Open http://127.0.0.1:1313. The page reloads whenever you save a note.