mirror of
https://github.com/tomasriveral/NoteWrapper.git
synced 2026-08-11 18:18:36 +02:00
250 lines
9.3 KiB
Markdown
250 lines
9.3 KiB
Markdown
# 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 ;)
|
|
|
|
[](https://deepwiki.com/tomasriveral/notewrapper)
|
|
|
|
## 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 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`
|
|
|
|
You must also have a [supported editor (and their associated plugin if needed)](#editor-support) installed:
|
|
|
|
* `helix`
|
|
* `jed`
|
|
* `kakoune`
|
|
* `micro`
|
|
* `nano`
|
|
* `neovim`
|
|
* `vi`
|
|
* `vim`
|
|
|
|
---
|
|
|
|
## How to install
|
|
|
|
### Nix flakes
|
|
|
|
Add this to your inputs in flake.nix:
|
|
|
|
```nix
|
|
notewrapper = {
|
|
url = "github:tomasriveral/notewrapper";
|
|
};
|
|
```
|
|
If your flake already inputs nixpkgs and/or flake-utils, you can follow it:
|
|
```nix
|
|
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:
|
|
|
|
```shell
|
|
git clone https://github.com/Totorile1/NoteWrapper.git
|
|
cd NoteWrapper
|
|
```
|
|
|
|
4. Build the project:
|
|
|
|
* On **NixOS**:
|
|
|
|
```shell
|
|
nix-build
|
|
```
|
|
|
|
* On other systems:
|
|
|
|
```shell
|
|
make
|
|
```
|
|
|
|
5. [Configure](#configuration) `~/.config/notewrapper/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:
|
|
-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](#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)
|
|
* **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 | Aditional requirements |
|
|
| --------- | ----------- | ------- | ------------ | ---------------------------------------------------------|
|
|
| [Helix](https://helix-editor.com/) | ❌ | ❌ | ✅ | — |
|
|
| [Jed](https://www.jedsoft.org/jed/) | ❌ | ❌ | ✅ | — |
|
|
| [Kakoune](http://kakoune.org/) | ❌ | ❌ | ✅ | — |
|
|
| [Micro](https://micro-editor.github.io/) | ❌ | ✅ | ✅ | [micro-vivify](https://codeberg.org/gibbert/micro-vivify) and [modifications to your `init.lua`](./docs/micro.md)|
|
|
| [Nano](https://www.nano-editor.org/) | ❌ | ❌ | ✅ | — |
|
|
| [Neovim](https://neovim.io/) | ✅ | ✅ | ✅ | [vivify-vim](https://github.com/jannis-baum/vivify.vim) |
|
|
| [Vi](https://en.wikipedia.org/wiki/Vi_(text_editor)) | ❌ | ❌ | ✅ | |
|
|
| [Vim](https://www.vim.org/) | ✅ | ✅ | ✅ | [vivify-vim](https://github.com/jannis-baum/vivify.vim) |
|
|
|
|
[How to add support for another editor](./CONTRIBUTING.md#adding-editor-support)
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Edit `~/.config/notewrapper/config.json`. If it does not exist, it will be created on first launch.
|
|
|
|
```json
|
|
{
|
|
"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"]
|
|
}
|
|
}
|
|
```
|
|
|
|
### 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`
|
|
|
|
Note:
|
|
* 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`.
|
|
|
|
---
|
|
|
|
## Vivify configuration
|
|
|
|
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)
|
|
|
|
It is recommended to use a browser different from your main one for rendering.
|
|
|
|
---
|
|
|
|
## Planned features
|
|
|
|
* [ ] A converter between journal types
|
|
* [x] 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`)
|
|
* [x] Default to $EDITOR
|
|
* [ ] Refactoring the source code
|