From 20b57320ed0a0972b158b2f872797cf15bdf7602 Mon Sep 17 00:00:00 2001 From: Tomas Rivera <137088692+Totorile1@users.noreply.github.com> Date: Sun, 19 Apr 2026 17:33:09 +0200 Subject: [PATCH] Rewrote README.md --- README.md | 228 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 151 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index b812e54..fe44095 100644 --- a/README.md +++ b/README.md @@ -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`. -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 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 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 Specify the note (or journal). + -r, --render Render the note with Vivify. -R, --no-render Do not render. - -v, --vault Specify the vault. - --version Display the program version and the GPL3 notice. - -V, --verbose Show debug information. + -v, --vault 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