Getting started

This guide will help you get started with Notesium, using the embedded web interface. By the end, you’ll have Notesium installed, a notes folder set up, and your first linked notes created.

Install Notesium

Open a terminal and run the following commands, which will download and verify notesium, set executable permissions and make it available in your PATH.

# Example for Linux 64-bit
arch=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')
curl -sLO https://github.com/alonswartz/notesium/releases/latest/download/notesium-linux-$arch
curl -sLO https://github.com/alonswartz/notesium/releases/latest/download/checksums.txt
sha256sum --check --ignore-missing checksums.txt && rm checksums.txt
chmod +x notesium-linux-$arch
mv notesium-linux-$arch $HOME/.local/bin/notesium

# Example for macOS 64-bit
arch=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')
curl -sLO https://github.com/alonswartz/notesium/releases/latest/download/notesium-darwin-$arch
curl -sLO https://github.com/alonswartz/notesium/releases/latest/download/checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing && rm checksums.txt
chmod +x notesium-darwin-$arch
mv notesium-darwin-$arch $HOME/bin/notesium

# Example for Windows 64-bit (in PowerShell)
$arch = if ($ENV:PROCESSOR_ARCHITECTURE -eq "AMD64") { "amd64" } elseif ($ENV:PROCESSOR_ARCHITECTURE -eq "ARM64") { "arm64" } else { throw "Unsupported architecture: $ENV:PROCESSOR_ARCHITECTURE" }
Invoke-WebRequest -Uri "https://github.com/alonswartz/notesium/releases/latest/download/notesium-windows-$arch.exe" -OutFile "./notesium-windows-$arch.exe"
Invoke-WebRequest -Uri "https://github.com/alonswartz/notesium/releases/latest/download/checksums.txt" -OutFile "./checksums.txt"
$hash = Get-FileHash -Path "./notesium-windows-$arch.exe" -Algorithm SHA256
$checksums = Get-Content "./checksums.txt"
if ($checksums -match $hash.Hash) { Write-Output "Checksum verified"; Remove-Item "./checksums.txt" } else { Write-Error "Checksum verification failed!" }
New-Item -ItemType Directory -Path "$env:USERPROFILE\AppData\Local\Microsoft\WindowsApps" -Force
Move-Item -Path "./notesium-windows-$arch.exe" -Destination "$env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\notesium.exe"

# Confirm installation
notesium version --verbose

Tip: Shell completion is available for all notesium commands and options.

Create a notes directory

Notes are stored as plain Markdown files inside a single folder. Create a folder named notes inside your home directory (this is the default location).

mkdir $HOME/notes

Tip: Set the NOTESIUM_DIR environment variable if you prefer a different location.

Start the Web Interface

Notesium ships with an embedded web interface which is self contained and runs locally.

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

Tip: The web interface stores state and preferences, but is port-specific, meaning that to retain them across sessions, the same port must be used.

Create your first note

Once the Web interface opens in your browser:

1. Click New Note, or the + in the ribbon top-left (or press space n n).
2. Write your note, and click Save (or press Ctrl+s).

# Quantum mechanics

A fundamental theory in physics that provides a description of the
physical properties of nature at the scale of atoms and subatomic
particles.

Tip: The first line of the note is used as the title. A unique deterministic ID will be used as the filename.

Link your notes

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

Create another note, and link it to the first.

1. Click the + in the ribbon top-left (or press space n n).
2. Start writing the note content

# Richard Feynman

An American physicist, known for his work in the path integral
formulation of

3. At the end of the sentence type [[. The two square brackets will trigger the Link insertion Finder, where you can select the note to link to. Once selected, the link will be inserted (for example):

# Richard Feynman

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

4. Click Save (or press Ctrl+s).

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

Tip: Titles can be changed without breaking any existing links.

Navigate between notes

Outgoing links: When editing/viewing a note, links are clickable and will either open the linked note in a new tab, or switch to it if already open. The Outgoing links are also listed in the Note Sidebar.

Incoming links: Another way to navigate is through incoming links. For example, the Note sidebar in Quantum mechanics will list Richard Feynman under incoming links, and link directly to the line number where it was referenced.

Tip: Quickly review all links related to the current note with a preview by pressing space n k.

Tip: Visualize the relationships between notes with the interactive force graph.

Find & Search notes

Use the Notes list panel or the Finder to quickly locate notes (activated from the Ribbon or keybindings).

Tip: For more keybindings, see the Web Interface documentation, or use the in-app reference in Settings>Keybindings.

That’s the basics. Keep writing and let structure emerge naturally as you link your notes.

Where to next?

• Learn about the Core concepts.
• Explore the Web interface and its features.
• Power user? Dive into the CLI, API, or the Vim plugin.
• Need help or have feedback? See GitHub Discussions.