sqve / notebox.nvim

Notebox is a lightweight Neovim plugin for efficient management and retrieval of Markdown-based notes

📥 notebox

Notebox is a plugin for Neovim designed to help you manage your Markdown-based notes. It is intentionally lightweight, adhering to the Unix philosophy, and focuses on streamlining the creation and retrieval of notes.

Additional note-taking features, such as highlighting and LSP support, are accessible through other plugins; see the [companions] section for more information.

✨ Key features

• Key: Value

⚡ Requirements

• Neovim
• plenary.nvim
• telescope.nvim

📦 Installation

lazy.nvim

{
  'sQVe/notebox.nvim',
  dependencies = { 'nvim-lua/plenary.nvim' },
  opts = {
    -- Input configuration here.
    -- Refer to the configuration section below for options.
  }
},

packer.nvim

use({
  'sQVe/notebox.nvim',
  requires = { 'nvim-lua/plenary.nvim' },
  config = function()
    require('notebox').setup({
      -- Input configuration here.
      -- Refer to the configuration section below for options.
    })
  end,
})

🔌 Configuration

The following code block shows the available options and their defaults:

{
  generate_note_id = nil,
  get_open_options = nil,
  root_directory = vim.fn.expand('$HOME') .. '/notebox',
  subdirectories = {
    dailies = 'dailies',
    new_notes = 'inbox',
    templates = 'templates',
  },
}

generate_note_id

A callback function that generates the id of a note. The builtin handler for this provides the following ids:

Type	Format	Example
Daily	%Y%m%d-%A	20230131-wednesday
Note	%Y%m%d- + title	20230131-my-note-title

Parameters

• type: ('daily' | 'note')? - The note type.
• title: string? - The note title.

Return

Returns the note id string.

get_open_options

A callback function that returns the options to feed into the opening process. The built-in handler supports opening the file on macOS (open) and Linux (xdg-open) in the program associated with its type.

Return

Returns a table: { command: string, args: string[] } with arguments to pass to the open process.

Example

root_directory

A string value that determines the root directory for notebox.

subdirectories

A table that sets sub directory names within the root_directory.

dailies

A string value that determines where daily notes will be stored.

new_notes

A string value that determines where new notes will be stored.

templates

A string value that determines where templates are stored.

The following template files are used:

1. daily.md: When creating a new daily note.
2. note.md: When creating a new note.

📗 Usage

Notebox works out-of-the-box with the auto_start option enabled. The following API is available under require('notebox') if you want to handle things manually:

require('notebox').setup

Sets up the plugin, see configuration for further information.

require('notebox/note').new_note

Create a new note.

Parameters

• note_type: ('daily' | 'note')? - The type of note. Defaults to 'note'.
• note_title: string? - The title of the note. The user will be prompted for the title if it is not provided.
• use_buffer_directory: boolean? - Determines whether to create the new note in the same directory as the current buffer. Defaults to false.

require('notebox/note').open_note

Open the current note in the system default application.

require('notebox/telescope').find_note

Find notes by their filename.

Parameters

• root_directory: string? - The root directory, defaults to config.root_directory config if unspecified.

require('notebox/telescope').live_grep_note

Find notes by their content.

Parameters

• root_directory: string? - The root directory, defaults to config.root_directory config if unspecified.

👥 Companions

The purpose of notebox is to provide frictionless creation and retrieval of notes. It is just one piece of a larger puzzle when it comes to creating a cozy environment for managing Markdown-based notes. The remaining information in this section will give you an opinionated view on how I ([sQVe]) have set up other Neovim plugins to create my note-taking environment.

LSP and completion

One essential part of any note-taking environment is the ability to easily navigate and reference other notes. The following plugins provide a rich set of features for this purpose:

• nvim-lspconfig together with marksman:
• nvim-cmp:
• LuaSnip:

Syntax and highlighting

• headlines.nvim:
• nvim-treesitter:

💡 Inspiration

The following plugins inspired this plugin:

• obsidian.nvim
  • This plugin kick-started my note-taking journey and helped me discover my preferred method for working with markdown-based notes. See alternatives to notebox for a comparison.
  • It provided insights into how to open notes in Obsidian, which is the GUI note-taking application that I personally use.
• nvim-lspconfig
  • It provided insights into how to safely resolve the current operating system, especially when it comes to Windows.

🔀 Alternatives to notebox

There are multiple alternatives to notebox, most of which aim to provide a feature-rich or even feature-complete note-taking environment. The following plugins are excellent options if you are willing to commit to a specific workflow and don't need to assemble your environment by yourself.

• mkdnflow.nvim: Boosts Markdown navigation and management. Offers features inspired by Vimwiki, such as link syncing and file renaming.
• neorg: Provides a variety of tools for note-taking and project management in the .norg format, including time tracking and authoring features.
• obsidian.nvim: Allows writing and interacting with Obsidian vaults directly in Neovim.
• vimwiki: Acts as a personal wiki for Vim, facilitating note-taking, task management, and content exporting to HTML.

➕ Contributing

All contributions to notebox are greatly appreciated, whether it's a bug fix or a feature request. If you would like to contribute, please don't hesitate to reach out via the [issue tracker].

Before making a pull request, please consider the following:

• Follow the existing code style and formatting conventions.
  • Install Stylua to ensure proper formatting.
• Write clear and concise commit messages that describe the changes you've made.

🏁 Roadmap

• Ability to customize the template name for new notes and daily notes.
• Create a week's worth of daily notes. Useful for writing to-dos for each day of the week.
• Customize template attributes.
• Generate a list of notes created today within the daily note.
• Generate a weekly review note.
• Handle non-flat daily note structures.
• Open notes backward or forward from the current date or from the date of the current note.