---
title: Introduction & Mental Model
description: Philosophy, design principles, and mental model of VertiWiki, the single-file static documentation engine.
tags: [vertiwiki, introduction, philosophy, mental-model, zero-backend]
---

# Introduction to VertiWiki

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

VertiWiki is a modern, 100% static, single-file Markdown wiki and technical documentation engine. It provides the ergonomics of enterprise documentation portals without requiring complex build toolchains, server daemons, database backends, or deployment re-compilations.

---

## 💡 The Core Problem

Traditional documentation frameworks (such as Docusaurus, VitePress, or MkDocs) rely on ahead-of-time (AOT) static site generation:

1. **Heavy Build Pipelines**: Every markdown typo or documentation update requires running a Node.js or Python CI build, installing hundreds of megabytes of `node_modules`, and rebuilding static bundles.
2. **Operational Overhead**: Self-hosted alternatives (like Wiki.js or BookStack) require active Node/PHP servers, relational databases (PostgreSQL/MySQL), scheduled backups, and constant security patching.
3. **Deployment Friction**: Content creators cannot simply push raw Markdown files to an S3 bucket, Cloudflare Pages, or static web server and expect immediate rendering without a compilation trigger.

---

## 🧠 The VertiWiki Mental Model

VertiWiki turns the documentation paradigm inside-out:

```mermaid
graph LR
    subgraph Traditional SSG
        A[Markdown Source] --> B[CI Build Server Node/Python]
        B --> C[Compiled HTML/CSS Bundle]
        C --> D[CDN / Edge]
    end

    subgraph VertiWiki Paradigm
        E[Markdown Source] --> F[Static File Server]
        G[Single-File vertiwiki.html] --> F
        F --> H[Browser Runtime Execution]
    end
```

### 1. The Engine as a Single Asset
The entire user interface, parser extensions, syntax highlighter, search indexer, and theme engine are compiled into a standalone, single HTML distribution (`dist/vertiwiki.html` or `index.html`). 

### 2. Live Runtime Fetching & Rendering
When a user accesses a URL such as `https://my-wiki.internal/#/guides/getting-started.md`:
- The client engine intercepts the hash route.
- It executes an asynchronous HTTP `fetch` to retrieve the target Markdown document.
- The pipeline processes frontmatter, transforms wikilinks, compiles code fences with Prism.js, sanitizes HTML with DOMPurify, and mounts the document into the DOM.
- The search plugin builds an in-memory inverted index using MiniSearch for instant full-text filtering.

### 3. Zero Build on Content Modification
Editing documentation is as simple as updating the Markdown file. The next browser refresh immediately reflects the changes.

---

## 🎯 Key Design Principles

- **Zero-Backend Invariant**: No Node.js process, Python runtime, or database is needed in production. Standard HTTP file servers (Nginx, Caddy, Apache, GitHub Pages, Cloudflare Pages, Vercel) serve files directly.
- **Client-Side Security by Default**: Every rendered markdown fragment passes through a hardened DOMPurify profile before entering the DOM. Script injection and XSS vectors are eliminated.
- **Deep Deterministic Routing**: Deep links, subfolder deployments, and localized translations (`en`, `ro`, `fr`) are handled deterministically via client-side hash routes (`/#/guide.md` or `/#/ro/guide.md`).
- **AI Agent-Friendly (AEO)**: Native support for `llms.txt`, clean raw markdown content negotiation, and semantic markdown structures make VertiWiki directly navigable by autonomous AI coding assistants.
- **Design Token Decoupling**: Visual identity is managed through CSS custom properties and lightweight JSON theme presets (`themes/obsidian.json`, `themes/dracula.json`, etc.) without modifying core JavaScript.

---

## 🔗 Next Steps

- Jump straight into practical setup with the [5-minute Quickstart](quickstart.md).
- Explore distribution formats and package managers in [Installation & Setup](installation.md).
- Understand internal execution in the [System Architecture Guide](concepts/architecture.md).