Repository navigation
Description
Description
Custom templates currently work only with local desktop vaults. In the self-hosted web client and desktop remote-workspace mode, Settings reports that custom templates require a local vault, even though the remote server owns a normal filesystem vault.
Built-in templates continue to work because they are bundled with the client, but custom templates stored under .zennotes/templates/ cannot be listed, created, edited, or deleted remotely.
Desired behavior
Custom templates should work when:
- using the self-hosted web client
- connecting the desktop app to a remote ZenNotes server
Templates should remain stored in the active vault’s .zennotes/templates/ directory, preserving the existing template format and UI.
Changes made by one connected client should become visible to other clients without requiring a reconnect.
Proposed approach
- Add authenticated server endpoints for listing, reading, writing, and deleting custom templates.
- Advertise support through an optional server capability flag so older servers remain compatible.
- Use those endpoints from both the web client and desktop remote-workspace client.
- Report template-directory changes through the existing vault watcher.
- Keep local-vault template behavior unchanged.
Security and compatibility
Remote template operations should:
- use the server’s existing authentication/session middleware
- restrict paths to flat Markdown files under
.zennotes/templates/ - reject path traversal
- use the configured note-size limit
- use the vault’s existing locking and atomic-write behavior
- remain disabled when an older server does not advertise support
- leave built-in templates available on older servers
Acceptance criteria
- Custom templates can be created, edited, listed, read, and deleted from the self-hosted web client.
- The same operations work in desktop remote-workspace mode.
- Template changes refresh across connected clients.
- Older servers degrade gracefully without breaking built-in templates.
- Local-vault template behavior is unchanged.
- Server authentication, path validation, size limits, CRUD, watcher events, and UI capability gating are covered by tests.
Out of scope
- Changing the custom-template syntax or frontmatter format.
- Redesigning the existing template editor or picker.
- Synchronizing templates between different vaults.
Prior work
This is a focused follow-up to #592.
@flokchvtr previously explored server/web custom-template support in the web-feature-parity branch, including commit 821b816.
The template portion does not appear to have a focused pull request yet. I am opening this issue first, as requested by the contribution guide, to confirm the scope and avoid duplicating ongoing work.
Activity
adibhanna commentedon Sep 8, 2026
Done on the
v2.46.0branch in dc3059c (release PR #749)..zennotes/templates/through four authenticated routes:GET /api/templates,GET /api/templates/read?path=,POST /api/templates/write,POST /api/templates/delete. The vault layer mirrors the desktop module byte for byte (slug rules, flat directory and.mdonly,adrtoadr-2de-duplication, rename removes the previous file, atomic writes under the vault lock, symlinked escapes refused); writes pastZENNOTES_MAX_NOTE_BYTESanswer 413.supportsCustomTemplates. The web client and the desktop remote client gate on it, so an older server keeps Settings, Templates read-only with a note saying the server needs 2.46 or later, and built-in templates keep working. Local vaults are unchanged..zennotes/templates/under a newtemplateschange scope, so a template saved in one client shows up in the others without a reconnect, and a change-feed gap re-lists them.Tests cover the Go vault layer, the routes (auth, CRUD, traversal, size limit, capability), both watchers, the remote client, the store and the Settings gate, and it was verified live in the web client and in desktop remote mode against a real server. Thanks for the spec, and thanks @flokchvtr, whose web-feature-parity branch explored the server and web half first.
It ships with 2.46.0.
Feat(templates): custom templates work on remote vaults (#723)