Web interface

Notesium ships with an embedded web interface which is self contained and runs locally. It is started using the CLI web command.

To allow writing of notes, be sure to specify the --writable flag. The web interface stores state and preferences, but is port-specific, meaning that to retain them across sessions, the same port must be used. For example:

notesium web --writable --open-browser --port=8080

If you’re just getting started, follow the Quickstart guide.

User interface

Ribbon

The Ribbon is the slim, always-visible strip along the left edge that surfaces common actions at a glance - creating a new note, toggling panels, or invoking the Finder for fast navigation. Some of these actions also have keyboard equivalents, but the Ribbon ensures everything remains discoverable and just a click away.

Labels panel

The Labels panel lists all label notes (ie. notes with single-word titles), along with their connections count, and provides a “quick” way to create labels while avoiding duplicates. The panel can be toggled via the Ribbon (and the Notes list panel labels dropdown).

Creating a label note

As discussed, Notesium supports the concept of labels - but there is no special label syntax. A label is simply a regular note, and considered a label only if its title is a single word. It can also have its own content. Association is performed in exactly the same way as linking regular notes, and is bi-directional.

Given there is no requirement for note titles to be unique, below the label list is a New label input for quickly creating label notes and avoiding duplicates. While typing a checkmark will appear if it is unique. Clicking the checkmark or pressing Enter will open a new note with the title pre-filled. Once saved, the new label will appear in the label list.

Opening a label note

Each label in the list includes a count of its connections (incoming and outgoing links). Hovering a label replaces this count with a ↗, indicating that clicking it will open the label note itself.

Viewing label note connections

The panel is context-aware, adapting label click behavior:

• By default, clicking a label will open a Finder with incoming and outgoing links for the label.

• If the Notes list panel is open, clicking a label will instead set the notes list filter to label:$label, narrowing the list to only notes for that label.

Sorting the labels panel

The labels and Notes list panel share sorting preferences. By default, labels are sorted alphabetically, but can be changed to “linked notes count” in the Notes List panel > Labels dropdown.

Tip: The panel can also be toggled via the Notes List panel labels dropdown.

The panel can be resized by dragging its border. Double clicking will revert to the default width.

List panel

The Notes list panel lists all notes, which can be filtered and sorted, and supports additional density and label preferences. The panel can be toggled via the Ribbon.

Filter query syntax

The filter query will match against the Note title as well as any associated labels.

When a filter is applied, the match count will be displayed along with a “quick link” to initiate a full text search using the Finder below the filtered results.

A special syntax label:$label is supported as well. This will pre-filter the items to notes associated (incoming and outgoing links) with the label note. If $label is ommitted, all label notes will be displayed. The filter can be further filtered with multiple exact match (AND).

Sort and density dropdown

The Sort preference will be applied to all density views.

Labels dropdown

The Sort preference will be applied to the Labels tree and the Labels Panel.

Detailed view

Set in the Sort and density dropdown, the detailed view will display the note title, date, and associated labels if any. For example:

Albert Einstein
May 18, 2023 · Physicist

Date: By default, the modified date will be used, unless sort:created is set. The displayed date will be relative if less than 48 hours have passed (e.g., Just now, 15m ago, 3h ago, Yesterday), or the actual date. When the actual date is displayed, the year will be omitted if “this-year”. If the created date is in the future (periodic notes), the full date will be shown.

Compact view

Set in the Sort and density dropdown, the compact view will only display the note title. Clicking the item will open or switch to the note, hovering will reveal a ↗, upon hover will display a preview.

When using the compact view, the Labels tree can be enabled.

Compact view - Labels tree

The Labels tree is only available when using the Compact view, and can be enabled in the Labels dropdown. The tree consists of 2 levels, a chevron () with the label title, and its associated notes.

Clicking the chevron or label will toggle its associated notes. When the associated notes are toggled open, they act the same as Compact view items. Clicking will open or switch to the note, hovering will reveal a ↗, upon hover will display a preview.

Hovering the chevron or label will reveal the link count and icons:

When performing a filter query, it too will be applied to the Labels tree.

Tip: The panel can be resized by dragging its border. Double clicking will revert to the default width.

Graph panel

The Graph panel is documented in: Graph view > Panel view.

Tabs

Each note is rendered is its own tab.

• Tabs can be re-ordered by drag-and-drop.

• Hovering a tab will display the note title and filename.

• Switching tabs can be done by clicking on it, or with the keybindings.

• Closing a tab can be done by clicking on the X (or :q if vim-mode). When attempting to close a tab which has unsaved changes, a confirmation dialog will appear with Cancel or Close without saving.

Keybindings

Status bar

The status bar is displayed under the editor, displaying the current status, settings, and additional info/actions when the Sidebar is closed.

Tip: settings can be also be toggled from Settings>Editor, and :set SETTING if vim-mode.

Sidebar

The note sidebar is not available until the note is saved. It can be toggled via the info/close icon. The sidebar consists of 4 main sections: Actions, Stats, Dates, and Links.

Actions

Stats

The stats section displays the number of lines (excluding blank lines), words, and characters in the note.

Dates

The dates section shows when the note was created and last modified.

• Clicking Created opens Finder with the note’s creation time (ctime) set as the prefix and the filter pre-filled with that date, showing all notes created on the same day.

• Clicking Modified does the same using the note’s modification time (mtime), showing all notes modified on that day.

Links

The links section is split into sub-sections for incoming and outgoing links. Each sub-section includes a count, and displays the relevant links.

• Clicking a link will open/switch to the linked note. If the link is incoming, it will activate and scroll to the line where the link is specified.

• If any of the outgoing links are dangling, they will be displayed in red along with the line number and a dangling badge. Clicking a dangling link will activate/scroll to the line where the link is specified.

• Each link is a link-tree, which can be toggled (-/+). When toggled open, that notes' links will be displayed, along with a badge (incoming/outgoing). Each link in a link-tree is itself a link-tree, meaning they can be recursively opened.

Tip: The sidebar can be resized by dragging its border. Double clicking will revert to the default width.

Settings

The Settings consist of 4 main sections: Key Bindings, Editor, Statistics and About. It can be opened by clicking the Settings icon in the Ribbon.

Key Bindings

Provides an “in-app” reference for the Global, Finder, and Tabs keybindings.

Editor

Consolidates the Editor settings (those exposed in the Status bar), as well as an “in-app” reference for editor related keybindings and inline documentation where relevant.

• Settings: Toggle switches for Vim mode, Line wrapping, Conceal formatting, and Fold gutter.
• Keybindings: Default mode, Vim mode, and Table formatting and navigation.

Statistics

• Counts: Renders the CLI command stats global counts, and
• Finder integration: Integrates with the relevant Finder for deeper inspection.

About

• Software update: Renders the CLI command version output, includes the last-check, and the ability to check for a new version.

• Resources: Useful links as well as Report and issue (which will include version information in the GitHub issue body).

• Runtime: A combination of API runtime and state variables.

Editor modes

Default mode

The default editor mode resembles a simple plain text editor, with additional keybindings. The editor mode is displayed and can be set in either the Status bar or in Settings>Editor.

Keybindings

Vim mode

The editor supports Vim mode, which attempts to emulate the most useful features of Vim as faithfully as possible, but is not a complete implementation. It does however feature the following:

• All common motions and operators, including text objects
• Operator motion orthogonality
• Commands for write and quit (:w :wq :q :q!)
• Visual mode - characterwise, linewise, blockwise
• Full macro support (q @)
• Folding support (za zo zc zR zM)
• Incremental highlighted search (/ ? # * g# g*)
• Search/replace with confirm (:substitute :%s)
• Search history
• Jump lists (C-o C-i)
• Sort (:sort)
• Marks (` ‘)
• Cross-buffer yank/paste

Vim mode can be enabled in either the Status bar or in Settings>Editor.

Prefer the real thing? Notesium has a Vim/Neovim plugin.

Keybindings

Editing and formatting

Syntax highlighting and concealment

The editor is configured to syntax highlight based on Markdown formatting.

By default, formatting characters such as those used for bold, italic and code will be concealed except on the active-line. In addition, links will also be concealed and only display the title. This setting can be toggled in the Status bar, in Settings>Editor, or :set [no]conceal when vim-mode is enabled.

The following table lists the Markdown syntax of elements that will be formatted and/or syntax highlighted, and indicates whether concealment of the formatting characters is supported.

Table formatting and navigation

The editor will recognize when the cursor is placed within a table structure (identified by lines starting with the | character), and provide formatting and navigation.

• Automatic table formatting: Pressing Tab not only navigates through the table but also automatically formats it. This includes adjusting cell padding to align text according to the column specifications defined in the header row.
• Column alignment: The alignment for each column is determined by the syntax used in the header separator row (--- left, :---: center, ---: right).
• Dynamic column adjustment: If the cursor is at the end of a row and Tab is pressed, a new column will be added. When the cursor is on the header row, pressing Tab ensures the header separator row exists and matches the column count of the header, adjusting as necessary.
• Concealment support: When concealment is enabled, the formatting logic takes this into account, calculating the maximum length of each column without the concealed text, ensuring a visually consistent table layout.
• Navigation: Move across table cells and rows with the provided keybindings.

Keybindings

Section folding

The editor supports section folding, making it easier to view and edit notes, especially longer ones. Folds can be toggled via the Fold gutter or keybindings, which work whether the cursor is on the section heading or anywhere within the section.

The Fold gutter displays chevrons () for collapsible sections. Clicking a chevron toggles folding for that section. The Fold gutter can be toggled via the Status bar, in Settings>Editor, or :set [no]fold when vim-mode is enabled.

Folded sections are visually distinct, featuring a subtle full-width background, displaying the line count, and unfolding when clicked.

Keybindings

Line wrapping

When soft line-wrapping is enabled, long lines will “wrap” to the next line depending on the width of the editor. Soft line-wrapping is only visual, and does not manipulate the text by inserting new lines.

The wrap setting can be toggled via the Status bar, in Settings>Editor, or :set [no]wrap when vim-mode is enabled.

Linking notes

As previously mentioned, Notesium becomes truly powerful when you start linking your notes. Each connection adds context and helps structure emerge organically.

Inserting a link

Linking to an existing note is done while editing a note, by typing [[ (or Alt-k). This will trigger the Link insertion Finder.

The Link insertion Finder will display notes sorted by the most recently modified note first. Once the target note is selected, a correctly formatted Markdown link will be inserted.

Once the note is saved, both notes are bi-directionally linked.

Tip: inserting a literal [[ can be done one character at a time while waiting for the timeout.

Following a link

Clicking anywhere on the link, will open the linked note (or switch to it if already open). When vim-mode is enabled, ge or gx will open (or switch) to the link under the cursor.

Finder

The finder is typically opened using global keybindings or icons in the Ribbon, but is also seamlessly integrated throughout the web interface.

Keybindings

Search syntax

Graph view

The Graph view visualizes relationships between notes using an interactive force-directed graph. It is designed to help explore relationships, identify structure, and navigate large note collections visually.

The graph view has two modes: the Panel view and the Fullscreen view, each optimized for different use cases.

Display and force settings

The graph layout can be refined using the following settings. The graph can also be dragged, panned, or zoomed to adjust focus and layout.

Regular notes are displayed as orange nodes, whereas label notes are displayed as blue nodes.

Filter search syntax

Filtering emphasizes matching nodes and their immediate relationships while de-emphasizing the rest of the graph.

Panel view

The graph panel can be toggled via the Ribbon, Status bar, or Sidebar.

The panel view is optimized to provide a visual mental model of the current note’s relationships while editing. It is displayed alongside the editor and automatically tracks the active note, updating when links are added or removed and when switching tabs.

Tracking the active note can be disabled in the Display settings.

Clicking a node title opens the note in a new tab, or switches to it if already open.

Tip: The panel can be resized by dragging its border. Double-clicking restores the default width.

Fullscreen view

The fullscreen view can be opened via the Ribbon or with the keybinding space n g.

The fullscreen view is optimized for exploration and inspection of relationships, supporting free navigation and previewing without changing editing context.

Clicking a node title opens the note in a read-only overlay preview. The graph emphasizes the selected node and its immediate incoming and outgoing links, while de-emphasizing the rest of the graph.

The overlay preview has syntax highlighting and concealment enabled, and includes appended incoming links to aid navigation. Clicking a link in the preview switches to that note and updates the graph accordingly. Clicking the pencil icon closes the graph and opens the note in a tab for editing.

Keybindings

Periodic notes

Notesium itself does not directly support periodic notes. Instead, the Web interface (and Vim integration) provides support for working with periodic notes based on the shared, deterministic convention discussed in Concepts > Periodic notes.

Daily and weekly notes

The Web interface supports daily and weekly periodic notes. For each day or week, at most one corresponding note exists.

Periodic notes can be accessed through the Date picker or via the Keybindings. If the selected periodic note does not exist, it will be created and preseeded with a date-based formatted title.

The title is provided purely for convenience and can be edited freely. Changing the title does not affect how the note is treated or how it is located by the system.

Weekly notes rely on the week start (configured in the Date picker) to determine which week a note belongs to, which creation time is used, and how the note title is preseeded.

Date picker

The date picker displays a monthly calendar layout based on the configured week start, provides visual indicators for existing periodic notes, and allows opening or creating daily and weekly notes for a selected date. It can be opened via the Ribbon.

Week start

By default set to Monday, the configured week start affects the calendar layout and is relied upon when creating weekly notes, including which week a note belongs to, which creation time is used, and how the note title is preseeded.

The week start can be changed by clicking one of the day labels (Sun, Mon, and so on). Changing it immediately reflows the calendar and saves the preference for future weekly notes.

Existing notes

Existing periodic notes are reflected visually in the calendar. A blue dot indicates that a daily note exists for a given date. A green dot appears under the configured week-start day when a weekly note exists for that week.

Date selection

By default, the current date is selected, but any past or future date can be chosen. This allows periodic notes to be backdated or created ahead of time while preserving chronological order.

Once a date is selected, clicking Daily note opens or creates the daily note for that date, while Weekly note opens or creates the weekly note for the week (as defined by the configured week start) containing the selected date.

Keybindings

Global keybindings