https://github.com/majjoha/marginalia.nvim
Lightweight Neovim plugin for writing and managing notes.
https://github.com/majjoha/marginalia.nvim
lua neovim neovim-plugin nvim plugin
Last synced: 6 months ago
JSON representation
Lightweight Neovim plugin for writing and managing notes.
- Host: GitHub
- URL: https://github.com/majjoha/marginalia.nvim
- Owner: majjoha
- License: isc
- Created: 2025-09-21T07:49:25.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-10-13T13:25:46.000Z (6 months ago)
- Last Synced: 2025-10-14T20:35:27.126Z (6 months ago)
- Topics: lua, neovim, neovim-plugin, nvim, plugin
- Language: Lua
- Homepage: https://github.com/majjoha/marginalia.nvim?tab=readme-ov-file
- Size: 30.3 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Marginalia
Marginalia is a lightweight plugin for writing and managing notes. It aims to be
a good, unobtrusive Neovim citizen, and it relies on built-in functionality,
e.g., `:grep` and gf, does not introduce changes to the `filetype` of
your notes, or shadow your existing key bindings.
The plugin supports creating and editing notes, listing all your notes, finding
backlinks, and searching your notes by tags.
## Features
- Create and edit notes
- List all notes in the quickfix list
- Find backlinks automatically
- Tag-based search with completion
- Works with built-in Neovim functionality (`:grep`, gf, etc.)
- Zero external dependencies
## Installation
```sh
git clone https://github.com/majjoha/marginalia.nvim.git ~/.config/nvim/pack/packages/start/marginalia.nvim
```
## Setup
```lua
require("marginalia").setup()
```
To override the default configuration:
```lua
require("marginalia").setup({
notes_path = "~/notes", -- Path to your notes folder
file_extension = ".md", -- The default extension for your notes
header_format = "# ", -- The header format for your notes, e.g., # Header
tag_identifier = "#", -- The identifier used for tags, e.g., #tag
file_prefix_function = function() -- The prefix function used when
return os.date("%Y%m%d%H%M-") -- creating new notes
end
})
```
## Commands
| Command | Arguments | Description |
|---------------------------------|----------------|-----------------------------------------------------------------------------|
| `:MarginaliaNew` | `{title}` | Creates a new note with the given title. |
| `:MarginaliaEdit` | `{title}` | Edits the note with the given title. This command supports tab completion. |
| `:MarginaliaList` | – | Lists all notes. |
| `:MarginaliaFindBacklinks` | – | Finds references to the current note. |
| `:MarginaliaFindTagReferences` | `[{tag}]` | Finds references to the given tag or the tag under the cursor if not given. |
| `:MarginaliaConvertWordToTag` | – | Converts the word under the cursor to a tag. |
## Suggested key mappings
```lua
vim.keymap.set("n", "mnn", ":MarginaliaNew")
vim.keymap.set("n", "men", ":MarginaliaEdit")
vim.keymap.set("n", "mln", ":MarginaliaList", { silent = true })
vim.keymap.set("n", "mfb", ":MarginaliaFindBacklinks",
{ silent = true })
vim.keymap.set("n", "mft", ":MarginaliaFindTagReferences", {})
vim.keymap.set("n", "mcw", ":MarginaliaConvertWordToTag",
{ silent = true })
```
## FAQ
### How can I use folders for storing my notes?
You can define a prefix function that returns an empty string when you
configure the plugin:
```lua
require("marginalia").setup({
file_prefix_function = function()
return ""
end,
})
```
Now when you run `:MarginaliaNew technology/neovim`, a new note with the name
`neovim` is stored in your `technology` folder.
If you want to use folders, you might want to consider adding this `autocmd` to
ensure that nested folders are created automatically:
```lua
vim.api.nvim_create_autocmd("BufWritePre", {
pattern = "*",
callback = function()
local dir = vim.fn.expand(":p:h")
if vim.fn.isdirectory(dir) == 0 then
vim.fn.mkdir(dir, "p")
end
end,
})
```
### Can I use wiki-style links?
Yes. In fact, this behavior can be enabled anywhere in Neovim. For notes in
Markdown format, simply add
```lua
vim.opt.suffixesadd:append({ ".md" })
```
to your `init.lua`, and you can now visit links, e.g.,
`[[today-i-learned-neovim]]`, using gf.
## Development
Run tests using [plenary.nvim](https://github.com/nvim-lua/plenary.nvim):
```sh
nvim --headless -c "PlenaryBustedDirectory tests/" -c "qa"
```
## Related projects
- [vim-notes](https://github.com/xolox/vim-notes)
- [vim-pad](https://github.com/fmoralesc/vim-pad)
- [VimWiki](https://github.com/vimwiki/vimwiki)
- [Waikiki](https://github.com/fcpg/vim-waikiki)
- [wiki.vim](https://github.com/lervag/wiki.vim)
## License
See [LICENSE](./LICENSE).