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.

Pinning lets you promote the items that matter most — a daily note, an active project reference, or a high-priority todo — so they always appear at the top of every listing. Pinned items are marked with a 📌 indicator in nb, nb ls, and nb browse, making them impossible to miss no matter how many other items are in the notebook.

​
Pinning and Unpinning Items

Use nb pin to pin an item and nb unpin to remove the pin. Pass the item’s ID, filename, or title as the selector.
1

Start with a normal listing

❯ nb
home
----
[5] Title Five
[4] Title Four
[3] Title Three
[2] Title Two
[1] Title One
2

Pin two items

❯ nb pin 4
Pinned: [4] four.md "Title Four"

❯ nb pin 1
Pinned: [1] one.md "Title One"
3

Pinned items appear first

❯ nb
home
----
[4] 📌 Title Four
[1] 📌 Title One
[5] Title Five
[3] Title Three
[2] Title Two
4

Unpin an item

❯ nb unpin 4
Unpinned: [4] four.md "Title Four"

❯ nb
home
----
[1] 📌 Title One
[5] Title Five
[4] Title Four
[3] Title Three
[2] Title Two
Pinned items remain at the top in nb browse as well, so they are equally prominent when navigating in a terminal or GUI browser.

​
How Pinning Works: The .pindex File

When you pin an item, nb records it in a .pindex file stored in the same notebook or folder. This plain-text file lists the basenames of pinned items, one per line. Because .pindex lives alongside your notes and is tracked by Git, pinned state is preserved across machines and clones.
The .pindex file is managed automatically by nb pin and nb unpin. You do not need to edit it by hand.

​
Pattern-Based Pinning with NB_PINNED_PATTERN

For a more dynamic approach, nb can be configured to treat any item matching a search pattern as pinned. Set the $NB_PINNED_PATTERN environment variable in your ~/.nbrc file to the desired tag or pattern. To pin all items tagged with #pinned: 
export NB_PINNED_PATTERN="#pinned"
With this setting, any note, bookmark, or todo that contains #pinned will automatically appear at the top of listings — no manual nb pin command required. To tag an item for automatic pinning: 
nb add --title "Daily Note" --tags pinned "Today's priorities."
Pattern-based pinning is ideal for workflows where the “pinned” status should travel with the content itself. Tagging with #pinned means the item floats to the top on every machine that has NB_PINNED_PATTERN configured.

​
Customizing the Pin Indicator

All indicator icons in nb are configurable. To use a different character for the pin indicator, set $NB_INDICATOR_PINNED in your ~/.nbrc: 
export NB_INDICATOR_PINNED="💖"

❯ nb
home
----
[1] 💖 Title One
[5] Title Five
[4] Title Four
[3] Title Three
[2] Title Two

​
Use Case Examples

Daily Note

Pin your daily log or journal entry each morning so it’s always the first item in your home notebook.
nb pin 7

Reference Document

Keep a cheat sheet or style guide pinned in a project notebook for quick access while working.
nb pin project:1

Active Todo

Pin the most urgent todo so it stays visible at the top of the list until it’s done.
nb pin 3
# when complete:
nb unpin 3

Tag-Based Pinning

Use NB_PINNED_PATTERN to automatically pin anything tagged #active, keeping your workflow self-organizing.
# in ~/.nbrc
export NB_PINNED_PATTERN="#active"
To move an item to the top of the list temporarily without committing a persistent pin, see the bump plugin.

Build docs developers (and LLMs) love

Get started for freeTalk to us