Core concepts

Notesium is built on a few simple yet powerful ideas.

• A completely flat directory structure.
• Filenames are 8 hexidecimal digits and deterministic.
• Titles are inferred from the first line.
• Notes with one-word titles are considered labels.
• Links are inline, and bi-directional.

Understanding these concepts helps explain why Notesium feels different from traditional note-taking apps, and why that difference matters.

Each of these design choices, from filenames to links, supports a single goal: to make note-taking frictionless, durable, and emergent.

Notesium doesn’t ask you to decide on structure upfront. Instead, it encourages exploration, linking, and gradual refinement - so your ideas can grow as naturally as your thinking does.

Notes directory

“It is better to prefer associative ontologies to hierarchical taxonomies.” ~ Andy Matuschak

Folders are often thought of as categories, but notes don’t always fit neatly into just one category, which could result in decision paralysis when creating a new note, and can prematurely constrain what may emerge.

Links would also be broken when renaming a folder or moving a note from one folder to another.

Notesium assumes a flat directory structure, having all notes be siblings to one another, in one directory. Utilizing bi-directional links allows for the structure to emerge over time. Additionally, the label convention allows for a meta-hierarchical taxonomy to be created which can be useful in certain circumstances.

Notesium’s default is to use $HOME/notes, but this can be configured by setting the NOTESIUM_DIR environment variable.

Note filenames

“There are only two hard things in Computer Science: cache invalidation and naming things.” ~ Phil Karlton

Naming is hard. With regards to notes, common conventions are to use the current date, or note title, or both in concatenated form.

• Titles: Considering notes evolve, it is often uncertain exactly what the note will encompass. And even if it is, having to decide on a title can paralyze or cause cognitive overload prior to writing the content. Existing and future collisions also need to be accounted for. If a better title is thought of later, or the context of the note changes, renaming the file would break existing links.

• Dates: The current timestamp seems like a good choice, but depending on the format used, it could result in overly long filenames, especially considering the uniqueness requirement. Additionally, timezones and daylight saving could result in collisions and interfere with sorting.

Notesium addresses this by using the UNIX epoch time, and further encoding it in hexadecimal, resulting in 8 characters for the identifier (e.g., 64214930.md). This can later be easily decoded and formatted depending on the use case.

The .md extension is required so external tools can easily identify the filetype for syntax highlighting, as well as limit the processing of files by the parser.

This is all handled automatically by Notesium, but shown here for illustrative purposes:

# encoding
$ epoch=$(date +%s --date='2023-03-27T10:43:44')
$ hexid=$(printf '%x' "$epoch")
$ echo -e "epoch: $epoch\nhexid: $hexid"
epoch: 1679903024
hexid: 64214930

# decoding
$ epoch=$(printf "%d" "0x$hexid")
$ date +%FT%T --date="@$epoch"
2023-03-27T10:43:44

Power CLI users are sometimes hesitant about this design choice, since it makes it less convenient to find or create notes using standard UNIX tools.

In practice, however, Notesium is itself a CLI utility - built to integrate naturally into command-line workflows, and provides powerful subcommands to accomplish almost anything. Both the Web Interface and Vim plugin are simply front-ends built on top of these same commands.

Note titles

“Note titles are like APIs, and when titled well they become an abstraction.” ~ Andy Matuschak

As discussed in Note filenames, it is often uncertain exactly what a note will encompass, and having to decide on a title can paralyze or cause cognitive overload before writing the content.

Just write a title and focus on the content. You can change it later, and no links will break.

Each note’s title is inferred automatically from the first line - optionally, but recommended as a Markdown heading. For example:

# Quantum mechanics

This keeps notes portable, self-describing, and editor-agnostic - so they remain readable and recognizable anywhere, even outside of Notesium.

Label notes

Even though tags are an ineffective association structure, Notesium supports the concept of labels - but there is no special label syntax. A label is simply a regular note, considered a label only if its title is a single word. It can also have its own content.

# Physicist

Associating a note with a label is done by linking, in either direction.

# Physicist

- [Richard Feynman](64214a1d.md)

# Richard Feynman

An American [physicist](642146c7.md), known for his work in the path integral
formulation of [Quantum mechanics](64214930.md)

This supports creating a meta-hierarchical taxonomy that can be searched, filtered, and sorted across all interfaces - CLI, Vim plugin, and the Web interface.

For example, the following command will prefix each note title with its associated label (multiple times for notes linked to multiple labels), color-code them, and sort alphabetically:

$ notesium list --prefix=label --sort=alpha --color
64218087.md:1: «Book» Surely you're joking Mr. Feynman
64218088.md:1: «Physicist» Albert Einstein
64214a1d.md:1: «Physicist» Richard Feynman

Additionally, the Web interface includes a dedicated Labels panel and Labels tree that provide a visual representation of label associations. Label notes are also color-coded in the Graph view.

This simple convention keeps Notesium’s structure emergent, not imposed.

Periodic notes

Notesium itself does not directly support periodic notes.

Instead, the embedded Web interface and Vim plugin handle daily and weekly notes using a creation-time convention - 00:00:00 for daily notes and 00:00:01 on the first day of the week for weekly notes.

This convention results in deterministic, unique filenames, enabling instant identification of a specific periodic note without manual organization or special formatting. It eliminates overhead and the need to search the entire notes directory for keywords or regular expressions.

Additionally, both past and future periodic notes can be created using this same convention while retaining chronological order.

$ notesium new --ctime=2024-07-04T00:00:00
/home/user/notes/6685bbd0.md

$ notesium list --sort=ctime --prefix=ctime --date=15:04:05 | grep 00:00:00
6685bbd0.md:1: «00:00:00» Jul 04, 2024 (Thursday)
6681c750.md:1: «00:00:00» Jul 01, 2024 (Monday)
668075d0.md:1: «00:00:00» Jun 30, 2024 (Sunday)

$ notesium list --sort=ctime --prefix=ctime --date=15:04:05 | grep 00:00:01
669c2551.md:1: «00:00:01» 2024: Week29 (Sun Jul 21 - Sat Jul 27)
6692ead1.md:1: «00:00:01» 2024: Week28 (Sun Jul 14 - Sat Jul 20)
6689b051.md:1: «00:00:01» 2024: Week27 (Sun Jul 07 - Sat Jul 13)

The Web interface includes a Date picker for selecting daily or weekly notes, as well as keybindings to open or create them quickly. The Vim plugin provides the same keybindings and also supports commands that accept optional dates. Both interfaces allow configuring the week start, and will preseed the note title accordingly. The periodic note’s title is just a title, and can be changed. It does not “classify” the note as a periodic note, rather what matters is the ctime (encoded in the filename) convention.

Periodic notes are identified purely by their creation time convention, not by their title or content. Titles are preseeded for convenience, but remain fully editable and do not classify the note.

This convention reinforces Notesium’s goal of determinism, simplicity and predictability.

Links

“Notes should be densely linked, allowing for structure to emerge organically.” ~ Andy Matuschak

Links are what turn a pile of notes into a living network of thought.

In Notesium, links are not an additional feature - they are the core organizing principle. Rather than forcing hierarchy through folders, relationships are created through linked notes. The more you link, the more structure naturally emerges.

Dense linking allows structure to emerge organically, revealing connections you might not have anticipated - sometimes even ones that surprise you. Notesium’s link model keeps your notes fully portable, self-contained, and editor-agnostic, while providing the connective tissue that makes your knowledge base grow more valuable over time.

Bi-directional links

Links in Notesium are bi-directional.

If note A links to note B, an incoming link is automatically registered on B.

• Outgoing links are those you create inside a note, pointing to other notes.
• Incoming links are automatically discovered, showing which notes reference the current one.

This dual awareness transforms a flat collection of files into an interconnected graph. You can explore these relationships visually in the Graph view, through dedicated panels in the Web interface, or contextually via the Finder and the CLI.

Inline link format

Notesium requires links to use the inline Markdown syntax, for example:

[Quantum mechanics](64214930.md)
 │                  │
 └── TITLE          └── TARGET

Each link points to a note by its filename (the 8-character hexadecimal identifier, including the .md suffix). This makes links explicit, durable, and easy to parse. The link TITLE can be safely changed - what matters is the link TARGET.

Even though links are short, for an improved reading experience in Vim consider enabling conceallevel (see Related Vim settings). This is implemented in the Web interface editor and enabled by default.

Inserting links

In both the Vim plugin and Web interface, inserting a link is as simple as typing [[. This triggers the Link Insertion Finder, where you can search or filter notes. Selecting a note inserts the correct Markdown link automatically.

# Richard Feynman

An American physicist, known for his work in the path integral
formulation of [Quantum mechanics](64214930.md)

Dangling links

When using the Vim plugin or Web interface, Notesium will not allow a note to be deleted if it has incoming links. This prevents creating dangling links - links that point to non-existent notes.

However, dangling links can still occur if a note is deleted directly from the filesystem or if a link’s target is manually changed.

Identifying dangling links: