### Local Deployment Script Example

Source: https://github.com/johansan/notebook-navigator/blob/main/scripts/README.md

An example bash script for deploying built plugin files to a local Obsidian vault. This script is intended to be placed in `build-local.sh` and added to `.gitignore`.

```bash
#!/bin/bash
# Copy built files to Obsidian vault
cp main.js manifest.json styles.css ~/Documents/ObsidianVault/.obsidian/plugins/notebook-navigator/
```

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

### Pin File Example

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/api-reference.md

Example using Templater script to pin the current file in Notebook Navigator's folder, tag, and property contexts.

```APIDOC
## Pin File

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

### Method
`app.plugins.plugins['notebook-navigator']?.api.metadata.pin(file: string)`

### Parameters
#### Path Parameters
- **file** (string) - Required - The path to the file to pin.

### Request Example
```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');
}
%>
```

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

### TypeScript Example with Type Definitions

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/api-reference.md

Demonstrates how to use the Notebook Navigator API with TypeScript type definitions for enhanced safety and autocompletion.

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

const nn = app.plugins.plugins['notebook-navigator']?.api as NotebookNavigatorAPI | undefined;
if (!nn) {
  return;
}

await nn.whenReady();

const folder = app.vault.getFolderByPath('Projects');
if (!folder) {
  return;
}

// Icon strings are type-checked at compile time
const icon: IconString = 'ph-folder';
await nn.metadata.setFolderMeta(folder, { color: '#FF5733', icon });

// Events have full type inference
nn.on('selection-changed', ({ state }) => {
  console.log(state.files.length);
});

```

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

### Set Folder Color Example

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/api-reference.md

Example using Templater script to set a folder's color based on the current day of the week.

```APIDOC
## Set Folder Color

### Description
Sets a specific color for a given folder in the Notebook Navigator, based on the day of the week.

### Method
`app.plugins.plugins['notebook-navigator']?.api.metadata.setFolderMeta(folder: string, meta: { color: string })`

### Parameters
#### Path Parameters
- **folder** (string) - Required - The path to the folder.
- **meta** (object) - Required - An object containing metadata, specifically a `color` property.
  - **color** (string) - Required - The color to set for the folder (e.g., hex code).

### Request Example
```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 });
}
%>
```

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

### Customize Hotkey Binding

Source: https://github.com/johansan/notebook-navigator/blob/main/README.md

Example of a hotkey binding in the `data.json` file. Multiple key bindings can be added per action.

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

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

### Initial Render Sequence Diagram

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/rendering-architecture.md

Illustrates the sequence of events from initial container render to the mounting of the Notebook Navigator Component, including data loading and context setup.

```mermaid
sequenceDiagram
    participant V as Vault
    participant DB as IndexedDBStorage
    participant MC as Memory Cache
    participant ST as StorageContext
    participant NC as NotebookNavigatorContainer
    participant SK as SkeletonView
    participant DH as Data Hooks
    participant UI as Virtualized Panes

    NC->>SK: Render while isStorageReady=false
    ST->>DB: Open IndexedDB and load cached records
    DB->>MC: Seed in-memory mirror
    ST->>V: Enumerate vault files (diff input)
    ST->>DB: Reconcile initial diff
    ST->>ST: Register vault + settings listeners
    ST->>NC: Set isStorageReady=true
    NC->>UI: Mount NotebookNavigatorComponent
    ST->>DH: Expose synchronous getters and tag/property trees
    DH->>UI: Build navigation/list item arrays
    UI->>MC: Read data synchronously during render
```

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

### JavaScript Example without Type Definitions

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/api-reference.md

Shows how to use the Notebook Navigator API in plain JavaScript, without relying on TypeScript definitions.

```javascript
// Works without type definitions
const nn = app.plugins.plugins['notebook-navigator']?.api;
if (nn) {
  // Wait for storage if you need storage-backed navigation/tag/property reads
  await nn.whenReady();

  const folder = app.vault.getFolderByPath('Projects');
  if (!folder) {
    return;
  }

  await nn.metadata.setFolderMeta(folder, { color: '#FF5733' });
}

```

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

### Complete Theme Example

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/theming-guide.md

This snippet defines a comprehensive set of CSS variables for theming the Notebook Navigator. It covers styling for file items, text, quick actions, headers, and mobile interfaces. Use these variables to customize the visual appearance of the application.

```css
/* File items */
  --nn-theme-file-name-color: #a9b7c6;
  --nn-theme-file-preview-color: #7f8b91;
  --nn-theme-file-task-icon-color: #afb1b3;
  --nn-theme-file-feature-border-radius: 3px;
  --nn-theme-file-date-color: #6a8759;
  --nn-theme-file-word-count-color: #6a8759;
  --nn-theme-file-parent-color: #cc7832;
  --nn-theme-file-tag-color: #9876aa;
  --nn-theme-file-tag-custom-color-text-color: #ffffff;
  --nn-theme-file-tag-bg: #383a3e;
  --nn-theme-file-property-color: #cc7832;
  --nn-theme-file-property-bg: #383a3e;
  --nn-theme-file-tag-border-radius: 3px;
  --nn-theme-file-property-border-radius: 3px;
  --nn-theme-file-border-radius: 4px;
  --nn-theme-file-selected-bg: #4a78c8;
  --nn-theme-file-selected-name-color: #ffffff;
  --nn-theme-file-selected-preview-color: #c5c5c5;
  --nn-theme-file-selected-date-color: #a5dc86;
  --nn-theme-file-selected-word-count-color: #a5dc86;
  --nn-theme-file-selected-parent-color: #ffd580;
  --nn-theme-file-selected-tag-color: #ffffff;
  --nn-theme-file-selected-tag-bg: #5a5f66;
  --nn-theme-file-selected-property-color: #ffffff;
  --nn-theme-file-selected-property-bg: #5a5f66;
  --nn-theme-file-selected-inactive-bg: #383c45;
  --nn-theme-file-selected-inactive-name-color: #dfe3e8;
  --nn-theme-file-selected-inactive-preview-color: #b9bec6;
  --nn-theme-file-selected-inactive-date-color: #8fb275;
  --nn-theme-file-selected-inactive-word-count-color: #8fb275;
  --nn-theme-file-selected-inactive-parent-color: #e3b173;
  --nn-theme-file-selected-inactive-tag-color: #dfe3e8;
  --nn-theme-file-selected-inactive-tag-bg: #4c5058;
  --nn-theme-file-selected-inactive-property-color: #dfe3e8;
  --nn-theme-file-selected-inactive-property-bg: #4c5058;
  --nn-theme-file-border-width: 1px;
  --nn-theme-file-pill-border-width: 1px;
  --nn-theme-file-selected-border-color: rgba(255, 255, 255, 0.24);
  --nn-theme-file-selected-inactive-border-color: rgba(255, 255, 255, 0.14);
  --nn-theme-file-tag-border-color: rgba(255, 255, 255, 0.2);
  --nn-theme-file-property-border-color: rgba(255, 255, 255, 0.2);
  --nn-theme-file-selected-tag-border-color: rgba(255, 255, 255, 0.3);
  --nn-theme-file-selected-property-border-color: rgba(255, 255, 255, 0.3);

  /* File text styling */
  --nn-theme-list-heading-font-weight: 600;
  --nn-theme-list-group-header-font-weight: 600;
  --nn-theme-file-name-font-weight: 600;
  --nn-theme-file-compact-name-font-weight: 400;
  --nn-theme-file-preview-font-weight: 400;
  --nn-theme-file-date-font-weight: 400;
  --nn-theme-file-word-count-font-weight: 400;
  --nn-theme-file-parent-font-weight: 400;
  --nn-theme-file-tag-font-weight: 400;

  /* Quick actions */
  --nn-theme-quick-actions-bg: rgba(43, 43, 43, 0.95);
  --nn-theme-quick-actions-border: #555555;
  --nn-theme-quick-actions-border-radius: 4px;
  --nn-theme-quick-actions-icon-color: #7f8b91;
  --nn-theme-quick-actions-icon-hover-color: #a9b7c6;
  --nn-theme-quick-actions-separator-color: #3c3c3c;

  /* Headers */
  --nn-theme-header-button-icon-color: #7f8b91;
  --nn-theme-header-button-hover-bg: #4b5059;
  --nn-theme-header-button-active-bg: #4a78c8;
  --nn-theme-header-button-active-icon-color: #ffffff;
  --nn-theme-header-button-disabled-icon-color: #5c5c5c;

  /* Mobile */
  --nn-theme-mobile-bg: #2b2b2b;
  --nn-theme-mobile-list-header-link-color: #589df6;
  --nn-theme-mobile-list-header-breadcrumb-color: #a9b7c6;
  --nn-theme-mobile-list-header-breadcrumb-font-weight: 600;
  --nn-theme-mobile-toolbar-bg: #3c3f41;
  --nn-theme-mobile-toolbar-button-icon-color: #a9b7c6;
  --nn-theme-mobile-toolbar-button-active-bg: #4a78c8;
  --nn-theme-mobile-toolbar-button-active-icon-color: #ffffff;
  --nn-theme-mobile-toolbar-glass-bg: #2b2b2b;
}
```

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

### Set Folder Metadata without Type Definitions

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/api-reference.md

This example shows how to set folder metadata without using TypeScript definitions. It's recommended to use `whenReady()` if your logic depends on storage-backed data.

```javascript
// Works without type definitions
const nn = app.plugins.plugins['notebook-navigator']?.api;
if (nn) {
  // Wait for storage if you need storage-backed navigation/tag/property reads
  await nn.whenReady();

  const folder = app.vault.getFolderByPath('Projects');
  if (!folder) {
    return;
  }

  await nn.metadata.setFolderMeta(folder, { color: '#FF5733' });
}
```

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

### Complete CSS Theme Example

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/theming-guide.md

Apply this CSS to set a comprehensive theme for Notebook Navigator, inspired by the JetBrains Darcula color palette. It defines variables for foreground colors, navigation pane elements, calendar components, navigation items, tag highlights, pinned shortcuts, text styling, pane dividers, and list pane elements.

```css
body {
  /* Theme foreground */
  --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);

  /* Navigation calendar */
  --nn-theme-calendar-header-color: var(--nn-theme-foreground);
  --nn-theme-calendar-weekday-color: var(--nn-theme-foreground-muted);
  --nn-theme-calendar-week-color: var(--nn-theme-foreground-muted);
  --nn-theme-calendar-day-in-month-color: var(--nn-theme-foreground);
  --nn-theme-calendar-day-outside-month-color: var(--nn-theme-foreground-faded);
  --nn-theme-calendar-weekend-bg: rgba(169, 183, 198, 0.1);
  --nn-theme-calendar-hover-bg: #4b5059;
  --nn-theme-calendar-note-indicator-color: #4a78c8;
  --nn-theme-calendar-unfinished-task-indicator-color: #4a78c8;
  --nn-theme-calendar-feature-image-text-color: #ffffff;
  --nn-theme-calendar-feature-image-overlay-color: rgb(0 0 0 / 0.05);
  --nn-theme-calendar-day-today-color: #ffffff;
  --nn-theme-calendar-day-today-bg: #4a78c8;
  --nn-theme-calendar-day-active-border-color: rgba(169, 183, 198, 0.5);

  /* 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-count-color: #7f8b91;
  --nn-theme-navitem-count-bg: transparent;
  --nn-theme-navitem-count-border-radius: 3px;
  --nn-theme-navitem-border-radius: 3px;
  --nn-theme-navitem-hover-bg: #4b5059;
  --nn-theme-navitem-selected-bg: #4a78c8;
  --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-count-color: #e6e6e6;
  --nn-theme-navitem-selected-count-bg: rgba(0, 0, 0, 0.2);
  --nn-theme-navitem-selected-inactive-bg: #464c55;
  --nn-theme-navitem-selected-inactive-name-color: #cfd3da;
  --nn-theme-navitem-selected-inactive-chevron-color: #9da2ab;
  --nn-theme-navitem-selected-inactive-icon-color: #b9bec6;
  --nn-theme-navitem-selected-inactive-count-color: #b9bec6;
  --nn-theme-navitem-selected-inactive-count-bg: rgba(0, 0, 0, 0.25);
  --nn-theme-navitem-border-width: 1px;
  --nn-theme-navitem-count-border-width: 1px;
  --nn-theme-navitem-custom-border-color: rgba(0, 0, 0, 0.18);
  --nn-theme-navitem-hover-border-color: rgba(255, 255, 255, 0.18);
  --nn-theme-navitem-selected-border-color: rgba(255, 255, 255, 0.25);
  --nn-theme-navitem-selected-inactive-border-color: rgba(255, 255, 255, 0.14);
  --nn-theme-navitem-count-border-color: rgba(255, 255, 255, 0.2);
  --nn-theme-navitem-selected-count-border-color: rgba(255, 255, 255, 0.3);
  --nn-theme-navitem-selected-inactive-count-border-color: rgba(255, 255, 255, 0.2);

  /* Tag highlights and drop targets */
  --nn-theme-tag-positive-bg: rgba(106, 135, 89, 0.2);
  --nn-theme-tag-negative-bg: rgba(219, 80, 80, 0.2);

  /* Pinned shortcuts */
  --nn-theme-pinned-shortcut-shadow-color: rgba(0, 0, 0, 0.2);

  /* Navigation text styling */
  --nn-theme-navitem-name-font-weight: 400;
  --nn-theme-navitem-file-name-font-weight: 400;
  --nn-theme-navitem-custom-color-name-font-weight: 600;
  --nn-theme-navitem-custom-color-file-name-font-weight: 600;
  --nn-theme-navitem-folder-note-name-font-weight: 600;
  --nn-theme-navitem-folder-note-name-decoration: underline;
  --nn-theme-navitem-folder-note-name-hover-decoration: underline;
  --nn-theme-navitem-count-font-weight: 400;

  /* Pane divider */
  --nn-theme-divider-border-color: #323232;
  --nn-theme-divider-resize-handle-hover-bg: #4a78c8;

  /* List pane */
  --nn-theme-list-bg: #2b2b2b;
  --nn-theme-list-header-icon-color: #7f8b91;
  --nn-theme-list-header-breadcrumb-color: #7f8b91;
  --nn-theme-list-header-breadcrumb-font-weight: 600;
  --nn-theme-list-search-active-bg: #515336;
  --nn-theme-list-search-border-color: #3c3c3c;
  --nn-theme-list-heading-color: #d0d2d6;
  --nn-theme-list-group-header-color: #7f8b91;
  --nn-theme-list-separator-color: #3c3c3c;


```

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

### External Icon Provider Controller Methods

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/service-architecture.md

Methods for managing external icon packs, including installation, removal, and synchronization with settings.

```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
```

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

### Get API Version

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/api-reference.md

Retrieves the current API version string of the Notebook Navigator plugin.

```APIDOC
## Get API Version

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

### Method
`app.plugins.plugins['notebook-navigator']?.api.getVersion()`

### Response
#### Success Response (200)
- **version** (string) - The API version string (e.g., "2.0.0").
```

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

### Check Storage Ready

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/api-reference.md

Checks if the initial storage bootstrap process for the Notebook Navigator API is complete.

```APIDOC
## Check Storage Ready

### Description
Determines if the Notebook Navigator API's initial storage bootstrap has finished.

### Method
`app.plugins.plugins['notebook-navigator']?.api.isStorageReady()`

### Response
#### Success Response (200)
- **ready** (boolean) - True if storage is ready, false otherwise.
```

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

### Initialize Services in TypeScript

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/service-architecture.md

This snippet shows the sequence of service instantiation within the main TypeScript file during plugin startup. It includes services like RecentNotesService, WorkspaceCoordinator, TagTreeService, and others, demonstrating dependency injection patterns.

```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
);
this.commandQueue = new CommandQueueService();
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);
if (this.settings.searchProvider === 'omnisearch' && !this.omnisearchService.isAvailable()) {
  this.setSearchProvider('internal');
}
this.api = new NotebookNavigatorAPI(this, this.app);
this.metadataService.setFolderStyleChangeListener(folderPath => {
  if (!this.api) {
    return;
  }

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

const iconService = getIconService();
iconService.registerProvider(new VaultIconProvider(this.app));
this.externalIconController = new ExternalIconProviderController(this.app, iconService, this);
const iconController = this.externalIconController;
if (iconController) {
  runAsyncAction(
    async () => {
      await iconController.initialize();
      await iconController.syncWithSettings();
    },
    {
      onError: (error: unknown) => {
        console.error('External icon controller init failed:', error);
      }
    }
  );
}
```

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

### Allowlist Dynamic i18n Keys

Source: https://github.com/johansan/notebook-navigator/blob/main/scripts/README.md

Example of how to keep an intentionally dynamic i18n key from being flagged as unused by adding a specific comment to the code.

```typescript
// unused-strings keep settings.items.example
```

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

### Run Build Script (Bash)

Source: https://github.com/johansan/notebook-navigator/blob/main/scripts/README.md

Executes the main build script for ensuring code quality before deployment using Bash.

```bash
./scripts/build.sh
```

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

### ReleaseCheckService

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/service-architecture.md

Polls GitHub releases and compares versions with the installed plugin. It stores timestamps and latest announced releases in settings and provides pending notices.

```APIDOC
## ReleaseCheckService

### Description
Polls GitHub releases and compares versions with the installed plugin. It stores timestamps and latest announced releases in settings and provides pending notices.

### Methods

- `checkForUpdates(force?: boolean): Promise<ReleaseUpdateNotice | null>`
- `getPendingNotice(): ReleaseUpdateNotice | null`
- `clearPendingNotice(): void`
```

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

### Wait for Storage Ready

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/api-reference.md

Resolves a promise when the initial storage bootstrap for the Notebook Navigator API completes.

```APIDOC
## Wait for Storage Ready

### Description
Provides a promise that resolves once the Notebook Navigator API's initial storage bootstrap is complete.

### Method
`app.plugins.plugins['notebook-navigator']?.api.whenReady()`

### Response
#### Success Response (200)
- The promise resolves when the storage bootstrap is complete.
```

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

### Omnisearch Service Integration

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/service-architecture.md

Provides an interface for interacting with the Omnisearch plugin. Use `isAvailable` to check if the plugin is installed and `search` to perform full-text searches.

```typescript
isAvailable(): boolean
search(query: string, options?: { pathScope?: string }): Promise<OmnisearchHit[]>
registerOnIndexed(callback: () => void): void
unregisterOnIndexed(callback: () => void): void
```

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

### Register Tag Menu Item

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/api-reference.md

Register a callback to add custom items to the tag context menu. This example adds an item to handle aggregate tag collections.

```typescript
nn.menus.registerTagMenu(({ tag, addItem }) => {
  if (!nn.tagCollections.isCollection(tag)) {
    return;
  }

  addItem(item => {
    item.setTitle(`Handle ${nn.tagCollections.getLabel(tag)}`);
  });
});
```

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

### Pin Current File with Templater

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/api-reference.md

Use this Templater script to pin the currently active file within the Notebook Navigator. Ensure the 'notebook-navigator' plugin is installed and enabled.

```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');
}
%>
```

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

### Homepage Controller Methods

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/service-architecture.md

Methods for resolving the homepage target and handling its opening at startup or via command.

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

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

### Subscribe to Storage Ready Event (One-Time)

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/api-reference.md

Subscribes to the 'storage-ready' event, which fires once when the storage system is ready. This is useful for performing initial storage-backed operations. The listener is automatically unsubscribed after firing.

```typescript
// 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
});


```

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

### Get Current Navigation Item and Selection

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/api-reference.md

Query the current selection state using `getNavItem` for the active navigation item (folder, tag, or property) and `getCurrent` for the selected files and focus state.

```typescript
// Check what's selected
const navItem = nn.selection.getNavItem();
if (navItem.type === 'folder') {
  console.log('Folder selected:', navItem.folder.path);
} else if (navItem.type === 'tag') {
  console.log('Tag selected:', navItem.tag);
} else if (navItem.type === 'property') {
  console.log('Property selected:', navItem.property);
} else {
  console.log('Nothing selected in navigation pane');
}

// Get selected files
const { files, focused } = nn.selection.getCurrent();
```

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

### Notebook Navigator Storage Architecture Diagram

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/storage-architecture.md

Mermaid diagram illustrating the data flow and storage dependencies within Notebook Navigator.

```mermaid
graph TB
    Vault["Vault (files + metadata cache)"] --> Storage["StorageContext"]
    Storage --> CacheDB["IndexedDB cache (notebooknavigator/cache/{appId})"]
    Providers["Content providers"] --> CacheDB
    CacheDB --> Memory["Memory caches (MemoryFileCache + LRUs)"]
    Memory --> UI["React UI"]

    Settings["Settings (data.json)"] --> UI
    Local["vault-scoped localStorage"] --> UI
    Local --> CacheDB
    Icons["Icon assets DB (notebooknavigator/icons/{appId})"] --> UI
```

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

### Run Notebook Navigator API Tests

Source: https://github.com/johansan/notebook-navigator/blob/main/tests/README.md

Execute the Notebook Navigator API test suite. Options include verbose output, running specific test suites, or disabling automatic cleanup of temporary files.

```javascript
runTests(); // Run all tests with auto-cleanup
runTests({ verbose: true }); // Show detailed output
runTests({ only: 'metadata' }); // Run only specific test suite
runTests({ cleanup: false }); // Keep test files for debugging
```

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

### Run Build Script (PowerShell)

Source: https://github.com/johansan/notebook-navigator/blob/main/scripts/README.md

Executes the main build script for ensuring code quality before deployment using PowerShell.

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build.ps1
```

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

### Import Notebook Navigator API Types

Source: https://github.com/johansan/notebook-navigator/blob/main/src/api/public/README.md

Import the `NotebookNavigatorAPI` type into your plugin project to use with the Notebook Navigator API. Ensure the path is correct relative to your plugin's source files.

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

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

### Menus API

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/api-reference.md

Allows registration of callbacks to dynamically add items to various context menus within the Notebook Navigator.

```APIDOC
## Menus API

### Description
Register callbacks that add items to Notebook Navigator's file, folder, tag, and property context menus.

File and folder menu hooks are available in API version 1.2.0. Tag and property menu hooks are available in API version 2.0.0.

### Methods
- **registerFileMenu(callback)**: Add items to the file context menu. Returns `() => void`.
- **registerFolderMenu(callback)**: Add items to the folder context menu. Returns `() => void`.
- **registerTagMenu(callback)**: Add items to the tag context menu. Returns `() => void`.
- **registerPropertyMenu(callback)**: Add items to the property context menu. Returns `() => void`.

Callbacks run synchronously during menu construction. Add menu items synchronously and do async work in `onClick` handlers.
```

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

### Cache Rebuild Pipeline Diagram

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/metadata-pipeline.md

Illustrates the flow of actions and components involved in rebuilding the cache, from user interaction to storage and content provider updates.

```mermaid
graph TD
    User["User action"] --> Trigger["Settings button or command palette"]
    Trigger --> Plugin["NotebookNavigatorPlugin.rebuildCache"]
    Plugin --> Activate["activateView() and resolve navigator leaf"]
    Activate --> View["NotebookNavigatorView.rebuildCache"]
    View --> Component["NotebookNavigatorComponent.rebuildCache"]
    Component --> Storage["StorageContext.rebuildCache"]

    Storage --> DB["IndexedDBStorage and MemoryFileCache"]
    Storage --> Registry["ContentProviderRegistry"]
    Registry --> MP["MarkdownPipelineContentProvider"]
    Registry --> Tags["TagContentProvider"]
    Registry --> Meta["MetadataContentProvider"]
    Registry --> Thumbs["FeatureImageContentProvider"]

    MP --> DB
    Tags --> DB
    Meta --> DB
    Thumbs --> DB
```

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

### React Component Tree for Navigator Mounting

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/service-architecture.md

This JSX snippet illustrates the React component hierarchy used to mount the Notebook Navigator. It highlights the use of various context providers for managing settings, preferences, data, services, and UI state.

```jsx
<SettingsProvider plugin={plugin}>
  <UXPreferencesProvider plugin={plugin}>
    <RecentDataProvider plugin={plugin}>
      <ServicesProvider plugin={plugin}>
        <ShortcutsProvider>
          <StorageProvider app={plugin.app} api={plugin.api}>
            <ExpansionProvider>
              <SelectionProvider /* app/api/file rename wiring */>
                <UIStateProvider isMobile={isMobile}>
                  <NotebookNavigatorContainer />
                </UIStateProvider>
              </SelectionProvider>
            </ExpansionProvider>
          </StorageProvider>
        </ShortcutsProvider>
      </ServicesProvider>
    </RecentDataProvider>
  </UXPreferencesProvider>
</SettingsProvider>
```

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

### Notebook Navigator Data Flow Diagram

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/startup-process.md

Visual representation of the data flow during the Notebook Navigator startup and synchronization process, illustrating how files are processed, metadata is queued, and providers are updated.

```mermaid
graph TD
    Start["From Phase 3:<br/>Database & Providers ready"] --> A["processExistingCache (initial)"]

    A --> B["getIndexableFiles<br/>(markdown + supported non-markdown feature images)"]
    B --> C[calculateFileDiff]

    C --> D["removeFilesFromCache (toRemove)"]
    C --> E["recordFileChanges (toAdd/toUpdate)"]

    D --> F[rebuildTagTree + rebuildPropertyTree]
    E --> F

    F --> G[Mark storage ready<br/>notify API]

    G --> H["queueMetadataContentWhenReady<br/>(filters to files needing work)"]
    H --> I["metadataCache gating<br/>(getFileCache, resolved/changed)"]
    I --> J["Queue markdownPipeline/tags/metadata providers"]

    G --> K{Show feature images?}
    K -->|Yes| L[Queue fileThumbnails for supported non-markdown feature images]
    K -->|No| M[Skip non-markdown feature images]

    J --> N[Enter Phase 5]
    L --> N
    M --> N
```

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

### Workspace Coordinator Methods

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/service-architecture.md

Methods for managing workspace elements like navigator views and calendar placement, and for revealing files.

```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
```

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

### Make Notebook Navigator backgrounds transparent

Source: https://github.com/johansan/notebook-navigator/wiki/Custom-CSS

Apply this CSS to make various Notebook Navigator elements have a transparent background. Enable 'Translucent window' in Obsidian settings for this to take effect.

```css
body {
    .notebook-navigator,
    .nn-navigation-pane,
    .nn-navigation-pane .nn-pane-header,
    .nn-navigation-pane-scroller,
    .nn-list-pane,
    .nn-list-pane .nn-pane-header,
    .nn-list-pane-scroller,
    .nn-list-title-area,
    .nn-vault-title-area,
    .nn-shortcut-pinned,
    .nn-navigation-calendar-overlay,
    .nn-nav-banner-image {
        background-color: transparent !important;
    }
}

```

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

### Automate Plugin Release (Node.js)

Source: https://github.com/johansan/notebook-navigator/blob/main/scripts/README.md

Automates the release process for the Obsidian plugin, including version bumping and PR creation.

```javascript
node scripts/release.js
```

```javascript
node scripts/release.js patch
```

```javascript
node scripts/release.js minor
```

```javascript
node scripts/release.js major
```

```javascript
node scripts/release.js patch --dry-run
```

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

### Manage Folder and File Pins

Source: https://github.com/johansan/notebook-navigator/blob/main/docs/api-reference.md

Set metadata for folders, pin/unpin files, and check their pinned status. Defaults to all contexts if none specified.

```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`);
  }
}
```