Notebook Navigator

https://notebooknavigator.com/docs.html
Admin
Notebook Navigator is an Obsidian plugin that enhances note management and navigation with a...
Tokens:31,921
Snippets:349
Trust Score:5.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Register file context menu items

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Examples for handling single and multiple file selections within the file context menu.

```typescript
import type { NotebookNavigatorAPI } from './notebook-navigator';

const nn = app.plugins.plugins['notebook-navigator']?.api as Partial<NotebookNavigatorAPI> | undefined;

const dispose = nn?.menus?.registerFileMenu(({ addItem, file, selection }) => {
  if (selection.mode !== 'single') {
    return;
  }

  if (file.extension !== 'md') {
    return;
  }

  addItem(item => {
    item.setTitle('My action').setIcon('lucide-wand').onClick(() => {
      console.log('Clicked', file.path);
    });
  });
});

// If dispose is defined, call dispose() when your plugin unloads
```

```typescript
const dispose = nn?.menus?.registerFileMenu(({ addItem, selection }) => {
  if (selection.mode !== 'multiple') {
    return;
  }

  addItem(item => {
    item.setTitle('My batch action').setIcon('lucide-list-check').onClick(() => {
      console.log('Selected files', selection.files.map(f => f.path));
    });
  });
});
```

--------------------------------

### ExternalIconProviderController Key Methods

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fservice-architecture

Interface definitions for managing external icon pack installation, updates, and provider synchronization.

```typescript
initialize(): Promise<void>
dispose(): void
installProvider(id: ExternalIconProviderId, options?: InstallOptions): Promise<void>
removeProvider(id: ExternalIconProviderId, options?: RemoveOptions): Promise<void>
syncWithSettings(): Promise<void>
isProviderInstalled(id: ExternalIconProviderId): boolean
isProviderDownloading(id: ExternalIconProviderId): boolean
getProviderVersion(id: ExternalIconProviderId): string | null
```

--------------------------------

### Define a custom dark-mode theme

Source: https://notebooknavigator.com/docs.html?doc=developer%2Ftheming-guide

A comprehensive example of overriding all supported --nn-theme-* CSS variables to create a JetBrains Darcula-inspired dark theme.

```css
.theme-dark {
  /* Foreground colors */
  --nn-theme-foreground: #a9b7c6;
  --nn-theme-foreground-muted: #7f8b91;
  --nn-theme-foreground-faded: #6e6e6e;
  --nn-theme-foreground-faint: #4f565a;

  /* Navigation pane */
  --nn-theme-nav-bg: #3c3f41;
  --nn-theme-nav-separator-color: #6e6e6e;
  --nn-theme-nav-separator-background: var(--nn-theme-nav-separator-color);
  --nn-theme-nav-separator-height: 1px;
  --nn-theme-nav-separator-opacity: 0.35;
  --nn-theme-nav-indent-guide-color: rgba(127, 139, 145, 0.65);
  --nn-theme-nav-leader-color: rgba(127, 139, 145, 0.65);
  --nn-theme-pinned-shortcut-shadow-color: rgba(0, 0, 0, 0.2);

  /* Navigation items */
  --nn-theme-navitem-chevron-color: #6e6e6e;
  --nn-theme-navitem-icon-color: #afb1b3;
  --nn-theme-navitem-name-color: #a9b7c6;
  --nn-theme-navitem-file-name-color: #a9b7c6;
  --nn-theme-navitem-name-font-weight: 400;
  --nn-theme-navitem-custom-color-name-font-weight: 600;
  --nn-theme-navitem-folder-note-name-decoration: underline;
  --nn-theme-navitem-folder-note-name-hover-decoration: underline;
  --nn-theme-navitem-border-radius: 3px;
  --nn-theme-navitem-border-width: 1px;
  --nn-theme-navitem-custom-border-color: rgba(0, 0, 0, 0.18);
  --nn-theme-navitem-hover-bg: #4b5059;
  --nn-theme-navitem-hover-border-color: rgba(255, 255, 255, 0.18);
  --nn-theme-tag-positive-bg: rgba(106, 135, 89, 0.2);
  --nn-theme-tag-negative-bg: rgba(219, 80, 80, 0.2);

  /* Navigation selection */
  --nn-theme-navitem-selected-bg: #4a78c8;
  --nn-theme-navitem-selected-border-color: rgba(255, 255, 255, 0.25);
  --nn-theme-navitem-selected-chevron-color: #c5c5c5;
  --nn-theme-navitem-selected-icon-color: #e6e6e6;
  --nn-theme-navitem-selected-name-color: #ffffff;
  --nn-theme-navitem-selected-inactive-bg: #464c55;
  --nn-theme-navitem-selected-inactive-border-color: rgba(255, 255, 255, 0.14);
  --nn-theme-navitem-selected-inactive-chevron-color: #9da2ab;
  --nn-theme-navitem-selected-inactive-icon-color: #b9bec6;
  --nn-theme-navitem-selected-inactive-name-color: #cfd3da;

  /* File counts */
  --nn-theme-navitem-count-color: #7f8b91;
  --nn-theme-navitem-count-font-weight: 400;
  --nn-theme-navitem-count-bg: transparent;
  --nn-theme-navitem-count-border-radius: 3px;
  --nn-theme-navitem-count-border-width: 1px;
  --nn-theme-navitem-count-border-color: rgba(255, 255, 255, 0.2);
  --nn-theme-navitem-selected-count-color: #e6e6e6;
  --nn-theme-navitem-selected-count-bg: rgba(0, 0, 0, 0.2);
  --nn-theme-navitem-selected-count-border-color: rgba(255, 255, 255, 0.3);
  --nn-theme-navitem-selected-inactive-count-color: #b9bec6;
  --nn-theme-navitem-selected-inactive-count-bg: rgba(0, 0, 0, 0.25);
  --nn-theme-navitem-selected-inactive-count-border-color: rgba(255, 255, 255, 0.2);

  /* List pane */
  --nn-theme-list-bg: #2b2b2b;
  --nn-theme-list-search-active-bg: #515336;
  --nn-theme-list-search-border-color: #3c3c3c;
  --nn-theme-list-separator-color: #3c3c3c;

  /* Group headers */
  --nn-theme-list-group-header-color: #7f8b91;
  --nn-theme-list-group-header-font-weight: 600;
```

--------------------------------

### Metadata Management

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Methods for getting and setting metadata for folders, tags, and properties. Updates are partial, where null values clear properties and undefined/missing values leave them unchanged.

```APIDOC
## getFolderMeta(folder)

### Description
Retrieves all metadata associated with a specific folder.

### Parameters
- **folder** (TFolder) - Required - The folder object to query.

### Returns
- **FolderMetadata | null** - The metadata object or null if not found.

## setFolderMeta(folder, meta)

### Description
Performs a partial update of folder metadata.

### Parameters
- **folder** (TFolder) - Required - The folder object to update.
- **meta** (FolderMetadataUpdate) - Required - The metadata properties to update.

## getTagMeta(tag)

### Description
Retrieves all metadata associated with a specific tag.

### Parameters
- **tag** (string) - Required - The tag name.

### Returns
- **TagMetadata | null** - The metadata object or null if not found.

## setTagMeta(tag, meta)

### Description
Performs a partial update of tag metadata.

### Parameters
- **tag** (string) - Required - The tag name.
- **meta** (TagMetadataUpdate) - Required - The metadata properties to update.

## getPropertyMeta(nodeId)

### Description
Retrieves all metadata associated with a property node.

### Parameters
- **nodeId** (string) - Required - The ID of the property node.

### Returns
- **PropertyMetadata | null** - The metadata object or null if not found.

## setPropertyMeta(nodeId, meta)

### Description
Performs a partial update of property node metadata.

### Parameters
- **nodeId** (string) - Required - The ID of the property node.
- **meta** (PropertyMetadataUpdate) - Required - The metadata properties to update.
```

--------------------------------

### whenReady()

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Returns a promise that resolves when the initial storage bootstrap is complete.

```APIDOC
## whenReady()

### Description
Returns a promise that resolves when the initial storage bootstrap completes.

### Returns
- **Promise<void>** - A promise that resolves when ready.
```

--------------------------------

### Initialize plugin services in TypeScript

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fservice-architecture

This sequence occurs during plugin startup in src/main.ts to instantiate core services and controllers.

```typescript
// Database and settings load happen before this block
this.preferencesController.initializeRecentDataManager();
this.recentNotesService = new RecentNotesService(this);

// Initialize workspace and homepage coordination
this.workspaceCoordinator = new WorkspaceCoordinator(this);
this.homepageController = new HomepageController(this, this.workspaceCoordinator);

// Initialize services
this.tagTreeService = new TagTreeService();
this.propertyTreeService = new PropertyTreeService();
this.metadataService = new MetadataService(
  this.app,
  this,
  () => this.tagTreeService,
  () => this.propertyTreeService
);
this.tagOperations = new TagOperations(
  this.app,
  () => this.settings,
  () => this.tagTreeService,
  () => this.metadataService
);
this.propertyOperations = new PropertyOperations(
  this.app,
  () => this.settings,
  () => this.saveSettingsAndUpdate(),
  () => this.propertyTreeService,
  mutator => this.preferencesController.updateCollapsedPinnedContexts(mutator)
);
this.commandQueue = new CommandQueueService();
this.folderNoteSidebarService = new FolderNoteSidebarService(this);
this.folderNoteSidebarService.start();
this.fileSystemOps = new FileSystemOperations(
  this.app,
  () => this.tagTreeService,
  () => this.propertyTreeService,
  () => this.commandQueue,
  () => this.metadataService,
  (): VisibilityPreferences => ({
    includeDescendantNotes: this.preferencesController.getUXPreferences().includeDescendantNotes,
    showHiddenItems: this.preferencesController.getUXPreferences().showHiddenItems
  }),
  this
);
this.omnisearchService = new OmnisearchService(this.app);
this.api = new NotebookNavigatorAPI(this, this.app);
this.metadataService.setFolderStyleChangeListener(folderPath => {
  if (this.isUnloading || !this.api) {
    return;
  }

  this.api[INTERNAL_NOTEBOOK_NAVIGATOR_API].metadata.emitFolderChangedForPath(folderPath);
});
this.releaseCheckService = new ReleaseCheckService(this);
recordStartupDiagnostic('services.initialized');

const iconService = getIconService();
iconService.registerProvider(new VaultIconProvider(this.app));
if (this.hasEnabledExternalIconProviders()) {
  this.syncExternalIconController();
}

this.registerSettingsUpdateListener('external-icon-controller', () => {
  if (this.externalIconController || this.hasEnabledExternalIconProviders()) {
    this.syncExternalIconController();
  }
});
```

--------------------------------

### registerFileMenu(callback)

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Registers a callback to add items to the file context menu. The callback receives a context object containing the clicked file, selection mode, and a method to add menu items.

```APIDOC
## registerFileMenu(callback)

### Description
Registers a callback to add items to the file context menu. Available since API version 1.2.0.

### Parameters
- **callback** (function) - Required - A function that receives a context object with `addItem`, `file`, and `selection` properties.

### Returns
- **dispose** (function) - A function to unregister the menu hook.
```

--------------------------------

### Subscribe to Navigator Events

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Demonstrates how to listen for persistent and one-time events, and how to manage listener lifecycles using references.

```typescript
// Subscribe to pin changes
nn.on('pinned-files-changed', ({ files }) => {
  console.log(`Total pinned files: ${files.size}`);
  for (const [path, context] of files) {
    console.log(`${path} - folder: ${context.folder}, tag: ${context.tag}`);
  }
});

// Use 'once' for one-time events (auto-unsubscribes)
nn.once('storage-ready', () => {
  // Wait for storage to be ready before storage-backed navigation/tag/property lookups
  console.log('Storage is ready - initial mirror bootstrap is complete');
  // No need to unsubscribe, it's handled automatically
});

// Use 'on' for persistent listeners
const navRef = nn.on('nav-item-changed', ({ item }) => {
  if (item.type === 'folder') {
    console.log('Folder selected:', item.folder.path);
  } else if (item.type === 'tag') {
    console.log('Tag selected:', item.tag);
  } else if (item.type === 'property') {
    console.log('Property selected:', item.property);
  } else {
    console.log('Navigation selection cleared');
  }
});

const selectionRef = nn.on('selection-changed', ({ state }) => {
  // TypeScript knows 'state' is SelectionState with files and focused
  console.log(`${state.files.length} files selected`);
});

// Unsubscribe from persistent listeners
nn.off(navRef);
nn.off(selectionRef);
```

--------------------------------

### Initialize Navigation Pane Data and Virtualization

Source: https://notebooknavigator.com/docs.html?doc=developer%2Frendering-architecture

Hooks for retrieving navigation data and configuring the virtualized scroll container for the navigation pane.

```typescript
const { items, pathToIndex, shortcutItems } = useNavigationPaneData({
  settings,
  isVisible,
  sourceState: props.navigationSourceState,
  treeSections: props.navigationTreeSections,
  folderDecorationModel: props.folderDecorationModel,
  navRainbowState: props.navRainbowState,
  shortcutsExpanded: shortcuts.shortcutsExpanded,
  recentNotesExpanded: shortcuts.recentNotesExpanded,
  pinShortcuts: uiState.pinShortcuts && settings.showShortcuts,
  sectionOrder
});

const { rowVirtualizer, scrollContainerRefCallback, requestScroll } = useNavigationPaneScroll({
  items,
  pathToIndex,
  isVisible,
  activeShortcutKey: shortcuts.activeShortcutKey,
  scrollMargin: navigationScrollMargin,
  scrollPaddingEnd
});
```

--------------------------------

### Manage Metadata and Pinned Files

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Demonstrates how to update folder appearance using partial metadata objects and how to pin files within specific or global contexts.

```typescript
// Set folder appearance
const folder = app.vault.getFolderByPath('Projects');
if (folder) {
  await nn.metadata.setFolderMeta(folder, {
    color: '#FF5733', // Hex, or 'red', 'rgb(255, 87, 51)', 'hsl(9, 100%, 60%)'
    backgroundColor: '#FFF3E0', // Light background color
    icon: 'folder-open'
  });

  // Update only specific properties (other properties unchanged)
  await nn.metadata.setFolderMeta(folder, { color: 'blue' });
}

// Pin a file
const file = app.workspace.getActiveFile();
if (file) {
  await nn.metadata.pin(file); // Pins in folder, tag, and property contexts by default

  // Or pin in specific context
  await nn.metadata.pin(file, 'folder');

  // Check if pinned
  if (nn.metadata.isPinned(file, 'folder')) {
    console.log('Pinned in folder context');
  }
}

// Get all pinned files with context info
const pinned = nn.metadata.getPinned();
// Returns: Map<string, { folder: boolean, tag: boolean, property: boolean }>
// Example: Map { "Notes/todo.md" => { folder: true, tag: false, property: true }, ... }

// Iterate over pinned files
for (const [path, context] of pinned) {
  if (context.folder) {
    console.log(`${path} is pinned in folder view`);
  }
}
```

--------------------------------

### Initialize List Pane Hooks

Source: https://notebooknavigator.com/docs.html?doc=developer%2Frendering-architecture

Use useListPaneData to prepare list items and metadata, and useListPaneScroll to manage virtualized scrolling behavior.

```typescript
const { listItems, filePathToIndex, orderedFiles } = useListPaneData({
  selectionType,
  selectedFolder,
  selectedTag,
  selectedProperty,
  settings,
  activeProfile,
  groupBy: effectiveAppearanceSettings.groupBy,
  pinnedGroupExpanded,
  collapsedListGroups,
  searchProvider,
  searchQuery: !isManualSortEditActive && isSearchActive ? debouncedSearchQuery : undefined,
  searchTokens: !isManualSortEditActive && isSearchActive ? debouncedSearchTokens : undefined,
  visibility: { includeDescendantNotes, showHiddenItems },
  propertySortOrderOverride
});

const { rowVirtualizer, scrollContainerRefCallback, handleScrollToTop } = useListPaneScroll({
  enabled: !isManualSortEditActive,
  listItems,
  filePathToIndex,
  selectedFile,
  selectedFolder,
  selectedTag,
  selectedProperty,
  settings,
  folderSettings: effectiveAppearanceSettings,
  isVisible,
  selectionState,
  selectionDispatch,
  searchQuery: !isManualSortEditActive && isSearchActive ? debouncedSearchQuery : undefined,
  suppressSearchTopScrollRef,
  topSpacerHeight: effectiveTopSpacerHeight,
  includeDescendantNotes,
  groupCollapseStateSignature,
  visiblePropertyKeys: visibleListPropertyKeys,
  visiblePropertyKeySignature,
  hiddenTagVisibility,
  scrollMargin: 0,
  scrollPaddingEnd
});
```

--------------------------------

### Configure Notebook Navigator Hotkeys

Source: https://notebooknavigator.com/docs.html

Define custom key bindings for specific actions within the keyboardShortcuts section of the plugin's data.json file.

```json
"pane:move-up": [ { "key": "ArrowUp", "modifiers": [] }, { "key": "K", "modifiers": [] } ]
```

--------------------------------

### Core API Methods

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Methods for interacting with the Notebook Navigator plugin state and event system.

```APIDOC
## getVersion()

### Description
Returns the current version of the API.

### Returns
- **string** - The API version string.

## isStorageReady()

### Description
Checks if the initial storage bootstrap process is complete.

### Returns
- **boolean** - True if storage is ready, false otherwise.

## whenReady()

### Description
Returns a promise that resolves when the initial storage bootstrap is complete.

### Returns
- **Promise<void>**

## on(event, callback)

### Description
Subscribes to a specific typed event.

### Parameters
- **event** (NotebookNavigatorEventType) - The event name to subscribe to.
- **callback** (function) - The function to execute when the event triggers.

### Returns
- **EventRef** - A reference to the subscription for later unsubscription.

## once(event, callback)

### Description
Subscribes to a specific typed event once; the subscription is automatically removed after the first trigger.

### Parameters
- **event** (NotebookNavigatorEventType) - The event name to subscribe to.
- **callback** (function) - The function to execute when the event triggers.

### Returns
- **EventRef** - A reference to the subscription.

## off(ref)

### Description
Unsubscribes from a previously registered event using its reference.

### Parameters
- **ref** (EventRef) - The reference returned by on or once.
```

--------------------------------

### reveal(file)

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Reveals and selects a file in the navigator, expanding parent folders and switching views as necessary.

```APIDOC
## reveal(file)

### Description
Reveals and selects a file in the navigator. This method opens the view if closed, expands parent folders, and focuses the file.

### Parameters
- **file** (TFile | string) - Required - The file object or path string to reveal.

### Returns
- **Promise<boolean>** - Returns true if successful, false if the file cannot be resolved or the view cannot be opened.
```

--------------------------------

### Navigate to tags and properties

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Use these methods to focus on specific tags or property nodes. Always ensure the plugin is ready before attempting navigation to avoid errors.

```typescript
// Wait for storage if needed, then navigate
await nn.whenReady();

await nn.navigation.navigateToTag('#work');
await nn.navigation.navigateToProperty('key:status=done');
```

--------------------------------

### Define Notebook Navigator Settings Interface

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fstorage-architecture

The primary interface for managing plugin settings, including vault profiles, synchronization modes, and various metadata maps for files, folders, tags, and properties.

```typescript
export interface NotebookNavigatorSettings {
  vaultProfiles: VaultProfile[];
  vaultProfile: string;
  syncModes: Record<SyncModeSettingId, SettingSyncMode>;

  // ... settings omitted

  customVaultName: string;
  pinnedNotes: PinnedNotes;

  fileIcons: Record<string, string>;
  fileColors: Record<string, string>;
  fileBackgroundColors: Record<string, string>;
  folderIcons: Record<string, string>;
  folderColors: Record<string, string>;
  folderBackgroundColors: Record<string, string>;
  folderSortOverrides: Record<string, ListSortOverrideValue>;
  folderTreeSortOverrides: Record<string, AlphaSortOrder>;
  folderAppearances: Record<string, FolderAppearance>;

  tagIcons: Record<string, string>;
  tagColors: Record<string, string>;
  tagBackgroundColors: Record<string, string>;
  tagSortOverrides: Record<string, ListSortOverrideValue>;
  tagTreeSortOverrides: Record<string, AlphaSortOrder>;
  tagAppearances: Record<string, TagAppearance>;
  propertyIcons: Record<string, string>;
  propertyColors: Record<string, string>;
  propertyBackgroundColors: Record<string, string>;
  propertySortOverrides: Record<string, ListSortOverrideValue>;
  propertyTreeSortOverrides: Record<string, AlphaSortOrder>;
  propertyAppearances: Record<string, FolderAppearance>;
  virtualFolderColors: Record<string, string>;
  virtualFolderBackgroundColors: Record<string, string>;

  navigationSeparators: Record<string, boolean>;
  userColors: string[];
  lastShownVersion: string;
  rootFolderOrder: string[];
  rootTagOrder: string[];
  rootPropertyOrder: string[];
}
```

--------------------------------

### Event Subscription Methods

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Methods for managing event listeners in the NotebookNavigator SDK.

```APIDOC
## nn.on(event, callback)

### Description
Registers a persistent listener for a specific event. The listener will be invoked every time the event is emitted.

### Parameters
- **event** (string) - Required - The name of the event to subscribe to.
- **callback** (function) - Required - The function to execute when the event occurs.

## nn.once(event, callback)

### Description
Registers a one-time listener for a specific event. The listener is automatically removed after the first time the event is emitted.

### Parameters
- **event** (string) - Required - The name of the event to subscribe to.
- **callback** (function) - Required - The function to execute when the event occurs.

## nn.off(listenerRef)

### Description
Removes a previously registered persistent listener.

### Parameters
- **listenerRef** (object) - Required - The reference returned by the 'on' method.
```

--------------------------------

### isStorageReady()

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Checks if the initial storage bootstrap process is complete.

```APIDOC
## isStorageReady()

### Description
Checks if the initial storage bootstrap is complete.

### Returns
- **boolean** - True if storage is ready, false otherwise.
```

--------------------------------

### HomepageController Key Methods

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fservice-architecture

Interface definition for the HomepageController, responsible for resolving and opening the configured homepage.

```typescript
resolveHomepageFile(): TFile | null
canOpenHomepage(): boolean
handleWorkspaceReady(options: { shouldActivateOnStartup: boolean }): Promise<void>
open(trigger: 'startup' | 'command'): Promise<boolean>
```

--------------------------------

### FileSystemService Interface Methods

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fservice-architecture

Defines the primary methods for managing files, folders, and system-level operations within the vault.

```typescript
createNewFolder(parent: TFolder, onSuccess?: (path: string) => void): Promise<void>
createNewFile(parent: TFolder, openInNewTab?: boolean, manualSortContext?: ManualSortNewFilePlacementContext | null): Promise<TFile | null>
createNewFileForTag(
  tagPath: string,
  sourcePath?: string,
  openInNewTab?: boolean,
  manualSortContext?: ManualSortNewFilePlacementContext | null
): Promise<TFile | null>
createNewFileForProperty(
  propertyNodeId: string,
  sourcePath?: string,
  openInNewTab?: boolean,
  manualSortContext?: ManualSortNewFilePlacementContext | null
): Promise<TFile | null>
renameFolderToName(folder: TFolder, newName: string, settings?: NotebookNavigatorSettings): Promise<boolean>
renameFolderDisplayName(folder: TFolder, value: string, settings?: NotebookNavigatorSettings): Promise<boolean>
renameFile(file: TFile): Promise<void>
renameFileDisplayName(file: TFile, rawInput: string): Promise<boolean>
renameFileToName(file: TFile, rawInput: string): Promise<boolean>
deleteFolder(folder: TFolder, confirmBeforeDelete: boolean, onSuccess?: () => void): Promise<void>
deleteFile(file: TFile, confirmBeforeDelete: boolean, onSuccess?: () => void, preDeleteAction?: () => Promise<void>): Promise<void>
deleteSelectedFile(
  file: TFile,
  settings: NotebookNavigatorSettings,
  selectionContext: SelectionContext,
  selectionDispatch: SelectionDispatch,
  confirmBeforeDelete: boolean
): Promise<void>
duplicateNote(file: TFile): Promise<void>
duplicateFolder(folder: TFolder): Promise<void>
isDescendant(parent: TAbstractFile, child: TAbstractFile): boolean

moveFilesToFolder(options: MoveFilesOptions): Promise<MoveFilesResult>
moveFilesWithModal(
  files: TFile[],
  selectionContext?: {
    selectedFile: TFile | null;
    dispatch: SelectionDispatch;
    allFiles: TFile[];
  }
): Promise<void>
moveFolderWithModal(
  folder: TFolder
): Promise<
  | { status: 'success'; data: MoveFolderResult }
  | { status: 'cancelled' }
  | { status: 'error'; error: unknown }
>
moveFolderToTarget(folder: TFolder, targetFolder: TFolder): Promise<MoveFolderResult>

convertFileToFolderNote(file: TFile, settings: NotebookNavigatorSettings): Promise<void>
setFileAsFolderNote(file: TFile, settings: NotebookNavigatorSettings): Promise<void>

deleteMultipleFiles(
  files: TFile[],
  confirmBeforeDelete: boolean,
  preDeleteAction?: () => void | Promise<void>
): Promise<void>
trashFilesWithOpenLeafCleanup(files: readonly TFile[]): Promise<FileTrashResult>
deleteFilesWithSmartSelection(
  selectedFiles: Set<string>,
  allFiles: readonly TFile[],
  selectionDispatch: SelectionDispatch,
  confirmBeforeDelete: boolean
): Promise<void>

createCanvas(parent: TFolder): Promise<TFile | null>
createBase(parent: TFolder): Promise<TFile | null>
createNewDrawing(parent: TFolder, type?: 'excalidraw' | 'tldraw'): Promise<TFile | null>
applyPropertyNodeToFiles(propertyNodeId: string, files: readonly TFile[]): Promise<ApplyPropertyNodeResult>
setManualSortNewFileContextProvider(provider: (() => ManualSortNewFilePlacementContext | null) | null): () => void
getManualSortNewFileContextForTarget(
  targetType: ManualSortNewFilePlacementContext['targetType'],
  targetKey: string,
  options?: { waitForSelectionUpdate?: boolean }
): Promise<ManualSortNewFilePlacementContext | null>

openVersionHistory(file: TFile): Promise<void>
getRevealInSystemExplorerText(): string
revealInSystemExplorer(file: TFile | TFolder): Promise<void>
openInDefaultApp(file: TFile | TFolder): Promise<void>
```

--------------------------------

### Define DebugLoggingService methods and helpers

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fservice-architecture

Lists the instance methods and module helpers available in the DebugLoggingService for tracking startup events and diagnostic reporting.

```typescript
// Instance methods
initialize(): void
dispose(): void
isEnabled(): boolean
isActive(): boolean
getLogPath(): string
setEnabled(enabled: boolean): void
recordStartupEvent(event: string, details?: Record<string, unknown>): void
recordStorageReady(details: Record<string, unknown>): void
recordUserVisible(details?: Record<string, unknown>): void
finishStartupReport(reason: string, details?: Record<string, unknown>): void
logReport(title: string, details: Record<string, unknown>): void
recordContentProviderBatch(summary: ContentProviderBatchSummary): void
flush(): Promise<void>

// Module helpers
recordStartupDiagnostic(event: string, details?: Record<string, unknown>): void
finishStartupDiagnostics(details: Record<string, unknown>): void
recordStartupUserVisible(details?: Record<string, unknown>): void
recordDebugReport(title: string, details: Record<string, unknown>): void
recordContentProviderBatch(summary: ContentProviderBatchSummary): void
```

--------------------------------

### nn.metadata.pin(file)

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Pins a specific file within the Notebook Navigator context.

```APIDOC
## nn.metadata.pin(file)

### Description
Pins the provided file in folder, tag, and property contexts within Notebook Navigator.

### Parameters
- **file** (TFile) - Required - The Obsidian file object to be pinned.

### Example
```javascript
await nn.metadata.pin(file);
```
```

--------------------------------

### getVersion()

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Retrieves the current API version string.

```APIDOC
## getVersion()

### Description
Returns the current version string of the Notebook Navigator API.

### Returns
- **string** - The API version.
```

--------------------------------

### navigateToFolder(folder)

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Selects a folder in the navigation pane and expands its parent hierarchy.

```APIDOC
## navigateToFolder(folder)

### Description
Selects a folder in the navigation pane. It ensures the view is open and expands parent folders to make the target visible.

### Parameters
- **folder** (TFolder | string) - Required - The folder object or path string to select.

### Returns
- **Promise<boolean>** - Returns true if successful, false if the folder cannot be resolved or the view cannot be opened.
```

--------------------------------

### WorkspaceCoordinator Key Methods

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fservice-architecture

Interface definitions for coordinating navigator views, calendar leaf placement, and file reveal logic.

```typescript
activateNavigatorView(): Promise<WorkspaceLeaf | null>
getNavigatorLeaves(): WorkspaceLeaf[]
detachCalendarViewLeaves(): void
ensureCalendarViewInRightSidebar(options?: {
  reveal?: boolean
  activate?: boolean
  shouldContinue?: () => boolean
}): Promise<WorkspaceLeaf | null>
revealFileInActualFolder(file: TFile, options?: RevealFileOptions): void
revealFileInNearestFolder(file: TFile, options?: RevealFileOptions): void
```

--------------------------------

### Register folder context menu items

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Adds custom actions to the folder context menu using the folder path.

```typescript
const dispose = nn?.menus?.registerFolderMenu(({ addItem, folder }) => {
  addItem(item => {
    item.setTitle('My folder action').setIcon('lucide-folder').onClick(() => {
      console.log('Folder', folder.path);
    });
  });
});
```

--------------------------------

### IconService Methods

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fservice-architecture

Interface for managing icon providers, parsing icon identifiers, and rendering icons into DOM elements.

```typescript
registerProvider(provider: IconProvider): void
unregisterProvider(providerId: string): void
getProvider(providerId: string): IconProvider | undefined
getAllProviders(): IconProvider[]
parseIconId(iconId: string): ParsedIconId
formatIconId(provider: string, identifier: string): string
renderIcon(container: HTMLElement, iconId: string, size?: number): void
isValidIcon(iconId: string): boolean
search(query: string, providerId?: string): IconDefinition[]
getAllIcons(providerId?: string): IconDefinition[]
getVersion(): number
subscribe(listener: () => void): () => void
```

--------------------------------

### registerFolderMenu(callback)

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Registers a callback to add items to the folder context menu. Available since API version 1.2.0.

```APIDOC
## registerFolderMenu(callback)

### Description
Registers a callback to add items to the folder context menu. The callback receives a context object containing `addItem` and the `folder` object.

### Parameters
- **callback** (function) - Required - A function that receives a context object with `addItem` and `folder` properties.

### Returns
- **dispose** (function) - A function to unregister the menu hook.
```

--------------------------------

### Define ISettingsProvider interface

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fservice-architecture

Interface for managing application settings, recent notes, icons, and collapsed pinned contexts.

```typescript
interface ISettingsProvider {
  readonly settings: NotebookNavigatorSettings;
  saveSettingsAndUpdate(): Promise<void>;
  notifySettingsUpdate(): void;
  getRecentNotes(): string[];
  setRecentNotes(recentNotes: string[]): void;
  getRecentIcons(): Record<string, string[]>;
  setRecentIcons(recentIcons: Record<string, string[]>): void;
  getCollapsedPinnedContexts(): CollapsedPinnedContexts;
  updateCollapsedPinnedContexts(mutator: (record: CollapsedPinnedContexts) => boolean): boolean;
  getRecentColors(): string[];
  setRecentColors(recentColors: string[]): void;
}
```

--------------------------------

### RecentNotesService Key Methods

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fservice-architecture

Interface definitions for managing the recent notes list in vault-local storage.

```typescript
recordFileOpen(file: TFile): boolean
renameEntry(oldPath: string, newPath: string): boolean
removeEntry(path: string): boolean
```

--------------------------------

### ContentProviderRegistry Interface Methods

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fservice-architecture

Defines the core API for managing content providers, including registration, lookup, settings synchronization, and batch file processing.

```typescript
registerProvider(provider: IContentProvider): void
getProvider(type: ContentProviderType): IContentProvider | undefined
getAllProviders(): IContentProvider[]
getAllRelevantSettings(): (keyof NotebookNavigatorSettings)[]
handleSettingsChange(oldSettings: NotebookNavigatorSettings, newSettings: NotebookNavigatorSettings): Promise<ContentProviderType[]>
queueFilesForAllProviders(
  files: TFile[],
  settings: NotebookNavigatorSettings,
  options?: { include?: ContentProviderType[]; exclude?: ContentProviderType[] }
): void
stopAllProcessing(): void
```

--------------------------------

### Pin Current File via Templater

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Pins the currently active file within the Notebook Navigator context. Requires the plugin to be loaded and accessible via the app object.

```javascript
<%* // Templater script to pin the current file in Notebook Navigator
const nn = app.plugins.plugins['notebook-navigator']?.api;

if (nn) {
  // Pin the current file in folder, tag, and property contexts
  const file = tp.config.target_file;
  await nn.metadata.pin(file);
  new Notice('File pinned in Notebook Navigator');
}
%>
```

--------------------------------

### registerPropertyMenu(callback)

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Registers a callback to add items to the property context menu. Available since API version 2.0.0.

```APIDOC
## registerPropertyMenu(callback)

### Description
Registers a callback to add items to the property context menu. The callback receives a context object containing `addItem` and the `nodeId`.

### Parameters
- **callback** (function) - Required - A function that receives a context object with `addItem` and `nodeId` properties.

### Returns
- **dispose** (function) - A function to unregister the menu hook.
```

--------------------------------

### Define IPropertyTreeProvider interface

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fservice-architecture

Interface for managing property-based tree nodes and collecting file paths based on node IDs or keys.

```typescript
interface IPropertyTreeProvider {
  addTreeUpdateListener(listener: () => void): () => void;
  hasNodes(): boolean;
  findNode(nodeId: string): PropertyTreeNode | null;
  getKeyNode(normalizedKey: string): PropertyTreeNode | null;
  resolveSelectionNodeId(selectionNodeId: PropertySelectionNodeId): PropertySelectionNodeId;
  collectDescendantNodeIds(nodeId: string): Set<string>;
  collectFilePaths(nodeId: string, includeDescendants: boolean): Set<string>;
  collectFilesForKeys(normalizedKeys: Iterable<string>): Set<string>;
}
```

--------------------------------

### Set Folder Color via Templater

Source: https://notebooknavigator.com/docs.html?doc=developer%2Fapi-reference

Updates the metadata for a folder to set a specific color based on the current day of the week.

```javascript
<%* // Set folder color based on day of week
const nn = app.plugins.plugins['notebook-navigator']?.api;
if (nn) {
  const folder = tp.config.target_file.parent;
  const colors = ['#ff6b6b', '#4ecdc4', '#45b7d1', '#96ceb4', '#feca57', '#ff9ff3', '#54a0ff'];
  const dayColor = colors[new Date().getDay()];

  await nn.metadata.setFolderMeta(folder, { color: dayColor });
}
%>
```
Tokens:
Raw