---
title: TypeScript API Reference & Specifications
description: Exhaustive typed API catalog, method signatures, parameter tables, and return types for VertiWiki's core engine.
tags: [vertiwiki, api, reference, typescript, types, interfaces]
---

# TypeScript API Reference

> For the complete documentation index and agent navigation, see [llms.txt](/llms.txt).

This document provides 100% AST-grounded specifications for all public classes, functions, and interfaces in the VertiWiki core engine.

---

## 🧭 Router Subsystem (`src/core/router.ts`)

### `normalizePath(path: string): string`
Normalizes file paths by converting backslashes to forward slashes, stripping redundant slashes, and resolving `.` and `..` segments.

```typescript
export function normalizePath(path: string): string;
```

#### Parameters:
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `path` | `string` | Yes | Raw file or URL path to normalize. |

#### Returns:
`string` — Normalized clean path without leading slashes or `.` prefixes.

---

### `getBaseDirectory(): string`
Determines the canonical base directory for the current runtime instance, handling subfolder deployments and missing trailing slashes.

```typescript
export function getBaseDirectory(): string;
```

#### Returns:
`string` — Base path ending with a trailing slash (e.g. `'/'` or `'/docs/'`).

---

### `resolveResourceUrl(relativePath: string): string`
Resolves relative asset and markdown resource paths against the detected base directory.

```typescript
export function resolveResourceUrl(relativePath: string): string;
```

---

## 🔌 Pipeline Subsystem (`src/core/pipeline.ts`)

### `class Pipeline`
The central execution bus coordinating plugin lifecycle middleware.

```typescript
export class Pipeline {
  public registerPlugin(plugin: VertiWikiPlugin): void;
  public runBeforeParse(markdown: string, context: PluginContext): Promise<string>;
  public runAfterParse(html: string, context: PluginContext): Promise<string>;
  public runAfterRender(context: PluginContext): Promise<void>;
}
```

#### Plugin Lifecycle Methods:
- **`registerPlugin(plugin)`**: Appends a plugin to the active execution queue.
- **`runBeforeParse(markdown, context)`**: Asynchronously executes all registered `beforeParse` hooks sequentially. Returns the transformed Markdown string.
- **`runAfterParse(html, context)`**: Asynchronously executes all `afterParse` hooks sequentially. Returns the transformed HTML string.
- **`runAfterRender(context)`**: Executes all `afterRender` post-mount hooks.

#### Core Context Interfaces:
```typescript
export interface PluginContext {
  filePath: string;
  config: VertiWikiConfig;
  container: HTMLElement;
  rawMarkdown?: string;
}

export interface RenderContext {
  currentPath: string;
  rawMarkdown: string;
  htmlContent: string;
  config: VertiWikiConfig;
}
```

---

## 📝 Markdown Parser Subsystem (`src/core/parser.ts`)

### `parseFrontmatter(markdown: string)`
Extracts YAML frontmatter key-value pairs from the start of a Markdown string.

```typescript
export function parseFrontmatter(markdown: string): { 
  frontmatter: Record<string, string>; 
  body: string 
};
```

#### Returns:
An object containing:
- `frontmatter`: Dictionary of parsed key-value string pairs.
- `body`: Markdown content with the frontmatter header stripped.

---

### `cleanTitle(raw: string): string`
Sanitizes document titles for browser tabs and TOC headers by stripping HTML tags, markdown badge directives (`:badge[...]`), formatting tokens, and collapsing excess whitespace.

```typescript
export function cleanTitle(raw: string): string;
```

---

### `slugify(text: string): string`
Generates clean, collision-free URL anchor slugs from heading text strings.

```typescript
export function slugify(text: string): string;
```

---

## 🎨 Theme Manager (`src/ui/theme.ts`)

### `class ThemeManager`
Coordinates theme presets, CSS custom properties, and dark/light mode switching.

```typescript
export class ThemeManager {
  constructor(
    defaultMode?: 'auto' | 'light' | 'dark',
    defaultPreset?: string,
    customThemes?: (ThemePreset | CustomThemeDefinition)[],
    enableThemeChooser?: boolean
  );
  public setMode(mode: 'auto' | 'light' | 'dark'): void;
  public setPreset(presetId: string): void;
  public registerTheme(theme: ThemePreset | CustomThemeDefinition): ThemePreset;
  public getThemes(): ThemePreset[];
}
```

---

## 🔍 Search Engine (`src/plugins/search.ts`)

### `class SearchEngine`
Wraps MiniSearch for client-side full-text searching and preview snippet extraction.

```typescript
export class SearchEngine {
  public addDocument(doc: SearchDocument): void;
  public search(query: string, options?: { locale?: string }): SearchResultItem[];
  public clear(): void;
}
```

#### Parameters for `search`:
| Parameter | Type | Description |
| :--- | :--- | :--- |
| `query` | `string` | Search terms or phrases. |
| `options.locale` | `string` (optional) | Limits search scope strictly to the active language (`en`, `ro`, `fr`). |

#### Returns:
`SearchResultItem[]` — Array of matching documents scored by relevance, containing text snippets with `<mark>` highlight tags.