How to Organize Notes with Notebooks and Folders in nb
nb supports multiple notebooks and nested folders for organizing notes. Create, switch, and archive notebooks, and sync each one independently to a remote.
Use this file to discover all available pages before exploring further.
Every nb notebook is a self-contained Git repository stored as a directory under ~/.nb/. You can create as many notebooks as you need — for different projects, clients, topics, or contexts — and nb will track revisions in each one independently. Within each notebook, nested folders let you organize items into any hierarchy you like. Notebooks and folders are complementary to #tags, giving you both a tree-based taxonomy and a flat tag-based one.
Prefix any command with a notebook name and colon to target that notebook without switching to it:
# list items in "example" without switchingnb example:# add a note to "example"nb example:add "This is a note."nb example:a "This is a note."# show note 5 in "example"nb example:show 5nb example:s 5# edit note 12 in "example"nb example:edit 12nb example:e 12# search "example" for a querynb example:search "example query"nb example:q "example query"
The colon can also be placed on the identifier rather than the subcommand:
# these are equivalentnb edit example:12nb example:12 editnb example:12 e
A local notebook is any folder outside ~/.nb/ that has been initialized as an nb notebook. Local notebooks are great for adding structured Git versioning to an existing project directory.Initialize a local notebook with nb notebooks init:
# initialize the current directory as a local notebooknb notebooks init# create a new local notebook at ~/examplenb notebooks init ~/example# clone a remote Git repo as a local notebooknb notebooks init ~/example https://github.com/example/example.git
When nb is run from inside a local notebook directory, that notebook becomes the current notebook:
nb# local · example · home# ----------------------# [3] Title Three# [2] Title Two# [1] Title One
A local notebook is always referred to by the name local in selectors:
# move a note from home to the local notebooknb move home:Todos local:# move a note from local to homenb move 1 home:
Folders let you organize notes into subdirectories within a notebook. They are created automatically when you add a note to a path that does not exist yet.
Pass a folder path with a trailing slash to any list command:
# list items in example/demo/nb example/demo/# home# ----# [example/demo/3] Title Three# [example/demo/2] Title Two# [example/demo/1] Title One
Folders can also be navigated by their numeric id with a trailing slash:
nb list# [1] 📂 examplenb list 1/# [example/2] 📂 demo# [example/1] document.mdnb list 1/2/# [example/demo/3] Title Three# [example/demo/2] Title Two# [example/demo/1] Title One
Items inside folders are addressed using the folder path followed by the item id, filename, or title. Folder names and folder ids are interchangeable:
# list item 1 inside example/demo/nb list example/demo/1# edit item using mixed ids and namesnb edit example/2/one.md# show item using folder idsnb show 1/2/Title\ One# delete itemnb delete 1/demo/1
Combine the notebook name, colon, and folder path:
# list the "sample" folder in the "example" notebooknb example:sample/# add a note to "sample/demo" in the "example" notebooknb add example:sample/demo/# edit item 3 in "sample/demo" in the "example" notebooknb edit example:sample/demo/3
Notebooks and #tags work at different levels of granularity and complement each other:
Notebooks are good for top-level, high-signal categories: one per project, client, or major life area. Each notebook has its own version history and can be synced to a separate remote.
Tags are ad hoc and searchable across notebooks, letting you group related items across multiple notebooks without restructuring your hierarchy.
# search for #tag in the current notebooknb q --tag tag# search for #tag across all notebooksnb q -t tag -a# search for #tag in the "example" notebooknb q example: "#tag"