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 browse transforms your notebooks into a fully navigable local web application, accessible from any terminal or GUI browser on your machine. It renders [[wiki-style links]] and #hashtags as clickable internal links, displays pinned items, paginates long lists, and lets you read, edit, add, and delete items without leaving the browser. Everything runs entirely locally — no network requests, no third-party services, no data leaving your machine.

​
Starting the Browser

Run nb browse (shortcut: nb b) with no arguments to open the current notebook in a terminal web browser: 
nb browse

❯nb · home : +

search: [                    ]

[home:6]  📌 Example Markdown Title
[home:12] 🔒 example-encrypted.md.enc
[home:11] 🔖 Example Bookmark (example.com)
[home:10] 🔖 🔒 example-encrypted.bookmark.md.enc
[home:9]  Example .org Title
[home:8]  🌄 example-image.png
[home:7]  📄 example.pdf
[home:5]  🔉 example-audio.mp3
[home:4]  Example LaTeX Title
[home:3]  📹 example-video.mp4
[home:2]  example.md
[home:1]  📂 Example Folder
Lists use the same format as nb ls, including pinned items with 📌 indicators. Lists are automatically paginated to fit the terminal window height. nb browse opens in w3m, Links, or the browser set in the $BROWSER environment variable.

​
Opening a Specific Item or Folder

Pass any selector — a notebook name, folder path, item ID, filename, or title — to open directly to that location: 
# open item 42 in the "sample" folder of the "example" notebook
nb browse example:sample/42

# open a folder
nb browse example:sample/demo/

❯nb · example : sample / demo / +

search: [                    ]

[example:sample/demo/7] Title Seven
[example:sample/demo/6] Title Six
[example:sample/demo/5] Title Five
[example:sample/demo/4] Title Four
[example:sample/demo/3] Title Three

next ❯
Items can also be opened with nb show --browse / nb s -b, which behaves identically to nb browse <selector>.

​
GUI Browser

Add --gui / -g to open any nb browse view in the system’s primary GUI web browser: 
# open the current notebook in the GUI browser
nb browse --gui
nb b -g

# open a specific item in the GUI browser
nb browse sample:123 --gui

# open a folder in the GUI browser, short option
nb browse example/ -g

​
Server Modes

Start the web server and keep it running until any key is pressed:
nb browse --serve

​
Server Host and Port

By default nb browse listens on localhost:6789. Override either value in your ~/.nbrc: 
export NB_SERVER_HOST="localhost"
export NB_SERVER_PORT="6789"

​
Browsing Notebooks

Use --notebooks / -n to open the notebook index view: 
nb browse --notebooks
nb b -n

​
Search and Tag Filtering

nb browse includes a search field powered by nb search. You can also jump straight to a filtered view from the command line. 
# open to results for "example" in the current notebook
nb browse --query "example"
nb b -q "example"

❯nb · home

search: [example             ]

[home:321] Test Title
[home:654] Sample Title
[home:789] Demo Title
Search queries support the same AND / OR logic as nb search, since the search field passes arguments directly to nb search.

​
Editing in the Browser

​
Terminal Browser Editing

Select the edit link on any item page, or open an item directly in edit mode: 
nb browse edit text:formats/markdown/123
nb b e text:formats/markdown/123

❯nb · text : formats / markdown / 123 · ↓ · editing · - | +

[# Daring Fireball: Markdown (daringfireball.net)         ]
[                                                         ]
[<https://daringfireball.net/projects/markdown/>          ]
[                                                         ]
[## Related                                               ]
[                                                         ]
[- <https://en.wikipedia.org/wiki/Markdown>               ]
[                                                         ]
[## Comments                                              ]
[                                                         ]
[See also:                                                ]
[                                                         ]
[- [[text:formats/org]]                                   ]
[- [[cli:apps/nb]]                                        ]
[                                                         ]
[## Tags                                                  ]
[                                                         ]

[save] · last: 2021-01-01 01:00:00
Terminal browser editing behavior varies by browser: w3m opens items in your $EDITOR and returns you to the browser to save; links performs edits inline in the browser window.

​
GUI Browser Editing with Ace

By default, nb browse --gui uses the browser’s built-in <textarea> for editing. Enable the Ace editor for syntax highlighting, block selection, and other advanced features: 
# in ~/.nbrc
export NB_ACE_ENABLED=1
On next form load, nb automatically downloads and installs Ace from GitHub and enables it in nb browse edit --gui and nb browse add --gui.

​
Adding Notes in the Browser

Use the + link on any listing page, or open the add view directly: 
nb browse add
nb b a

# add in a specific notebook and folder
nb browse add text:formats/
Pre-populate the new note from the command line: 
nb browse add --title "Example Title" --content "Example content." --tags tag1,tag2

❯nb · home : +

[# Example Title                                    ]
[                                                   ]
[#tag1 #tag2                                        ]
[                                                   ]
[Example content.                                   ]

[add]

​
Deleting Items in the Browser

Use the - link on the edit page, or open the delete view directly: 
nb browse delete example:4
nb b d example:4

❯nb · example : 4 · ↓ · edit · - | +

              deleting

[4] example_file.md "Example Title"

              [delete]

​
Portability and Dependencies

nb browse adapts gracefully based on available tools:

Full Feature Set

ncat or socat and pandoc are available. All features including Ace editor support work as expected.

Pure Bash Fallback

When neither ncat nor socat is available and Bash 5.2+ is present, nb browse uses a built-in pure Bash server. All features except the Ace editor are supported.

pandoc Only

With only pandoc (no ncat/socat), items are rendered but [[wiki-style links]] navigate to the raw, unrendered file.

No pandoc

When socat, ncat, or Bash 5.2+ is available without pandoc, files in plain text formats are rendered with the original markup unconverted.

No Server Tool

Without ncat, socat, Bash 5.2+, or pandoc, nb browse falls back to the default behavior of nb show.
Use --print to render an item to standard output without starting a server — useful in environments where no server tool is available: 
nb browse --print example:42
On Windows, socat from MSYS or Cygwin is recommended for the best nb browse experience.

​
AsciiDoc Support

To browse items in AsciiDoc format, install asciidoctor. nb browse will automatically use it to render .adoc files.

​
Privacy

nb browse is entirely self-contained. All CSS, JavaScript, HTTP request parsing, and response building run locally within nb itself, with no external imports or frameworks. Additional privacy measures include:
  • Page content is cached inside each bookmark file, so previously bookmarked pages are readable offline without re-requesting the URL.
  • <img> tags in bookmarked content are stripped to prevent image-load tracking requests.
  • Outbound links are rewritten through an exit page redirect to avoid leaking the referer header.
  • All pages include <meta name="referrer" content="no-referrer" />.
  • Links carry rel="noopener noreferrer".
  • lynx is opened with -noreferer.
Terminal browsers such as w3m and Links do not execute JavaScript, so analytics scripts embedded in bookmarked pages cannot track your browsing sessions.

​
Shortcut Alias

nb browse can always be shortened to nb b: 
# open the current notebook
nb b

# open a specific item
nb b example:123

# open a notebook in the GUI browser
nb b sample: -g

Build docs developers (and LLMs) love

Get started for freeTalk to us