VispNote User Guide

1. Install and Launch

Download the installer that matches your operating system from the website download section or the public GitHub releases page. VispNote currently publishes builds for Windows 10/11 x64, macOS Apple Silicon, macOS Intel, Linux AppImage x86_64, and Debian-family Linux systems through a DEB package.

On first launch, VispNote creates a local workspace and seeds a few example notes so you can explore the editor, tags, graph, and tasks.

2. Updates and Releases

The VispNote website includes a Latest Updates section that shows the newest public GitHub release and links to the current installer assets. Use it when you want to confirm the newest version before downloading.

The current public release is VispNote v0.1.10, published on May 3, 2026 at 19:48 UTC. It includes desktop builds for Windows x64, macOS Apple Silicon, macOS Intel, Linux AppImage x86_64, and Debian-family Linux through a DEB package.

How to update

1. Open the website Latest Updates or Download section, or open the GitHub releases page.
2. Download the installer or package for your operating system.
3. Install the new version over the existing app when your operating system supports that flow.
4. Launch VispNote and continue using your existing vaults.

Your notes live in local vault folders as markdown files, so updating the desktop app should not require moving your notes. Keep normal backups of important vault folders before major system changes.

3. Vaults and Local Data

A vault is a local folder that contains a separate set of markdown notes, tags, metadata, canvases, workflow settings, novelist settings, and indexes. Treat a vault as one focused context. A personal vault can hold journals and errands; a work vault can hold meetings and projects; a research vault can hold sources and claims; a novelist vault can hold acts, chapters, scenes, characters, locations, plot threads, research, and revision notes.

Create a vault

1. Open the vault switcher in the sidebar.
2. Choose to create a new vault.
3. Enter a name and choose either a normal Notes vault or a Novelist vault.

How to choose vaults well

Use fewer vaults than folders. A vault works best when the notes benefit from being searched, linked, and reviewed together. Split vaults when the context, privacy, or project lifecycle is different enough that you do not want the notes mixed.

Switch vaults

Use the vault switcher at the top of the sidebar. VispNote saves pending note edits before changing vaults, then loads the selected vault's notes, tags, and canvases.

Rename or delete vaults

You can rename vaults from the vault switcher. Vault deletion is available in Settings under Data and Sync, but VispNote requires another vault to exist first and asks you to type the current vault name before deleting the folder.

Vault mode

Settings can show or change whether the active vault is a normal Notes vault or a Novelist vault. Turning on novelist mode adds the novelist panel, story structure helpers, and the writing workflow for that vault.

Where files live

VispNote stores notes as markdown files on your computer under ~/VispNote. Older legacy data folders may be used only as compatibility fallbacks when ~/VispNote does not exist. Canvases are stored as JSON files inside the vault's .canvases folder, and the search/AI index lives beside the vault data. Your core writing remains readable outside the app.

4. Writing Notes

VispNote uses a block editor. A note is made from blocks that can be paragraphs, headings, bullets, todos, quotes, code blocks, tables, dividers, page embeds, block embeds, block refs, plot-point blocks, and embedded canvases. The best way to write in VispNote is to capture rough blocks first, then reorganize them into structure later.

Create and edit notes

• Create a new note from the sidebar or with the keyboard shortcut.
• Edit the title at the top of the note.
• Add tags from the note header.
• Pin important notes so they appear first when sorting supports pinned notes.
• Use the duplicate and delete buttons in the editor toolbar, or right-click a note in the note list to rename, duplicate, or delete it.

Page properties

Lines at the top of a note using key:: value become editable page properties. Use them for structured metadata such as status:: DOING, type:: meeting, source::, order:: 120, act:: [[Act 1]], or chapter:: [[Chapter 1]]. The status:: property drives the note's workflow status when workflow states are enabled.

Slash commands

Type / in a block to open commands. You can insert headings, paragraphs, bullets, todos, quotes, code blocks, markdown tables, dividers, dates, reminders, links, tags, labels, canvas embeds, workflow markers, plot points in novelist mode, and AI actions when AI is configured.

Block operations

Right-click a block or use the grip menu to copy a block ref, copy an embed, copy/cut/paste the block, zoom into it, indent/outdent, move it, duplicate it, add a label, convert it to another block type, assign a workflow marker, or delete it. Drag-select multiple blocks to copy, cut, delete, or apply AI actions to the selection.

Refs and embeds

Use ((block-id)) to reference a specific block. Use {{embed [[Page Title]]}} to embed a page preview, {{embed ((block-id))}} to embed a block, and {{canvas canvas-id}} to embed a canvas in a note. The block context menu can copy the exact ref or embed syntax for you.

Formatting and tables

The selection toolbar supports bold, italic, underline, strikethrough, inline code, highlights, text colors, smaller/larger text, delete, undo, redo, and AI actions. Code blocks include a language selector for plain text, JavaScript, TypeScript, JSX, TSX, HTML, CSS, JSON, Markdown, Bash, Python, and SQL. Pasted HTML tables, tab-delimited text, and markdown tables are converted into markdown table blocks when possible.

Spell check and suggestions

When spell check is enabled, VispNote underlines possible misspellings in rendered blocks. Open the suggestion menu to replace the word or add it to the local ignore list.

Markdown support

Use regular markdown patterns for headings, bullets, todo checkboxes, block quotes, fenced code, horizontal rules, tables, inline code, bold, italic, wiki links, tags, reminders, block refs, and embeds. Copying blocks preserves markdown where possible.

A productive writing loop

1. Start with a quick note and write every idea as a separate block.
2. Use headings to create sections only after the note has enough material.
3. Turn action items into todo blocks or workflow blocks.
4. Use wiki links for ideas that deserve their own page.
5. Use refs and embeds for reusable details that should stay connected to their source.
6. Review backlinks, search, and graph view later to discover related notes you did not remember.

5. Organizing and Finding Notes

Tags

Add tags from the note header or type #tag in a block. Tags are best used as living contexts, not rigid folders. A note can be both #research and #product, which lets it appear in both views without duplication.

Use tags to self-organize notes. Start with broad tags like #work, #journal, #research, or #ideas. When a tag becomes crowded, split it into a more specific tag. When a tag has only one note for weeks, merge it back into a broader context.

The sidebar shows tags with counts. You can create a tag from the sidebar, create one while adding a note tag, or right-click a tag to manage it.

Wiki links and backlinks

Type [[ to link to another note. VispNote suggests existing notes while you type and can create a linked note when the target does not exist. Renaming a note updates wiki links that point to the old title. Backlinks appear below the editor so each note can show where it is referenced.

A good rule: use tags for categories and wiki links for relationships. For example, tag a note #reading, then link it to [[Product strategy]] when it changes how you think about that topic.

Search

Use the note-list search field to find text across the active vault. Search uses a local SQLite full-text index over note titles, body text, and tags, with search-as-you-type prefix matching. Results show highlighted snippets and respect the active view, tag, workflow, or novelist filter.

Graph view

Open Graph from the sidebar or shortcut to see note relationships built from wiki links. Graph view helps you inspect clusters, linked notes, isolated notes, and tag-colored groups. You can choose force, timeline, or cluster style in Settings, turn labels/tag colors/content sizing on or off, tune link distance and repulsion, reset the layout, and export the visible graph as SVG.

In novelist mode, the graph can use focused filters such as all novelist notes, act structure, characters plus scenes, plot threads plus scenes, or research plus scenes.

Suggested organization strategy

• Daily capture: create quick notes without worrying about perfect names.
• Weekly cleanup: add tags, link important ideas, and pin active notes.
• Project review: open the tag, graph, and backlinks to see what is connected.
• Archive by neglect: if you stop using a tag, do not maintain it unless it helps retrieval.

6. Todos, Today, Workflow, and Reminders

Todos

Create todo blocks in notes with /todo or markdown checkboxes. The Todos panel collects open tasks, completed tasks, and reminder-only blocks across the active vault. Toggle checkbox tasks directly from the panel; reminder-only items open the source note.

The Todos layout can be a grouped list or a Kanban-style board. In Kanban mode, items are grouped into Due / Reminders, Open, and Done.

Today view

Daily rollup gives you a date-oriented view of notes grouped by the day they were written. Use it to review recent work quickly. Settings can show long or short date headings.

Reminders

Use @remind YYYY-MM-DD or @remind YYYY-MM-DD HH:MM in a block. VispNote surfaces due and overdue reminders in task views and reminder notifications.

The reminder button near the top right opens the reminder center, where reminders are grouped as due, upcoming, or snoozed. Due reminders can also appear as a card or banner, depending on Settings. Snooze duration, overdue-on-launch behavior, and reminder sound are configurable.

How to stay productive with tasks

Use todos for simple binary tasks. Use workflow states when an item has a lifecycle. Use reminders only for time-sensitive work. This keeps your task system light: not every note needs a deadline, and not every task needs a project board.

7. Workflows and Custom States

Workflow states turn notes and blocks into trackable work items. A note can carry a status through the status:: page property, and individual blocks can carry workflow markers such as TODO or WAIT. This keeps planning connected to the note that explains the work.

The default states are TODO, DOING, DONE, LATER, NOW, WAIT, and CANCELLED. States whose next state is empty are treated as closed. You can review workflow items in the Workflow panel as Kanban, Table, or List.

When to use workflows

• Use TODO for work that is accepted but not started.
• Use DOING for the very small number of active items.
• Use WAIT when another person, decision, or external event is blocking progress.
• Use LATER for good ideas you do not want in your active queue.
• Use DONE or CANCELLED to close the loop without deleting history.

Custom states

In the Workflow panel you can add or remove columns. State names are normalized to uppercase labels, so a draft like needs review becomes a compact workflow state. Custom states are saved per vault, which means a writing vault can use a different lifecycle from a work vault.

Workflow panel

Use Kanban mode to drag notes or workflow cards across columns. Use Table mode to scan status, note title, preview text, tags, and the state selector in one dense view. Use List mode for a simpler grouped reading view.

You can archive a note from the workflow without deleting it, then restore it from the Archived view. Table mode also lets you add or remove note tags without opening the note.

Block workflow markers

Use slash commands such as /TODO or the block context menu to add a marker to a block. Clicking a workflow pill cycles it to the next state or clears it when the state is closed.

Best practice: keep workflow states few and meaningful. If a state does not change what you do next, it is probably a tag, not a workflow state.

8. Novelist Mode

Novelist mode turns a vault into a writing workspace for long-form fiction. It adds starter notes, novel-specific tags, a structured Novelist panel, scene plot-point blocks, writing-focused workflow states, story status analytics, and an optional novelist AI configuration.

What novelist mode adds

• Structure tags: novel-act, novel-chapter, and novel-scene.
• Supporting tags: novel-character, novel-location, novel-plot, novel-research, and novel-revision.
• Starter notes: Act 1, Chapter 1, Scene 1, Characters, Locations, Plot Threads, Research, and Revision Notes.
• Writing workflow: IDEA, OUTLINE, DRAFT, REVISE, and FINAL.
• Story properties: notes use properties such as status::, order::, act:: [[Act 1]], chapter:: [[Chapter 1]], pov::, setting::, and purpose::.
• Plot Points blocks: scene notes can contain ::: plot-points blocks with beats, linked context pages, and AI actions.

How to write a novel in VispNote

1. Create a dedicated novelist vault, or enable novelist mode for an existing writing vault.
2. Create acts for large story movements, chapters for reading units, and scenes for draftable moments.
3. Use order:: to keep acts, chapters, and scenes in a stable sequence.
4. Link chapters to acts and scenes to chapters with properties and section links.
5. Keep characters, locations, plot threads, research, and revision notes as supporting notes so facts stay reusable.
6. Use workflow states to move each scene from idea to final.
7. Use canvases when the story needs a spatial board, map, timeline, or relationship diagram.

Novelist panel

The Plan tab shows the story as Acts, Chapters, and Scenes. It can create acts, chapters, scenes, and supporting notes from templates; link existing chapters or scenes; set order values; rename notes; attach unlinked chapters or scenes to a parent; create missing parents; and convert a chapter to a scene when needed.

The Status tab summarizes draft word count, average words per scene, unlinked items, scene completion, word count by act, workflow status counts, and a character appearance heat map. Character aliases can come from name:: or names:: properties as well as the note title.

The AI Config tab stores novelist-specific writing preferences for the active vault, including prompt preset, model collection, model override, target word limit, instructions, additional context, included components, system/user message templates, temperature, max tokens, and custom prompts.

Plot Points blocks

Use /plot points in a scene to create a beat list. Add one beat per line, link context pages such as characters or locations, then use the block's AI buttons to summarize the beats, improve the plan, or write scene prose. AI writing from a Plot Points block previews generated text before it is inserted or appended.

Best practice: draft scenes in scene notes, not in one huge manuscript note. Link scenes into chapters and acts. This keeps revision manageable and lets the Workflow and Novelist panels show exactly where each part of the story stands.

9. Canvases

Canvases are freeform visual spaces inside a vault. Use them for idea maps, project flows, diagrams, visual research, character relationships, story timelines, and planning that benefits from spatial layout.

• Create, open, rename, preview, or delete canvases from the Canvas dashboard.
• Attach a canvas to a note with /canvas, then open the embedded canvas from the note.
• Use select, pen, text, sticky note, rectangle, ellipse, line, arrow, diamond, triangle, and eraser tools.
• Adjust stroke, fill, and stroke width.
• Select one or more objects, move them, resize them, copy, cut, paste, delete, align, distribute, zoom, and fit to screen.
• Double-click text or sticky objects to edit their text.
• Use mouse wheel or toolbar buttons to zoom, middle mouse or space-drag to pan, and undo/redo to step through edits.

Canvas data is saved inside the active vault as JSON. Canvas deletion asks for confirmation and removes that canvas from the vault.

10. Optional AI

VispNote works without AI. When enabled, Ask AI can answer questions over your notes and writing actions can improve, format, summarize, shorten, fix, or draft text. Treat AI as an assistant for review and expansion, not as the owner of your notes.

AI can use Ollama locally or a configured hosted provider. Supported providers are Ollama, OpenRouter, OpenAI, Anthropic, Gemini, and a custom OpenAI-compatible endpoint. Hosted provider API keys are stored locally in VispNote settings.

Common AI actions

• Improve writing while preserving meaning and note structure.
• Format a page into cleaner markdown.
• Summarize or make a page concise.
• Fix spelling.
• Write new text in a section with preview before applying.
• Create a new page from an Ask AI request.
• Format and add useful wiki links to the current page.

Ask AI

Open Ask AI from the sidebar or with the shortcut. Ask AI can answer questions about the active vault, cite source notes, create pages, link notes, and run page actions such as improve, format, summarize, make concise, or fix spelling. Long-running requests can be stopped or sent to the background.

Retrieval modes

With Ollama and the nomic-embed-text embedding model installed, VispNote can use semantic retrieval. If embeddings are unavailable, it falls back to local keyword search and recent-note context. Hosted providers use local keyword and recent-note context; your note index remains local.

Provider setup

Configure the provider, API key, host or base URL, chat model, embedding model for Ollama, retrieval behavior, and token limits in Settings. Default chat models include gemma3 for Ollama, openai/gpt-4o-mini for OpenRouter, gpt-4o-mini for OpenAI, claude-sonnet-4-5-20250929 for Anthropic, and gemini-2.5-flash for Gemini.

If AI is disabled in Settings, all AI features stay unavailable and the rest of the app continues to work normally.

11. Settings

Settings are organized by appearance, editor, notes and tags, reminders, AI, data and sync, shortcuts, and about.

• Appearance: theme, density, font family, app font size, sidebar, and note list visibility.
• Editor: editor width, editor font size, indent guides, spell check, auto-link note suggestions, and whether new sections start collapsed.
• Notes and tags: sort by modified, created, or title; default new-note tags; pinned-first behavior; daily rollup format; todo layout; graph style; and vault stats.
• Reminders: notification style, sound, overdue-on-launch behavior, default snooze duration, and week-start preference.
• AI: enable AI, choose provider, set API key, host or base URL, chat model, Ollama embedding model, retrieval mode, and token limits.
• Data and Sync: current vault path, create a Notes or Novelist vault, change vault mode, confirm auto-save and markdown storage, and delete the current vault when another vault exists.
• Shortcuts and About: review keyboard shortcuts, platform information, app version, and project links.

12. Keyboard Shortcuts

Canvas editor shortcuts include Cmd/Ctrl C, Cmd/Ctrl X, Cmd/Ctrl V, Cmd/Ctrl Z, Cmd/Ctrl Shift Z or Cmd/Ctrl Y, Delete, mouse wheel zoom, and space-drag panning.

13. Troubleshooting

Download button opens releases instead of an installer

The latest release may still be building or uploading assets. Open the releases page and refresh after the build finishes.

AI is unavailable

AI is optional. Check Settings, confirm AI is enabled, verify the selected provider is configured, and make sure the selected chat model is available. For Ollama, start the service and pull the chat model, for example ollama pull gemma3. For semantic Ask AI with Ollama, also pull the embedding model, for example ollama pull nomic-embed-text.

Ask AI says keyword mode

Keyword mode means the chat model is available but the local embedding model is not. Ask AI still works with local full-text search and recent notes, but semantic retrieval needs the configured Ollama embedding model.

A reminder does not show

Check the reminder syntax and date. Use @remind YYYY-MM-DD or @remind YYYY-MM-DD HH:MM.

A note is missing from a workflow column

Check whether the note has a status:: property that matches an existing workflow state. If the note was archived from the Workflow panel, open Archived and restore it.

Search, backlinks, or graph feel stale

Save or reopen the vault so the local SQLite index can rescan notes. Search and graph are built from the active vault's indexed markdown, tags, and wiki links.

A canvas is not visible in a note

Open the Canvas dashboard and confirm the canvas still exists in the active vault. Canvas embeds point to a canvas id, so deleting the canvas removes the source for that embed.

I want my raw notes

Open the vault folder shown in Settings. Your notes are stored as markdown files. Canvases are stored in the vault's .canvases folder as JSON files.