WikiNest

Overview

WikiNest is a git-native wiki built for small engineering teams who want collaborative documentation without infrastructure overhead. The core idea is deliberately minimal: a wiki is nothing more than a collection of markdown files in a Git repository. WikiNest acts as a thin browser-based editing layer over that repository — every page you write, every edit you save becomes a Git commit automatically. No server to spin up. No database to provision. No npm install, no build pipeline, no Docker container. The entire application ships as a single `index.html` and one `style.css` file. Setup takes two minutes: fork the repository, enable GitHub Pages or GitLab Pages, done. Your team gets a collaborative wiki backed by version control from day one.

Problem

Documentation tooling for small teams has a frustrating cost structure. The established options each come with significant baggage: - Confluence — per-user SaaS pricing that punishes growth, opaque versioning, vendor lock-in - Wiki.js — requires Node.js server, PostgreSQL or MongoDB, ongoing infrastructure maintenance - Docusaurus / MkDocs — need a Node.js or Python build pipeline, local environment setup, CI for deployment - Notion — closed platform, no real version history, export is a one-way door For a team of 2–8 engineers who just want to write docs and track decisions, none of these is proportionate to the actual need. The underlying insight: if you already use Git, you already have all the infrastructure you need for a wiki. The files just need a decent editor in front of them.

Solution

WikiNest strips the problem down to its minimum viable form. The application talks directly to the GitHub or GitLab API from the browser. There is no backend — authentication happens via a personal access token stored in localStorage. Reading and writing pages means making API calls to read file contents and commit changes. This architecture has a clean consequence: every edit is automatically versioned. Roll back any page to any prior state. See exactly who changed what and when. The wiki's history is the repository's commit history — no separate audit log, no proprietary revision system. The tradeoff is intentional: WikiNest optimises for zero infrastructure cost and zero maintenance burden over rich real-time collaboration features.

What I built

• Split-view markdown editor — raw markdown on the left, live rendered preview on the right
• Auto-versioning — every save generates a Git commit with a descriptive message
• Offline drafts — autosave to localStorage every 500ms, changes survive page reloads
• Drag-and-drop image uploads — images are committed directly into the repository as binary blobs
• Wiki-style linking — "[[Page Name]]" syntax with autocomplete across existing pages
• Full-text search — index generated by CI on every push, searched client-side
• Page history — last 20 commits per page with diff preview
• Folder management — create and rename folders with custom naming
• GitHub Pages and GitLab Pages deployment — no separate hosting required
• Zero external runtime dependencies — no npm, no bundler, no CDN scripts

Architecture

The application is structurally flat: one HTML file, one CSS file, vanilla JavaScript with no framework. All state lives in two places: - The Git repository — canonical, versioned source of truth for all page content - localStorage — temporary session state (auth token, offline drafts, UI preferences) Read path: The browser calls the GitHub/GitLab REST API to fetch file contents. Markdown is parsed and rendered client-side. No server touch. Write path: On save, the application computes the base64 encoding of the updated file and calls the API's update-file endpoint with the current file SHA. The API atomically commits the new version. Conflict detection is handled by the SHA — if the file changed since last read, the commit fails with a clear error. Search path: A GitHub Actions workflow runs on every push and generates a flat JSON index of all page content. The browser fetches this index once per session and runs full-text search locally. This separation means the editor has no operational cost beyond the API rate limits of a standard GitHub free account — well within the range for any team writing documentation.

System Model

WikiNest is intentionally designed around an inversion of the typical wiki architecture. Traditional documentation systems introduce a dedicated backend layer: application server, database, authentication service, search infrastructure, deployment pipeline. WikiNest removes that entire layer and treats existing Git infrastructure as the platform itself. The resulting system model looks like this: - Git repository → canonical database - GitHub/GitLab API → persistence and write layer - GitHub Pages / GitLab Pages → hosting runtime - CI pipelines → asynchronous indexing system - Browser → application runtime - localStorage → ephemeral session cache The browser effectively operates as a distributed client for a Git-backed document store. This changes the operational model completely. There is no server lifecycle, no database maintenance, no migrations, no runtime orchestration and no infrastructure ownership beyond the repository itself. The repository is the system.

Why No Backend

The absence of a backend is not a missing feature — it is the core architectural constraint the entire project is built around. The goal was to answer a specific question: "How much collaborative documentation infrastructure can be replaced with Git itself?" Git already provides: - Version history - Concurrency model - Rollback - Audit trail - Access control - Replication - Hosting - Review workflows - Deployment pipelines Most wiki platforms rebuild these concepts inside their own application stack. WikiNest instead treats Git as the native storage and collaboration layer from the beginning. This has significant consequences: - No infrastructure provisioning - No operational maintenance - No deployment complexity - No proprietary data layer - No vendor lock-in - No synchronization system between the wiki and Git The trade-off is equally intentional: the architecture prioritises transparency, portability and operational simplicity over enterprise collaboration features.

Provider Abstraction

One of the more important engineering goals was avoiding tight coupling to a single Git platform. WikiNest supports both GitHub and GitLab through a normalized provider layer that abstracts differences between their REST APIs. Internally, operations like: - file reads - file writes - deletes - commit history - pipeline status - raw file access are converted into provider-agnostic operations. GitHub and GitLab expose different API shapes, authentication mechanisms and pipeline systems. WikiNest normalizes these into a shared internal model so the rest of the application can operate independently of the provider. For example: - GitHub uses `PUT /contents/{path}` while GitLab separates create/update into `POST` and `PUT` - GitHub Actions and GitLab Pipelines return different deployment payloads - GitLab uses `last_commit_id` where GitHub exposes blob SHAs directly The application hides these differences behind a thin API layer while preserving the same UX and deployment flow.

Consistency Model

WikiNest intentionally operates as an eventually consistent system. Raw CDN endpoints on both GitHub and GitLab cache markdown files aggressively, typically for 30–60 seconds. After a save, the latest repository state may not be immediately visible through the CDN even though the commit already exists. Instead of fighting this behavior, the application is designed around it. After a save: - The editor immediately renders the local version of the document - The sidebar updates optimistically without waiting for CI - A deploy watcher tracks the latest CI run - `tree.json` and `search.json` reload only after deployment succeeds This creates a workflow that feels responsive while still remaining fully static and backendless. Conflict detection is handled structurally through Git SHAs. Every write operation includes the currently known file SHA. If another edit lands first, the provider rejects the write automatically. In practice, Git itself becomes the concurrency control system.

Search Architecture

Full-text search is implemented without any dedicated search infrastructure. On every push, CI walks the `docs/` directory and generates two static artifacts: - `tree.json` → page metadata, hierarchy, excerpts and timestamps - `search.json` → flat full-text index of raw markdown content The frontend fetches `search.json` lazily on first search open instead of during initial page load. This keeps startup lightweight even for larger documentation repositories. Search itself is entirely client-side. This architecture deliberately shifts indexing cost into CI instead of runtime. The browser receives a precomputed static index and performs instant in-memory search with zero backend dependency. The trade-off is that search indexing is asynchronous and trails writes by roughly one deployment cycle.

Security Model

WikiNest uses a deliberately lightweight security model designed for internal engineering documentation rather than enterprise zero-trust environments. Editing requires three separate conditions: - Repository write access - Valid Personal Access Token - Local edit password The Personal Access Token is never stored server-side because there is no server. Instead: - The token is stored in localStorage - If an edit password is configured, the token is XOR-obfuscated with the password before storage - The token is decrypted only after the correct password is entered - The decrypted token lives only in runtime memory for the session duration This is intentionally described as obfuscation rather than strong cryptographic protection. The goal is not enterprise-grade secret management. The goal is avoiding accidental plaintext exposure while preserving the zero-backend architecture. The project also hardens several browser-side attack surfaces: - User-controlled strings are escaped before HTML interpolation - Dynamic UI elements use DOM APIs instead of inline HTML construction - Path validation prevents traversal sequences in file operations - External CDN scripts use Subresource Integrity hashes The main acknowledged architectural limitation is markdown rendering itself. User-authored markdown is rendered client-side through `marked.js`, meaning repository compromise could theoretically introduce malicious content. For the target use-case — small engineering teams operating inside trusted repositories — this trade-off was considered acceptable.

Operational Philosophy

WikiNest is intentionally optimized around operational minimalism. Modern documentation systems often accumulate infrastructure gradually: database → auth → object storage → deployment pipeline → search service → background jobs → backups → monitoring Eventually the documentation platform itself becomes another production service. WikiNest deliberately moves in the opposite direction. The entire system is: - one HTML file - one CSS file - one repository - static hosting - provider APIs - CI-generated metadata No package manager. No runtime dependencies beyond one CDN markdown parser. No server process. No containers. The result is a tool that is unusually transparent operationally: - Every page is a normal markdown file - Every edit is a normal Git commit - Every deployment is a normal Pages deployment - Every failure mode is inspectable through standard Git tooling A new engineer can realistically understand the entire system in a single afternoon.

Engineering Constraints

Several technical constraints shaped the project heavily: - No framework runtime - No build step - No server-side execution - No external database - No bundler - No dependency graph These constraints forced the architecture toward explicit simplicity. Features that are often hidden behind framework abstractions had to be implemented directly: - optimistic UI updates - debounced rendering - split-view editor synchronization - provider API normalization - CI deployment tracking - markdown parsing pipeline - wiki-link autocomplete - tree rendering from flat structures - offline draft persistence This constraint-driven approach kept the codebase extremely small while still supporting collaborative editing, search, version history and deployment feedback. The final application remains close to ~1000 lines of vanilla HTML, CSS and JavaScript.

Engineering Decisions

• No framework — vanilla JS keeps the bundle size at zero and eliminates dependency drift entirely
• API-first writes — using Git provider APIs means versioning is structural, not bolted on
• localStorage for auth — avoids any server-side session management; the token never leaves the browser
• CI-generated search index — avoids client-side indexing on load while keeping search instant
• Single file distribution — the entire app can be forked and served from any static host in minutes
• localStorage autosave — 500ms interval prevents data loss without requiring a backend persistence layer

Trade-offs

• No real-time collaboration — concurrent edits require manual conflict resolution via Git
• Personal access token auth — not suitable for large organizations requiring SSO or role-based access
• Search index has ~1 commit lag — content is searchable after the next CI run, not immediately on save
• GitHub/GitLab API rate limits apply — unlikely to be an issue for small teams, but worth noting
• No rich text editor — markdown only, intentional trade-off for simplicity and portability

Result

• Full wiki system with zero backend infrastructure
• Every edit is a traceable, reversible Git commit
• Setup time: under 2 minutes from fork to live wiki
• Works on any static hosting provider that supports GitHub/GitLab Pages
• [object Object]
• MIT licensed, fork-ready template repository

Takeaways

WikiNest is a study in constraint as design tool. By refusing to add a server, a database, or a build step, every other decision followed naturally: use the Git provider API directly, store state in localStorage, generate the search index in CI, distribute as a single file. The result is a tool that is genuinely usable from day one, costs nothing to run, and is fully transparent — you can read every line of the application in an afternoon. For small engineering teams, that transparency and zero operational overhead is often more valuable than the feature richness of heavier alternatives. It also demonstrates a pattern worth generalising: many tools that assume they need a backend actually don't, if you're willing to accept the right tradeoffs and build against the APIs your users are already using.