Reference

Troubleshooting

Fixes for kvist-specific problems. Two places usually tell you more: the plugin's publish report, and the server's log (docker compose logs kvist).

Setting up

The site says “404 not found”

Nothing has been published yet. Publish from Obsidian, and the site appears. If you have published, check that serve = true is set for the site in kvist.toml.

The plugin doesn't show up in Obsidian

The three files (main.js, manifest.json, styles.css) must be directly in <vault>/.obsidian/plugins/kvist/. Unzipping often leaves one folder too many: plugins/kvist/kvist/.

“Test” in the plugin fails

Publishing

A note isn't on the site

• Run kvist: Toggle publish for current note on it. If a rule keeps it private (an excluded folder, the #private tag), the message says which.
• Folder names are case-sensitive: always_public_folders = ["Kvist"] doesn't match kvist.

A note is on the site, but not in the menu, lists or search

It has unlisted: true in its properties. An unlisted note has its page, but nothing lists it.

Some links are plain text on the site

The note they point to isn't published, or doesn't exist. That's by design: it keeps private notes hidden. The publish report lists them. Markdown-style links are read from the linking note's folder first: [text](Bread.md) from Kvist/Ideas/ looks for Kvist/Ideas/Bread.md, then any note called Bread (see Writing notes).

An image or file is missing

• It sits in an excluded folder (the report lists these under Attachments in excluded folders). Move it, or set Folder for new attachments in the kvist plugin settings to a folder outside the excluded ones.
• Its file type isn't allowed, or it is over 50 MiB. See attachment_extensions and limits.

“The site build failed”

The live site keeps showing the last good version, and the message says what's wrong. The usual causes:

• Two notes would get the same address, like My note.md and My Note!.md, or a clashing permalink. Rename one.
• A note would take an address the site uses itself, like a note called Tags at the top of your published folder (/tags/). Rename it or give it a permalink.
• A link or embed to a private note, when unpublished_links or unpublished_embeds is "error".

“The server has newer content than this device” (◆)

Another device published changes this one hasn't synced yet, and publishing now would put older notes back. Let your vault finish syncing, then run Publish now. See More than one device.

If you just pointed the plugin at a different site, this device still remembers the old one. Use Reset settings at the bottom of the plugin's settings, enter the new site's details and publish again.

An old link to a renamed note shows “Nothing grows here”

kvist redirects a renamed or moved note's old address when it can tell which note it became. It can't when the note was renamed and edited and another new note shares its new file name, or when it was renamed while private. Publishing after each rename gives it the best chance.

Notes in a folder are in the wrong order

Folders list the newest notes first, by the updated property, or by when the file last changed if a note has none. Syncing or copying the vault can change those file times, so give the notes an updated date. To list a folder A to Z or by created date instead, or to pin a note to the top, see The order of notes.

A page is still visible after I unpublished it

Pages are cached for up to 60 seconds. With Cloudflare, set up the cache purge so it disappears immediately.

Settings

I want to publish the vault to a different site, or start a site over

In the plugin's settings, press Reset settings at the bottom, then enter the new server URL, site and token. To clear out the old site on the server, see Starting over or removing a site.

My changes to kvist.toml did nothing

kvist only reads it at startup. Run docker compose restart kvist, then publish again. If kvist doesn't come back up, docker compose logs kvist points at the mistake.

My changes to the settings note did nothing

• The note must be called exactly _site.md, and it goes up when you publish.
• Colors must be in quotes: accent: "#8a4f9e". Without them, YAML reads everything after # as a comment.
• Check the publish report: server-only settings, an unpublished home note, or a menu link to a private note show up there as warnings.
• For groups, at least one published note must carry each tag.

Still stuck?

Open an issue on GitHub with what you did, what you expected and the error message. Remove tokens and private note names before posting logs.