Skip to main content

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 has a lightweight plugin system that lets you add new subcommands, color themes, or any other shell-based functionality without touching the core script. Plugins are plain Bash files that live in a single directory, and they can be installed from a URL or a local path in one command.

​
Plugin Types

nb recognizes two plugin file extensions:
ExtensionPurpose
.nb-pluginDefines new subcommands and adds functionality
.nb-themeDefines a color theme (see Color Themes)
All plugins are stored in ${NB_DIR}/.plugins (default: ~/.nb/.plugins).

​
Installing Plugins

Use nb plugins install with a URL or a local file path: 
# install a plugin from a raw GitHub URL
nb plugins install https://raw.githubusercontent.com/xwmx/nb/master/plugins/clip.nb-plugin

# install a plugin from a standard GitHub URL
nb plugins install https://github.com/xwmx/nb/blob/master/plugins/example.nb-plugin

# install a theme from a standard GitHub URL
nb plugins install https://github.com/xwmx/nb/blob/master/plugins/turquoise.nb-theme

# install a plugin from a local path
nb plugins install plugins/example.nb-plugin
nb accepts both raw GitHub URLs and standard GitHub page URLs — they can be used interchangeably.

​
Listing Installed Plugins

# list plugin filenames
nb plugins

# list a specific plugin
nb plugins clip.nb-plugin

# list plugins with full paths
nb plugins --paths

# list the path to a specific plugin
nb plugins turquoise.nb-theme --paths
Example output: 
❯ nb plugins
clip.nb-plugin
example.nb-plugin
turquoise.nb-theme

❯ nb plugins --paths
/home/example/.nb/.plugins/clip.nb-plugin
/home/example/.nb/.plugins/example.nb-plugin
/home/example/.nb/.plugins/turquoise.nb-theme

​
Uninstalling Plugins

nb plugins uninstall example.nb-plugin

Plugin successfully uninstalled:
/home/example/.nb/.plugins/example.nb-plugin

​
Creating a Plugin

Plugins are Bash scripts with an .nb-plugin extension. Creating a new subcommand takes three steps:
1
Register the subcommand name
2
Call _subcommands add with the name of your new subcommand:
3
_subcommands add "example"
4
Define help and usage text
5
Use _subcommands describe with a heredoc to provide help text shown by nb help example:
6
_subcommands describe "example" <<HEREDOC
Usage:
  nb example

Description:
  Print "Hello, World!"
HEREDOC
7
Define the subcommand function
8
Name the function with a leading underscore matching the subcommand name:
9
_example() {
  printf "Hello, World!\n"
}
That’s it! With example.nb-plugin installed, running nb example prints "Hello, World!".

​
Complete Minimal Plugin

Here is the full content of the example plugin as a single file: 
# example.nb-plugin

# Step 1: register the subcommand name
_subcommands add "example"

# Step 2: define help text
_subcommands describe "example" <<HEREDOC
Usage:
  nb example

Description:
  Print "Hello, World!"
HEREDOC

# Step 3: define the subcommand function
_example() {
  printf "Hello, World!\n"
}
Install it locally, then run it: 
nb plugins install ./example.nb-plugin
nb example
# Hello, World!

​
Using the nb API Inside Plugins

The nb API is the command line interface itself. Inside a plugin, call any internal subcommand by its underscore-prefixed function name instead of spawning a new nb process. Options designed for machine-readable output (--no-color, --filenames, etc.) make it easy to parse results in scripts: 
# print the content of note 3 with no color
_show 3 --print --no-color

# list all unarchived global notebook names
_notebooks --names --no-color --unarchived --global

# list all filenames in the current notebook
_list --filenames --no-id --no-indicator

# print the path to the current notebook
_notebooks current --path

​
Working with Selectors

nb automatically scans arguments for selectors (e.g., notebook:id) and updates the current notebook context when a valid one is found. Use _show <selector> --filename to resolve a selector to a filename: 
_example() {
  local _selector="${1:-}"
  [[ -z "${_selector:-}" ]] && printf "Usage: example <selector>\n" && exit 1

  # Resolve the selector to a filename
  local _filename=
  _filename="$(_show "${_selector}" --filename)"

  # Get the current notebook path
  local _notebook_path=
  _notebook_path="$(_notebooks current --path)"

  # Print the file contents
  cat "${_notebook_path}/${_filename}"
}

​
Built-in Example Plugins

nb ships with several ready-to-study example plugins in its repository:

example.nb-plugin

The minimal “Hello, World!” plugin used in this guide.

clip.nb-plugin

Adds clipboard support — a practical example of using _show and _notebooks current --path together.

ebook.nb-plugin

Generates e-books from notebook content, demonstrating more advanced plugin patterns.
You can publish your plugin on GitHub, GitLab, or any public URL and share it with others. Anyone can install it with nb plugins install <url>.

​
Full API Reference

For a complete list of internal functions available to plugins, see the Plugin API reference.

Build docs developers (and LLMs) love

Get started for freeTalk to us