---
title: Plugins & Extensions Subsystem
description: Architecture of VertiWiki's plugin system and built-in extensions: MiniSearch, Mermaid, KaTeX, Callouts, and Lightbox.
tags: [vertiwiki, plugins, extensions, minisearch, mermaid, katex, callouts]
---

# Plugins & Extensions Subsystem

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

VertiWiki's capabilities are extended via a modular plugin architecture registered on the core `Pipeline`. Each plugin can tap into `beforeParse`, `afterParse`, and `afterRender` execution phases.

---

## 🔌 Built-In Plugin Catalog

| Plugin | Lifecycle Hook | Description |
| :--- | :--- | :--- |
| **Search (`search.ts`)** | `afterRender` | In-memory full-text search indexing powered by MiniSearch. |
| **Mermaid (`mermaid.ts`)** | `afterRender` | Renders flowcharts, sequence diagrams, and C4 models. |
| **Math (`math.ts`)** | `afterRender` | Formats LaTeX formulas via KaTeX. |
| **Callouts (`callouts.ts`)** | `beforeParse` | Transforms `> [!NOTE]` alerts into colored callout boxes. |
| **Tabs (`tabs.ts`)** | `beforeParse` | Implements synchronized multi-code tab switchers (`::: tabs`). |
| **Details (`details.ts`)** | `beforeParse` | Renders expandable accordion sections (`::: details`). |
| **Lightbox (`lightbox.ts`)** | `afterRender` | Fullscreen modal overlay for images and diagrams. |
| **AEO (`aeo.ts`)** | `afterRender` | Injects dynamic Schema.org JSON-LD and AI discovery headers. |
| **Analytics (`analytics.ts`)** | `afterRender` | Multi-provider privacy-focused pageview telemetry. |

---

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

Instead of relying on external search backends or bloated pre-compiled JSON blobs:
1. **Background Indexing**: As documents are loaded, `SearchEngine` feeds their plain-text content into an in-memory `MiniSearch` instance.
2. **Locale Scoping**: Queries are automatically filtered to match the reader's active locale (`en`, `ro`, `fr`), preventing foreign-language results.
3. **Fuzzy Matching & Snippets**: Supports typo tolerance (`fuzzy: 0.2`) and extracts dynamic text snippets around matching search tokens.

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

---

## 📊 2. Diagramming & LaTeX Math

### Mermaid Engine (`src/plugins/mermaid.ts`)
- Automatically initializes Mermaid with dark/light themes matched to `--verti-bg-base`.
- Sanitizes rendered SVGs using DOMPurify while explicitly preserving `<foreignObject>` and `<style>` elements to maintain diagram node labels without compromising security.

### KaTeX Formula Rendering (`src/plugins/math.ts`)
- Evaluates inline `\( ... \)` or `$...$` (with strict whitespace boundaries to prevent accidental currency symbol parsing) and display blocks `\[ ... \]` or `$$...$$`.
- Leverages pruned WOFF2 fonts for ultra-compact bundle size.
- Skips code-highlighting interference on math blocks.

### Image Lightbox (`src/plugins/lightbox.ts`)
- Provides modal zoom overlays for documentation diagrams and screenshots.
- Intelligently excludes images wrapped in hyperlinks (`img:not(a img)`) to preserve clickable banners and status badges.

---

## 📑 3. Interactive Content Components

### Callouts & GitHub Alerts (`src/plugins/callouts.ts`)
Transforms standard blockquote syntax into distinct visual notification banners:
```markdown
> [!NOTE]
> Informational callout.

> [!TIP]
> Optimization or best practice recommendation.

> [!IMPORTANT]
> Critical step or prerequisite.

> [!WARNING]
> Potential problem or pitfall.

> [!CAUTION]
> High-risk action that could cause data loss.
```

### Synchronized Content Tabs (`src/plugins/tabs.ts`)
Allows readers to switch between programming languages or operating systems across the entire page with persistent local state:
````markdown
::: tabs
== cURL
```bash
curl -X GET https://api.example.com/health
```
== Python
```python
import requests
requests.get("https://api.example.com/health")
```
:::
````

---

## 🤖 4. Answer Engine Optimization (AEO) (`src/plugins/aeo.ts`)

Prepares documentation for autonomous AI coding agents (Claude Code, Antigravity, OpenCode, Cursor):
- **Agent Discovery Tags**: Injects `<link rel="help" href="llms.txt">` into `<head>`.
- **Schema.org Graphs**: Builds dynamic `TechArticle` and `BreadcrumbList` microdata with dynamic active locale detection (`inLanguage`).
- **Copy for AI**: Adds an action button to copy the active markdown document directly into clipboard for LLM prompting.

---

## 🔗 Next Steps

- Review the core system design in [System Architecture](architecture.md).
- Explore runtime configuration parameters in [Configuration Overview](../configuration/overview.md).
- Inspect typed hook definitions in the [API Catalog](../reference/api.md).