Documentation

Vaults & Notebooks

A vault is a folder on your filesystem. It contains all your notes, notebooks, and attachments.

You can have multiple vaults and switch between them. Each vault is completely independent.

Notebooks

Notebooks are subfolders inside your vault. Create a notebook and it creates a folder. Nest notebooks by creating subfolders. It maps directly to your filesystem.

You can drag and drop notes between notebooks. Right-click a notebook to rename, set an icon, or delete it.

Vault metadata

HelixNotes stores its metadata in a .helixnotes/ folder inside your vault. This includes the search index, version history, and internal config. Your actual notes are untouched, they stay as plain .md files.

Notes & Files

Each note is a .md file with YAML frontmatter. The frontmatter stores metadata like title, tags, creation date, and a unique ID.

You can pin notes to keep them at the top of the list. Sort by last modified, date created, or title.

Show in File Manager

Right-click any note and pick Show in File Manager to open your default OS file manager (Nautilus, Dolphin, Finder, Explorer) at the note's folder, with the file already selected. Desktop only.

Tags

Add tags to notes via the note info panel. Tags help you organize and filter your notes across notebooks.

File format

Notes use standard markdown with YAML frontmatter. Here is what a note looks like on disk:

---
id: a1b2c3d4
title: My Note
tags: [project, ideas]
created: 2026-02-15T10:00:00Z
modified: 2026-02-15T10:30:00Z
pinned: false
---

# My Note

Your content here.

Migration

Switching from another app? Here is how to bring your notes into HelixNotes.

Obsidian

HelixNotes has a built-in Obsidian importer. Go to Settings > Import and select your Obsidian vault folder. It converts wiki links and image embeds to standard markdown automatically.

Joplin

A community-contributed Python script can convert a Joplin "Markdown + Front Matter" export into a HelixNotes-compatible vault. It preserves folder structure, tags, attachments, and converts internal links.

View the script and instructions on Codeberg.

Requirements: Python 3.8+, Joplin export in "Markdown + Front Matter" format.

Other apps

HelixNotes works with plain markdown files. If your current app can export to markdown, you can point HelixNotes at the exported folder and start using it right away. You may need to adjust image paths or link formats manually.

Formatting

The editor supports rich text formatting. You can use the toolbar, keyboard shortcuts, or slash commands.

Text styles

• Bold, Italic, Underline, Strikethrough
• Inline code
• Links (external URLs and internal note links)
• Text color (8 colors)
• Highlight / background color (8 colors)

Blocks

• Headings (H1 through H4)
• Bullet lists, numbered lists, task lists
• Blockquotes
• Code blocks with syntax highlighting
• Tables
• Horizontal rules
• Collapsible sections
• Images and file attachments

Text alignment

Left, center, right, or justify. Set it from the toolbar.

Slash Commands

Type / at the start of a new line to open the command menu. Start typing to filter.

Command	What it does
/heading1	Insert Heading 1
/heading2	Insert Heading 2
/heading3	Insert Heading 3
/list	Bullet list
/numbered	Numbered list
/todo	Task list with checkboxes
/code	Code block
/quote	Blockquote
/toggle	Collapsible section
/table	Table (opens size picker)
/hr	Horizontal rule
/pagebreak	Page break for printing
/math	Math block (opens LaTeX editor with live preview)
/imath	Inline math (opens LaTeX editor with live preview)
/date	Insert today's date (ISO format)
/time	Insert the current time
/now	Insert the current date and time
/color	Insert a color (with a swatch preview)

Navigate with arrow keys. Press Enter or Tab to insert. Escape to cancel.

Toolbar

The toolbar sits at the top of the editor. Left to right:

• Insert menu (+): image, file, table, horizontal rule, code block, quote, collapsible section
• Heading dropdown (H1–H4, paragraph)
• Bold, italic, underline, strikethrough
• Text color, highlight color (8 each)
• Alignment (left, center, right, justify)
• Bullet, numbered, and task lists
• Link, inline code
• Undo / Redo

Right side: favorites, outline, version history, graph view, AI actions, source mode toggle.

Source Mode

Press Ctrl+Shift+M (or Cmd+Shift+M on macOS) to switch between the rich editor and raw markdown source.

Source mode shows the plain markdown with line numbers. Useful when you need precise control over formatting.

Changes sync both ways. Edit in source mode, switch back, and the rich editor reflects your changes.

Tables

Insert a table from the toolbar insert menu or type /table. A size picker lets you choose rows and columns.

Once inserted:

• Tab to move between cells
• Right-click for table options: add/remove rows and columns, merge cells, split cell, toggle header row/column, set cell background color, delete table
• Tables are stored as HTML in the markdown file (markdown tables are too limited)

Images & Files

Drag and drop images into the editor or use the insert menu. Images are copied into .helixnotes/attachments/ inside your vault and referenced with relative paths.

Any image format your browser supports works: PNG, JPG, GIF, SVG, WebP, and more.

You can also attach non-image files. They appear as downloadable links in the note.

PDF files can be previewed inline if you enable that in settings. You can set the preview height in the Editor settings tab.

Math (KaTeX)

HelixNotes renders LaTeX math via KaTeX, both as block equations and inline. Math is stored in your note as plain markdown, so it round-trips through any other markdown tool.

Inserting math

Type /math for a block equation, or /imath for inline. A modal opens with a LaTeX textarea and a live preview. Press Ctrl+Enter to insert, Esc to cancel.

Editing existing math

Double-click any rendered math block or inline equation to reopen the modal pre-filled with the current LaTeX. Edit and click Update.

Markdown source

Block math is stored as $$...$$ on its own line(s); inline as $...$. Files written by other tools using the same syntax render correctly when opened in HelixNotes.

Examples

E = mc^2

x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}

\sum_{i=1}^{n} i = \frac{n(n+1)}{2}

\begin{aligned}
f(x) &= (x+1)^2 \\
     &= x^2 + 2x + 1
\end{aligned}

Mermaid Diagrams

Insert flowcharts, sequence diagrams, class diagrams, and more using Mermaid syntax inside a fenced code block.

Creating a diagram

Use a code block with mermaid as the language (pick from the language dropdown, or type the markdown source directly). A "Render diagram" button appears under the block. Click it to render.

Rendering is opt-in by design: invalid syntax never hangs the editor, and the source is always preserved next to the diagram.

Copy and Save

Once rendered, hover over the diagram. Three buttons appear at the top right:

• Copy: copies as PNG to clipboard. Paste into Slack, Discord, email, docs, anywhere.
• Save: opens a dialog. Pick .png for raster (with a white or dark background based on your theme) or .svg for infinitely scalable vector.
• Re-render (↻): clears the cache and re-renders, useful after editing the source.

Example

```mermaid
graph TD
  A[Start] --> B{Decide}
  B -->|Yes| C[OK]
  B -->|No| D[Stop]
```

Global Shortcuts

These work anywhere in the app. On macOS, replace Ctrl with Cmd.

Shortcut	Action
Ctrl+N	New note
Ctrl+P	Command palette
Ctrl+F	Search (global or in-note)
Ctrl+Shift+F	Global search
Ctrl+S	Force save
Ctrl+Shift+M	Toggle source mode
Alt+Left	Navigate back
Alt+Right	Navigate forward
Escape	Close panel / exit mode

Editor Shortcuts

These work when the editor is focused. On macOS, replace Ctrl with Cmd.

Shortcut	Action
Ctrl+B	Bold
Ctrl+I	Italic
Ctrl+U	Underline
Ctrl+Shift+X	Strikethrough
Ctrl+K	Insert / edit link (with note autocomplete)
Ctrl+E	Inline code
Ctrl+Alt+C	Code block
Ctrl+1 ... Ctrl+6	Heading 1 to Heading 6
Ctrl+0	Convert heading back to paragraph
Ctrl+Shift+7	Numbered list
Ctrl+Shift+8	Bullet list
Ctrl+Shift+9	Task list
Ctrl+Z	Undo
Ctrl+Shift+Z	Redo
Alt+Up	Move line up
Alt+Down	Move line down

In-note search

Shortcut	Action
Enter	Next result
Shift+Enter	Previous result
Escape	Close search

Search

Press Ctrl+F with no note open (or Ctrl+Shift+F anytime) to search across all notes in your vault.

Search is powered by Tantivy, a full-text search engine written in Rust. It indexes your notes and returns results instantly, with a CJK-aware tokenizer so Chinese, Japanese, and Korean text matches mid-phrase (not only from the start).

The search index lives in local app-data (outside your vault), so cloud-synced folders never churn through its files. It updates automatically when notes change.

In-note search

Press Ctrl+F while editing a note to search within that note. Highlights all matches and lets you jump between them.

External Viewer

Open any .md file from outside your vault without adding it to your notes. Useful for quickly reading a README from a cloned repo, looking at a file someone shared, or browsing your filesystem.

How to open

• Right-click a .md file in your file manager and choose "Open with HelixNotes"
• Or pass it as a command line argument: helix-notes ~/some/README.md
• Or use your OS's "Open With" dialog

What you get

The note opens in read only focus mode with a banner across the top showing the file path and two actions: Import to vault and Close. The toolbar and formatting bar are hidden, the editor is locked, and autosave is fully disabled. There is no way to accidentally write to a file outside your vault.

Import to vault

Click Import to vault to open a folder picker (vault root + your notebook tree). Pick a folder and HelixNotes copies the file in, handles filename conflicts automatically (appending (2), (3) if needed), then opens the new note in normal edit mode.

Available on Linux, macOS, and Windows. Skipped on Android.

Notebook Sorting

Notebooks default to alphabetical sort. If you want a custom order, switch to manual sort in Settings > General > Notebooks > Sort order.

Reordering

Drag any notebook over another. The drop zone splits into three:

• Top 30% of the row: drop above (a line indicator appears at the top of the target)
• Middle 40%: drop into (existing behavior, dashed outline)
• Bottom 30%: drop below (line indicator at the bottom)

Reordering across folders works too: HelixNotes moves the notebook into the target's parent first, then positions it. Reordering automatically flips the setting to Manual, so you do not have to toggle it separately.

Storage

The order is stored per vault in .helixnotes/state.json, alongside the sidebar widths and last open note.

Daily Notes

HelixNotes has a dedicated Daily Notes view with a month calendar for browsing and creating daily notes.

Accessing Daily Notes

• Click Daily Notes in the sidebar to open the calendar view.
• Click the calendar icon in the title bar to quickly create or jump to today's note.
• Use the + button while in the Daily Notes view to create today's note.

Calendar View

The calendar shows a month grid. Days that have a note are highlighted. Click any day to open its note. If it doesn't exist yet, it will be created automatically. Use the arrows to navigate between months, or click the month name to jump back to today.

How They're Stored

Daily notes live in a Daily/ folder in your vault. The filename is the date (2026-02-15.md) and the title is the full date ("February 15, 2026"). They are automatically tagged with daily.

The Daily/ folder is hidden from the notebook tree since it has its own dedicated view.

Tasks

The Tasks view gathers every - [ ] checklist item from across all your notes into one place, so you can see and act on your to-dos without hunting through individual notes. Open it from Tasks in the sidebar.

Working with tasks

• Check a task off and the change is written back to its source note.
• Set a priority (High, Medium, Low) and a due date right from each row.
• Click a task to jump to its note at the exact line.

List view

A flat list of every open task, sortable by due date, priority, or source note.

Calendar view

A month grid that places each task on its due date, with a No due date bucket for the rest. Drag a task onto a day to (re)schedule it. Your List / Calendar choice is remembered per vault (always List on Android).

Inline tokens

Priority and due date are stored as plain-text tokens inside the task line, so they round-trip through markdown and stay readable anywhere:

• !high, !med, !low (priority)
• due:2026-06-12 (due date, ISO format)

Example: - [ ] Email the landlord !high due:2026-06-12

Wiki Links

Enable wiki links in Settings > Editor. Once enabled, type [[ followed by a note title to link to another note.

Click a wiki link to navigate to that note. If the linked note does not exist, clicking it will create it.

Wiki links also enable the graph view, which shows connections between your notes.

Note Links

You can link to other notes using standard markdown links. Use a relative path ending in .md to create an internal note link:

[My Other Note](./My Other Note.md)
[Library Note](../Library/Setup Guide.md)

Clicking a note link navigates to that note within the app. External links (https://) open in your browser as usual. A small icon after each link indicates its type.

Link modal

Press Ctrl+K to open the link modal. Start typing a note name to see autocomplete suggestions. Selecting a note inserts a relative .md path automatically.

You can also type a URL to create an external link, or edit an existing link by placing the cursor on it and pressing Ctrl+K.

Outline Panel

Click the outline icon in the toolbar to open the outline panel. It shows all headings in the current note.

Click any heading to jump to it. The outline reflects heading hierarchy; nested headings are indented.

The outline updates in real-time as you edit.

AI Actions

HelixNotes has optional AI features. Set up a provider in Settings > AI.

Providers

Ollama runs locally on your device. No API key needed (an optional key field is available for secured setups), data stays on your machine.

OpenAI-compatible lets you point at any server that speaks the OpenAI API (LM Studio, LocalAI, vLLM, and similar) by setting its base URL and (if needed) an API key. Great for self-hosted models.

Anthropic (Claude) and OpenAI (GPT) are cloud providers. Selected text is sent to their servers. Requires an API key.

Setting up Ollama

Ollama lets you run AI models locally. Install it and pull a model:

curl -fsSL https://ollama.com/install.sh | sh
ollama pull gemma3:4b

Then in HelixNotes: Settings > AI > Ollama. The default server URL is http://localhost:11434. Enter the model name exactly as shown by ollama list.

Recommended models:

• gemma3:4b
• gemma3:1b
• llama3.2

How to use

Select text and right-click to see AI actions. Or use it on the entire note if nothing is selected.

Available actions

• Improve writing, fix grammar
• Make shorter, make longer
• Professional tone, friendly tone
• Summarize, explain
• Translate (English, Dutch, German, French, Spanish)
• Custom prompt

AI results stream in real-time. You can apply or discard the result. A version snapshot is automatically saved before any AI changes are applied, so you can always undo.

Empty note generation

If your note is empty, you can use a custom AI prompt to generate content from scratch.

Version History

HelixNotes keeps per-note version snapshots. Click the clock icon in the editor toolbar to open version history.

Versions are saved automatically. There is a minimum 5-minute gap between automatic snapshots to avoid noise. You can also create a manual snapshot anytime.

Each version shows a timestamp and file size. Click to preview the content, then restore if you want to go back.

History is stored in .helixnotes/history/ inside your vault, organized by note ID.

Backups

Go to Settings > Backup to configure automatic backups of your entire vault.

Options

• Frequency: every 1, 6, 12, or 24 hours
• Max backups: 5, 10, 20, or 50 (oldest deleted)
• Include attachments (images/files)
• Custom backup folder

Backups are ZIP archives. You can trigger a manual backup or restore from any previous backup in settings.

Default backup location: ~/.config/helixnotes/backups/

Settings

Open settings from the gear icon in the sidebar. Here is what you can configure:

General

• Compact mode (denser note list, no previews)
• Show the date next to each note in the list (toggle)
• Time format: relative, 12-hour, or 24-hour
• Start week on: Monday or Sunday (daily and tasks calendars)
• Restore last session on launch (reopen the note and folder/tag you were last in)
• GPU acceleration (requires restart)
• Start at system startup
• System tray icon (requires restart)
• Close to tray

Editor

• Title mode: input, heading, or hidden
• Hide title in note body (if first heading matches title)
• Line numbers in source mode
• Open notes in view mode (read-only by default)
• Wiki links ([[Note Title]]) and graph view
• Inline PDF preview, configurable height

Styling

• Theme: light, dark, or one of 20 palettes (Solarized, GitHub, Nord, Tokyo Night, Dracula, Catppuccin, Gruvbox, Synthwave, and more) via a dropdown
• Accent color (13 presets plus a custom color picker)
• Interface scale: zoom the whole app 80-200% (desktop only)
• Font size (small to extra large)
• Font: System, Inter, Georgia, Merriweather, Lora, Open Sans, Literata, Mono

Import

• Import from Obsidian (converts wiki links and image embeds to standard markdown)

Sync

Your notes are plain files in a folder, so you can sync them however you like. HelixNotes also has optional built-in WebDAV sync to your own server. There is still no HelixNotes cloud and no account.

WebDAV sync

Set it up in Settings > Sync. Point it at a WebDAV endpoint you control (Nextcloud, ownCloud, a NAS, or any WebDAV server) with your username and an app password.

• Sync manually, or automatically on an interval, on every change, and/or on open.
• Conflicts are never silently overwritten: when both sides changed, HelixNotes keeps both by writing a conflict copy.
• Only your notes and attachments sync; device-local state (search index, sort order) stays put.

Using your own tool instead

Prefer Syncthing, rsync, Git, or a synced folder (Dropbox/OneDrive)? That works too. HelixNotes watches the filesystem for external changes and picks them up automatically, so when another device edits a file the editor updates itself.

Syncthing

If you use Syncthing (or any folder-level sync), add ignore rules so device-local state does not conflict across machines. Manual notebook sort order (drag-and-drop) is stored in state.json and will break if synced between devices.

Add these to your .stignore file:

.helixnotes/state.json
.helixnotes/history/
.helixnotes/trash/

This keeps your notes, attachments, settings, and notebook icons syncing while avoiding conflicts on sort order, version history, and trash. The search index is no longer stored in the vault (it now lives in local app-data), so it never needs an ignore rule.