Documentation Index
Fetch the complete documentation index at: https://mintlify.com/xwmx/nb/llms.txt
Use this file to discover all available pages before exploring further.
nb derives metadata from three sources: the Git history of the notebook repository, the filesystem, and the content of each file. This layered approach means timestamps are reliable and portable across machines, item ordering is stable and committed to version control, and user-defined metadata lives alongside content in plain text.
Git-Derived Timestamps
nb reads commit history using git log to supply accurate timestamps — not filesystem ctime or mtime values, which can be reset by operations like rsync or cloning:
| Option | Source | Description |
|---|---|---|
--added / -a | First git commit containing the file | Creation datetime |
--updated / -u | Most recent git commit modifying the file | Last change datetime |
--authors | All commit authors for the file | Contributor list |
YAML Front Matter
User-defined metadata can be added to any note using front matter. Front matter is a block of YAML enclosed in triple-dashed lines (---) at the very start of a Markdown file:
nb reads the title: field for listing, filtering, and item selection. All other fields are stored in the file but are not parsed or interpreted by nb — they are yours to define.Title Field
When atitle: field is present in a note’s front matter, nb uses it instead of the filename when displaying the item in listings and when resolving title-based selectors:
Custom Fields
Any additional key–value pairs in the front matter block are preserved verbatim and available to external tools, templates, and scripts. Simple scalar values usekey: value syntax; complex data can use full YAML capabilities:
Internal State Files
nb uses several plain text files committed to Git to track item ordering, pinning, and notebook archival state. These files are managed automatically by nb — editing them manually may corrupt your notebook.
.index Files
Every folder in a notebook contains a .index file — a plain text list of filenames, one per line. The line number of each filename is its stable numeric id:
.index is committed to Git, ids are consistent across all clones of a notebook. The supported operations on an index are:
| Operation | Effect |
|---|---|
add | Append a new filename line to .index |
update | Overwrite an existing filename entry with a new filename |
delete | Remove the filename but preserve the blank line (keeping the id slot) |
reconcile | Remove duplicates, add entries for new files, delete entries for removed files |
rebuild | Delete and fully reconstruct .index sorted by last-modified (ids may change) |
nb index subcommand manages .index files. You can inspect it directly:
.pindex Files
Any folder may optionally contain a .pindex file — a plain text list of basenames that should be treated as pinned. Pinned items appear first in listings produced by nb and nb ls:
nb pin and nb unpin:
.archived Files
A notebook is considered archived when its root directory contains a file named .archived. Archived notebooks are hidden from default listings but remain accessible.
Bookmark and Todo File Formats
nb encodes additional semantic metadata through file extensions and content structure rather than external databases.
Bookmark Files (.bookmark.md)
Bookmarks are Markdown files with a .bookmark.md extension. The bookmark URL is the first angle-bracket-wrapped URL in the file. Sections are separated by Markdown h2 headings:
## Description, ## Quote, ## Comment, ## Related, ## Tags, ## Content, ## Source) are optional.
Todo Files (.todo.md)
Todos are Markdown files with a .todo.md extension. The h1 heading contains a Markdown checkbox indicating completion state:
[ ] in the heading means the todo is open; [x] means it is done.