llm-wikipedia

llm-wikipedia is a read-only web server that renders an llm-wiki markdown vault with familiar Wikipedia-style navigation and article chrome.

It is intentionally narrow:

• no authentication or editing UI; put it behind SSO or a reverse proxy
• no copied wiki content in the image or repository
• live reads from the mounted wiki directory, so changed markdown appears on the next request without restarting the server
• Docker-first deployment with a read-only wiki mount

Features

• Wikipedia-like layout: collapsible mobile navigation, left desktop navigation, article tabs, serif headings, infobox metadata, table of contents, red links, backlinks, and categories/tags.
• Recursive markdown rendering for index.md, entities/, concepts/, comparisons/, queries/, raw/, or any other markdown path in the vault.
• Obsidian/llm-wiki [[wikilinks]], including [[path/page|label]] and basename aliases when unambiguous.
• Ranked search across page titles, slugs, paths, namespaces, page types, tags, excerpts, sources, and full article bodies; multi-term queries require all terms so results stay focused.
• Read-only filesystem behavior; symlinks escaping the mounted wiki root are ignored.
• Health endpoint at GET /api/health for validating the mounted wiki root and page count.

Runtime contract

The container expects the wiki at /data/wiki by default. Override with LLM_WIKI_ROOT if needed.

docker run --rm \
  -p 3000:3000 \
  -e LLM_WIKI_ROOT=/data/wiki \
  -v /absolute/path/to/llm-wiki:/data/wiki:ro \
  code.mehalter.com/clawlter/llm-wikipedia:dev

Open http://localhost:3000.

The image's built-in Docker healthcheck uses /api/health. A 503 JSON response means the app is running but LLM_WIKI_ROOT does not point at a readable wiki directory inside the container. Malformed markdown frontmatter is reported in the indexErrors array without failing health; those pages are skipped until their frontmatter is corrected.

Docker Compose

services:
  llm-wikipedia:
    image: code.mehalter.com/clawlter/llm-wikipedia:dev
    ports:
      - "3000:3000"
    environment:
      LLM_WIKI_ROOT: /data/wiki
    volumes:
      - /absolute/path/to/llm-wiki:/data/wiki:ro
    read_only: true
    tmpfs:
      - /tmp

Container publishing

Forgejo Actions builds the Docker image on pull requests and publishes package tags to the Forgejo container registry for deployable refs.

Publishing rules:

• pushes to main publish code.mehalter.com/clawlter/llm-wikipedia:dev
• published releases tagged like v1.2.3 publish:
  • code.mehalter.com/clawlter/llm-wikipedia:v1.2.3
  • code.mehalter.com/clawlter/llm-wikipedia:v1
  • code.mehalter.com/clawlter/llm-wikipedia:latest
• pull requests build the image without pushing it

The publish workflow expects the shared Forgejo Actions secret PACKAGE_TOKEN with package write permission.

Local development

npm ci
LLM_WIKI_ROOT=/absolute/path/to/llm-wiki npm run dev

Quality checks

npm run lint
npm run typecheck
npm test
npm run build

Notes

The server currently reparses the mounted markdown on each request. That keeps live-update semantics simple and correct for typical llm-wiki sizes; if the wiki grows into tens of thousands of pages, the next optimization should be an mtime-aware in-process index cache rather than changing the runtime contract.