NoteWrapper

Note: This project fullfills all my usecases for now, so my main source for features ideas dried out. So if you have good ideas, feel free to open an issue ;)

Why?

I started journaling and note-taking with Obsidian but wanted to use only free software. I also tried Logseq and Joplin, but I preferred a terminal-based workflow.

Using my Neovim setup, I explored plugins such as neorg, orgmode, and today.nvim. While they offered useful features, none fully met my needs: some lacked external Markdown rendering, some relied on custom file formats, and others did not provide a true journal workflow.

For real-time Markdown rendering from Neovim, I found Vivify, which NoteWrapper relies on.

The goal was to create a terminal-based interface for accessing vaults and notes using standard Markdown, with minimal additional complexity. Although editor support is currently limited, NoteWrapper is designed as a standalone wrapper that can be adapted to other editors with minimal changes.

---

Features

• Terminal-based note and journal system
• Vault-based organization (similar to Obsidian)
• Standard Markdown files (no custom format)
• Journal support with flexible entry formats
• Real-time Markdown rendering via Vivify
• Backup different directories into different destinations
• Supports multiple editors

---

Dependencies

Before building NoteWrapper, you must install the following dependencies:

• ncurses
• cjson
• make
• Vivify
• rsync
• pkg-config
• sed
• ripgrep
• fzf
• libgit2

You must also have a supported editor (and their associated plugin if needed) installed:

• helix
• jed
• kakoune
• micro
• nano
• neovim
• vi
• vim

---

How to install

Nix flakes

Add this to your inputs in flake.nix:

notewrapper={url="github:tomasriveral/notewrapper";};

If your flake already inputs nixpkgs and/or flake-utils, you can follow it:

notewrapper={url="github:tomasriveral/notewrapper; inputs.nixpkgs.follow = "nixpkgs"; inputs.flake-utils.follow = "flake-utils";};

Building from source

1. Install all required dependencies listed above.
2. Ensure you have a supported editor installed.
3. Clone the repository:

git clone https://github.com/Totorile1/NoteWrapper.git
cd NoteWrapper

4. Build the project:

• On NixOS:

nix-build

• On other systems:

make

5. Configure~/.config/notewrapper/config.json (it is automatically created on first launch if it does not already exist).
6. Run the program:

./notewrapper

---

Packaging

There is currently no official package available for NoteWrapper.

However, contributions are welcome for packaging on any distribution.

As a NixOS user, I will likely package it for nixpkgs in the future if the project gains traction.

---

Usage

Usage: notewrapper [options]
Options:
-c, --config <path/to/config> Specify the config file.
-h, --help Display this message.
-e, --editor Specify the editor to open.
-j, --jump Jump to the end of the file on opening.
-J, --no-jump Do not jump to the end of the file.
-n, --note <note's name> Specify the note (or journal).
-r, --render Render the note with Vivify.
-R, --no-render Do not render.
-v, --vault <vault's name> Specify the vault.
--version Display the program version and the GPL3 notice.
-V, --verbose Show debug information.

Files are organized similarly to Obsidian. You have a directory containing all your vaults, where each vault is a separate directory.

NoteWrapper distinguishes two types of files:

• Notes: act as a single continuous file for writing
• Journals: split into timed entries (daily, monthly, or custom formats — see configuration)

Journals can be of two types:

• Divided: one separate file per entry
• Unified: one file where new entries are appended

---

Editor support

NoteWrapper relies on certain editor features, so not all functionality is supported by every editor.

Features requiring editor support:

• Bufferless rendering: updates the rendered view while typing (without saving). You won't need to save the file to see it updated in your browser.
• Cursor following: rendered view follows the cursor position. When you scroll in your editor, it will automatically scroll your browser view.
• Jump to end on open: automatically moves the cursor to the end of the file when oppening.

The first two features depend on Vivify's editor integration¹ and are mainly useful if you want external Markdown rendering in your browser.

If your editor does not support these features, you can implement a plugin using Vivify's API.

Editor	Bufferless	Cursor	Jump to end	Aditional requirements
Helix	❌	❌	✅	—
Jed	❌	❌	✅	—
Kakoune	❌	❌	✅	—
Micro	❌	✅	✅	micro-vivify and modifications to your init.lua
Nano	❌	❌	✅	—
Neovim	✅	✅	✅	vivify-vim
Vi	❌	❌	✅
Vim	✅	✅	✅	vivify-vim

How to add support for another editor

---

Configuration

Edit ~/.config/notewrapper/config.json. If it does not exist, it will be created on first launch.

{
"directory": ["~/Documents/Notes/", "/other/paths/"],
"render": true,
"jumpToEndOfFileOnLaunch": true,
"editor": "neovim",
"journalRegex": ".*journal.*",
"dateEntry": "# %a %d %m %Y",
"newLineOnOpening": true,
"backup": {
"enable": false,
"directory": {
"~/Documents/Notes": "path/to/backup1",
"/other/paths/": "path/to/backup2"
},
"interval": "weekly",
"rsyncArgs": ["-Lqah", "--update"],
"git": {
"enable": false,
"name": "Example Example",
"email": "mail@example.com"
}
}
}

Fields

• directory: Array of directories containing the vaults.
• render: enable/disable Vivify rendering
• jumpToEndOfFileOnLaunch: move cursor to end of file on open
• editor: selected editor (must be supported). If not set, it defaults to $EDITOR.
• journalRegex: regex used to detect journal files
• dateEntry: format for journal entries (see strftime)
• newLineOnOpening: add a newline when opening a note
• backup.enable: enable automatic backups using rsync
• backup.directory: backup's destination for each directory
• backup.interval: backup frequency (daily, weekly, monthly, or integer)
• backup.rsyncArgs: arguments passed to rsync
• git.enable: enable git version control for backups
• git.name and git.email are for the commits signature

Note

• The git backup implementation relies a lot on the IO speed of your drive. A low speed one (or a web mounted one) could create blanks between closing a document and the TUI opening.
• Directories must end with /.
• All directories used must exist.
• Elements of directory and backup.directory must match exactly.
• Directories set in directory but not in backup.directory won't be backed up.
• Directories set in backup.directory but not in directory will be ignored.
• journalRegex must match if the file name ends with .md and if it doesn't.
• It is recommended to keep -q or --quiet flag in rsyncArgs to avoid interference with ncurses.
• If rsync fails, you will see it inside ncurses.
• If you want the git backup but without rsync, you can leave backup.directory empty or map each directory to itself. When enabled, git will apply to all your vaults.
• Each vault gets its own git repository that will be created the first time you select the vault with the option enabled.

---

Vivify configuration

Some settings must be configured in Vivify itself. See: https://github.com/jannis-baum/Vivify/blob/main/docs/customization.md

It is recommended to use a browser different from your main one for rendering.

---

Planned features

• A converter between journal types
• Support multiple vault directories
• Port NoteWrapper to other editors (non-exhaustive list of planned ports: emacs -nw, ad, flow-control, ee, amp, dte, cano, mle, zee, ptext, kibi, ox, ne, dit, zile, moe, joe, pico, vis)
• Default to $EDITOR
• Refactoring the source code

Footnotes

1. Eventhough the features are Vivify-related, please report bugs and ask questions in this repo. ↩