Skip to content

HANDBOOK.md

Latest commit

 

History

History
318 lines (218 loc) · 10.4 KB

HANDBOOK.md

File metadata and controls

318 lines (218 loc) · 10.4 KB
Raw

RustNote Handbook

A comprehensive guide to using RustNote. RustNote is a Rust rewrite of note by armandsauzay.

Getting Started

On first run, RustNote automatically creates the necessary directories and generates a default configuration file.

Default locations:

  • Config: ~/.config/rustnote/config.yaml
  • Notes: ~/.local/share/rustnote/
  • Archive: ~/.local/share/rustnote/archive

These locations follow the XDG Base Directory specification and respect XDG_CONFIG_HOME and XDG_DATA_HOME environment variables if set.

To view your current configuration:

rustnote --config

Keybindings

Navigation

Key Action
j or Down Move selection down
k or Up Move selection up

Folder Operations

Key Action
l or Right Expand selected folder
h or Left Collapse selected folder; if a note is selected, navigate to its parent folder
N Create new folder in current directory
Enter (on folder) Rename folder

Note Operations

Key Action
n Create new note in current directory
Enter (on note) Open note in external editor
Backspace Archive current note or folder
d Delete current note or folder (with confirmation)

View

Key Action
Tab Toggle sidebar visibility
PageUp Scroll content preview up
PageDown Scroll content preview down
Mouse scroll wheel Scroll content preview

NoteSet Switching

Key Action
[ Switch to previous NoteSet (only available with multiple NoteSets)
] Switch to next NoteSet (only available with multiple NoteSets)

Application Control

Key Action
q Quit
Ctrl+c Quit

Editor Configuration

RustNote determines which editor to use based on this priority order:

  1. The editor field in config.yaml
  2. NOTE_EDITOR environment variable
  3. VISUAL environment variable
  4. EDITOR environment variable
  5. /usr/bin/vi (if it exists)
  6. /bin/ed (final fallback)

Editor Examples

Set editor via environment variables:

export NOTE_EDITOR=nvim
export VISUAL=helix
export EDITOR=nano

Or configure in config.yaml:

editor: nvim

Common editor commands:

  • nvim or vim or vi — Vim-based editors
  • helix or hx — Helix editor
  • nano — Nano editor
  • code --wait — VS Code (the --wait flag is required for TUI apps)

Multiple NoteSets

NoteSets are independent note collections, each with its own directory and optional archive folder. This feature is useful for separating personal notes, work notes, project documentation, or any other categorization.

Configuring NoteSets

NoteSets are configured in the config.yaml file using the note_sets array.

note_sets:
  - name: Personal
    path: /home/user/notes/personal
  - name: Work
    path: /home/user/notes/work
    archive_dir: /home/user/notes/work/archive
  - name: Projects
    path: /home/user/notes/projects

active_note_set: 0

Each NoteSet configuration:

  • name: Display name shown in the header
  • path: Directory where notes are stored
  • archive_dir: Optional. If not specified, defaults to {path}/archive

Switching NoteSets

When multiple NoteSets are configured, the header displays tab-style indicators showing all NoteSets and highlighting the active one.

Press [ to switch to the previous NoteSet or ] to switch to the next NoteSet.

State Persistence

  • Expanded folder state is preserved per NoteSet. When you switch back to a NoteSet, folders remain in their previous expanded/collapsed state.
  • The active NoteSet is saved to the config file and persists across restarts.

Backward Compatibility

If the note_sets array is not present in your configuration, RustNote falls back to the legacy single-note mode using the notes_dir and archive_dir fields.

Configuration Reference

Full config.yaml structure with all fields and defaults:

config_dir: ~/.config/rustnote
notes_dir: ~/.local/share/rustnote
archive_dir: ~/.local/share/rustnote/archive
editor: /usr/bin/vi
layout:
  sidebar_width: 30
  padding:
    horizontal: 2
    vertical: 1
  heights:
    header: 1
    footer: 1
    status: 1
    help: 1
  header_gap: 1
theme:
  light: default
  dark: default
note_sets:
  - name: Personal
    path: /home/user/notes/personal
active_note_set: 0

Configuration Fields

Paths

  • config_dir: Configuration directory (default: ~/.config/rustnote)
  • notes_dir: Legacy notes directory (used only if note_sets is not configured)
  • archive_dir: Legacy archive directory (used only if note_sets is not configured)

Editor

  • editor: External editor command (overrides environment variables)

Layout

  • layout.sidebar_width: Width of the sidebar in columns (default: 30)
  • layout.padding.horizontal: Horizontal padding (default: 2)
  • layout.padding.vertical: Vertical padding (default: 1)
  • layout.heights.header: Header height in lines (default: 1)
  • layout.heights.footer: Footer height in lines (default: 1)
  • layout.heights.status: Status bar height in lines (default: 1)
  • layout.heights.help: Help bar height in lines (default: 1)
  • layout.header_gap: Gap between header and content (default: 1)

Theme

  • theme.light: Light theme name (currently placeholder, default: "default")
  • theme.dark: Dark theme name (currently placeholder, default: "default")

NoteSets

  • note_sets: Array of NoteSet configurations (see Multiple NoteSets section)
  • active_note_set: Index of the active NoteSet (0-based)

Environment Variables

Environment variables that affect RustNote behavior:

  • XDG_CONFIG_HOME: Override default config directory location
  • XDG_DATA_HOME: Override default data directory location
  • NOTE_EDITOR: Primary editor preference
  • VISUAL: Secondary editor preference
  • EDITOR: Tertiary editor preference

Archive System

Archiving moves notes or folders to a separate directory, keeping your main note list clean while preserving content. If you want to permanently remove items instead, use the delete command.

Archiving & Deleting

Press Backspace to archive the currently selected note or folder. Press d to permanently delete the currently selected note or folder. A confirmation prompt will appear for deletion — press y to confirm or n/Esc to cancel. Press u to undo the most recent archive operation (one-step undo only).

How Archiving Works

The archive operation is a file-system-level move operation with several key characteristics:

  1. File System Rename: The archive operation is fundamentally an fs::rename — the note file or folder is physically moved to the archive directory. There is no database flag, no metadata change, no soft delete. It is a file-system-level move.

  2. Timestamp Prefix: The moved file is automatically renamed with a timestamp prefix in the format YYYY-MM-DD-HHMMSS-{original_filename}. For example, archiving meeting.md becomes 2026-06-01-143052-meeting.md. This prevents filename collisions across multiple archives and preserves the archive time.

  3. Folder Archiving: When archiving a folder, the entire directory (including all subdirectories and files) is moved to the archive directory as-is, preserving the internal structure.

  4. Hidden from Sidebar: The archive directory and all its contents are completely invisible in the sidebar note list. RustNote skips the archive directory path and any sub-paths during note traversal.

  5. Undo Archive: Press u to undo the most recent archive operation (the file is moved back to its original location). This only remembers the last operation — you cannot undo multiple archives in sequence.

Concrete example showing the file system before and after archive:

Before archiving:
~/notes/work/
├── project-a/
│   └── notes.md
├── meeting.md
└── ideas.md

After pressing Backspace on meeting.md:
~/notes/work/
├── project-a/
│   └── notes.md
└── ideas.md

~/notes/work/archive/
└── 2026-06-01-143052-meeting.md

Archive Directory Configuration

The archive directory is configured per NoteSet:

  • In note_sets config, specify archive_dir explicitly
  • If not specified, defaults to {path}/archive relative to the NoteSet path

Example:

note_sets:
  - name: Work
    path: /home/user/notes/work
    archive_dir: /home/user/notes/work-archive

Archive location rules:

Configuration Archive Location
archive_dir explicitly set in note_sets The specified path
archive_dir not set in note_sets {NoteSet.path}/archive (archive subdirectory within the NoteSet)
Legacy mode, no note_sets configured ~/.local/share/rustnote/archive

Tip: Archived files are regular files on disk. You can browse the archive directory directly with a file manager or terminal to find or organize old notes, even outside of RustNote.

Folder Organization

Creating Folders

Press N to create a new folder in the current directory. The folder is initially named "New Folder" (with a numeric suffix if needed to avoid conflicts). The rename prompt automatically opens so you can give it a proper name.

Renaming Folders

Press Enter on a folder to open the rename prompt. Type the new name and press Enter to confirm, or press Esc to cancel.

Expanding and Collapsing

Press l or Right to expand a folder and show its contents. Press h or Left to collapse a folder and hide its contents.

If a note is selected, pressing h or Left navigates to its parent folder and collapses it.

Tree Structure

The sidebar displays folders and notes in a tree structure with indentation indicating depth. Expanded folders show their children, while collapsed folders show only their name.

Note Content

Markdown Support

RustNote renders markdown notes with live preview in the content panel. Common markdown syntax is supported.

Creating Notes

Press n to create a new note. Notes are automatically named with a timestamp format: note-YYYY-MM-DD-HHMMSS.md. The note is pre-populated with a title and creation timestamp.

Editing Notes

Press Enter on a note file to open it in your configured external editor. When you close the editor, RustNote automatically refreshes the preview.