tomasr/NoteWrapper
1
0
Fork 0
mirror of https://github.com/tomasriveral/NoteWrapper.git synced 2026-08-12 02:18:38 +02:00
Code Issues Packages Projects Releases Wiki Activity

Rewrote README.md

Browse Source
This commit is contained in:
Tomas Rivera
2026-04-19 17:33:09 +02:00
parent 193382484f
commit 20b57320ed
1 changed files with 151 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+151 -77
View File
@@ -1,23 +1,99 @@
### Why?
I started journaling and notetaking with **[Obsidian](https://obsidian.md/)**, but wanted to only use free software. I also tried **[Logseq](https://logseq.com/)** and **[Joplin](https://github.com/laurent22/joplin)**, but preferred a terminal-based app.
# NoteWrapper
Using my Neovim setup, I explored plugins like **[neorg](https://github.com/nvim-neorg/neorg)**, **[orgmode](https://github.com/nvim-orgmode)**, and **[today.nvim](https://github.com/VVoruganti/today.nvim)**. While they offered useful features, none fully met my needs: some lacked external Markdown rendering, some used custom file formats, and some didn’t provide a true journal mode. For real-time Markdown rendering from Neovim, I found **[Vivify](https://github.com/jannis-baum/Vivify/)**, which NoteWrapper relies on.
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/tomasriveral/notewrapper)
The goal was a terminal-based interface for accessing vaults and notes using standard Markdown, with minimal extra features. Although it currently works only with Neovim, it is designed as a standalone wrapper that could be adapted for other editors with minimal changes.
## Why?
I started journaling and note-taking with **[Obsidian](https://obsidian.md/)** but wanted to use only free software. I also tried **[Logseq](https://logseq.com/)** and **[Joplin](https://github.com/laurent22/joplin)**, but I preferred a terminal-based workflow.
Using my Neovim setup, I explored plugins such as **[neorg](https://github.com/nvim-neorg/neorg)**, **[orgmode](https://github.com/nvim-orgmode)**, and **[today.nvim](https://github.com/VVoruganti/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](https://github.com/jannis-baum/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 support using `rsync`
* Supports multiple editors (vim, neovim, nano)
---
## Dependencies
Before building NoteWrapper, you must install the following dependencies:
* `ncurses`
* `cjson`
* `make`
* `Vivify`
* `rsync`
* `pkg-config`
* `sed`
* `ripgrep`
* `fzf`
You must also have a [supported editor](#editor-support) installed:
* `vim`
* `neovim`
* `nano`
---
## How to install
1. Install all required dependencies listed above.
2. Ensure you have a supported editor installed.
3. Clone the repository:
### How to install
1. Have installed `ncurses`, `cjson`, `make`, `Vivify`, `rsync`, `pkg-config`, `sed`, `ripgrep` and `fzf`. <TODO LATER we should put hyprlinks to each program.>
2. Have a supported editor: `vim`, `neovim` and `nano` (for the moment)
3. Clone the repository and enter it.
```shell
git clone https://github.com/Totorile1/NoteWrapper.git
cd NoteWrapper
```
4. Compile the project. On NixOS run `nix-build`. Other OS, run `make`.
5. [configure](#configuration) `./config.json` (the file is created on launching, if it already doesn't exist).
6. run the binary `notewrapper`
### Usage
4. Build the project:
* On **NixOS**:
```shell
nix-build
```
* On other systems:
```shell
make
```
5. Configure `./config.json` (it is automatically created on first launch if it does not already exist).
6. Run the program:
```shell
./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:
@@ -25,35 +101,55 @@ Options:
-d, --directory <path/to/directory> Specify the vaults' directory.
-h, --help Display this message.
-e, --editor Specify the editor to open.
-j, --jump Jumps 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 Renders the note with Vivify.
-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.
-v, --vault <vault's name> Specify the vault.
--version Display the program version and the GPL3 notice.
-V, --verbose Show debug information.
```
### Editor support
`NoteWrapper` relies on certain editor features, so not all of its functionality is supported by every editor.
Here are the features that depend on editor support:
Files are organized similarly to Obsidian. You have a directory containing all your vaults, where each vault is a separate directory.
- **Bufferless rendering**: As soon as you write something in the note (even without saving), it is rendered.
- **Cursor following**: The rendered view follows your cursor. For example, if you move to the bottom of a note, the rendered view will also scroll to the bottom.
- **Jump to end on open**: Automatically jumps to the end of the file when opening it.
NoteWrapper distinguishes two types of files:
The first two features depend on [Vivify's plugin for editors](https://github.com/jannis-baum/Vivify?tab=readme-ov-file#existing-integration) and are only usefull if you want to render the markdown externally on your browser. If your editor misses these features, you can just create a plugin or an extension which uses [Vivify's simple API](https://github.com/jannis-baum/Vivify?tab=readme-ov-file#editor-support).
* **Notes**: act as a single continuous file for writing
* **Journals**: split into timed entries (daily, monthly, or custom formats — see [configuration](#configuration))
Journals can be of two types:
| Editor | Bufferless | Cursor | Jump to end | Necessary plugin |
|---------|------------|--------|-------------|------------------|
| Neovim | ✅ | ✅ | ✅ | [vivify-vim](https://github.com/jannis-baum/vivify.vim) |
| Vim | ✅ | ✅ | ✅ | [vivify-vim](https://github.com/jannis-baum/vivify.vim) |
| Nano | ❌ | ❌ | ✅ | |
* **Divided**: one separate file per entry
* **Unified**: one file where new entries are appended
### Configuration
Change `~/.config/notewrapper/config.json`. If it does not exist, the program should create on launch.
---
## 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)
* **Cursor following**: rendered view follows the cursor position
* **Jump to end on open**: automatically moves the cursor to the end of the file
The first two features depend on [Vivify's editor integration](https://github.com/jannis-baum/Vivify?tab=readme-ov-file#existing-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](https://github.com/jannis-baum/Vivify?tab=readme-ov-file#editor-support).
| Editor | Bufferless | Cursor | Jump to end | Plugin required |
| ------ | ---------- | ------ | ----------- | ------------------------------------------------------- |
| Neovim | ✅ | ✅ | ✅ | [vivify-vim](https://github.com/jannis-baum/vivify.vim) |
| Vim | ✅ | ✅ | ✅ | [vivify-vim](https://github.com/jannis-baum/vivify.vim) |
| Nano | ❌ | ❌ | ✅ | — |
---
## Configuration
Edit `~/.config/notewrapper/config.json`. If it does not exist, it will be created on first launch.
```json
{
@@ -72,56 +168,34 @@ Change `~/.config/notewrapper/config.json`. If it does not exist, the program sh
}
}
```
`directory` is the directory where the program will search for vaults.
`render` is a boolean that tells the program if it needs to render the markdown file using `Vivify`
### Fields
`jumpToEndOfFileOnLaunch` is a boolean that tells the programs if it needs to set the cursor at the end of the file on launch.
* `directory`: root directory containing all vaults
* `render`: enable/disable Vivify rendering
* `jumpToEndOfFileOnLaunch`: move cursor to end of file on open
* `editor`: selected editor (must be supported)
* `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`: destination directory for backups
* `backup.interval`: backup frequency (`daily`, `weekly`, `monthly`, or integer)
* `backup.rsyncArgs`: arguments passed to `rsync`
`editor` is the editor the program will call. (It must be a supported editor.
---
`journalRegex` is a regex code. If the note name matches with this code, the program will treat it as a journal.
## Vivify configuration
`dateEntry` is the style of the file title or paragraph title (depending on the type of journal). See [strftime](https://pubs.opengroup.org/onlinepubs/7908799/xsh/strftime.html?) for more info.
Some settings must be configured in Vivify itself. See:
[https://github.com/jannis-baum/Vivify/blob/main/docs/customization.md](https://github.com/jannis-baum/Vivify/blob/main/docs/customization.md)
`newLineOnOpening` is a boolean that tells the program to append a newline when opening a note.
It is recommended to use a browser different from your main one for rendering.
`backup.enable` enable the backups. The program relies on `rsync` for backuping.
---
`backup.directory` is the directory where the backup will go.
`backup.interval` can either be `daily`, `weekly`, `monthly` or an integer. It specifies the interval between two backups.
`rsyncArgs` are the array of arguments that will be passed into rsync. See `man rsync` or `rsync --help`.
#### Vivify's Configuration
Some settings must be set in Vivify's configuration file. See [documentation](https://github.com/jannis-baum/Vivify/blob/main/docs/customization.md).
I recommend changing the browser settings to a browser different to your main browser.
### What needs to be done (a lot)
- [x] Add a way to create vaults
- [x] Add a way to delete vaults
- [ ] Add a way to delete notes
- [x] Stylisize a bit the TUI
- [x] Add more options to the config file
- [x] Search for config.json in other directories such as ~/.config/notewrapper/ and not only this directory
- [x] Port vivify.vim to nixpkgs
- [ ] Add a way to have vaults in different directories
- [x] some kind of FZF search for notes
- [x] A button to randomly select a note or an entry in a journal
- [x] Fix crash when the window is resized
- [x] Actually open vivify when opening nvim
- [x] Write the journaling code (separate files or one big journal files)
- [x] Adapt createNewNote with journals
- [x] Automatic backups
- [x] Add flags for customization
- [ ] Write a good README.md
- [x] Option to not render and to only open nvim
- [x] Figure out this vivify issue https://github.com/jannis-baum/Vivify/issues/291
- [ ] Port this to other editors
- [x] Port to vim
- [ ] Fixe all the small stuff marked //(TODO LATER) in the code
- [x] Comply with GPL-3 notice (add info about no waranty, etc.)
- [ ] A converter for both type of journals
## Planned features
* [ ] A converter between journal types
* [ ] Support multiple vault directories
* [ ] Port NoteWrapper to other editors