Files

T

agentandClaude b5631986e6 Generator-Skeleton (Phase 1): static HTML + watchdog + HTTP server

Replaces obv-Fork. New architecture:
- Python watchdog observes /home/admin/my-karpathy-wiki/
- On .md change → regenerate single HTML + update index
- On startup → full regen + tree.json/graph.json/tags.json/backlinks.json
- HTTP server on 127.0.0.1:8765 + tailscale proxy
- 265 static HTML pages with full Markdown rendering
- WikiLink resolution: [[entity]] → <a href='/path/entity.html'>
- Frontmatter as styled card (type, status, updated, sources)
- TOC auto-generated via markdown.extensions.toc
- PWA manifest for native-feeling install
- data.js with all metadata for offline use

Touch-first design (CSS+JS for tree/graph/search) follows in Phase 2.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2026-07-19 17:16:02 +00:00

3.1 KiB

Raw Blame History

hermes-wiki-static

Static HTML wiki generator for Lukas Huber's karpathy-style Obsidian-vault.

What this is

A Python tool that watches /home/admin/my-karpathy-wiki/ for changes and regenerates static HTML files on disk. A simple HTTP server serves them on loopback port 8765; Tailscale exposes it to the tailnet.

Why this exists

We previously used DanielCheer/obsidian-web-viewer (forked as hermes-wiki-viewer). It had three blockers:

No touch support on iOS Safari — click handlers don't work reliably
3D-Graph auto-rotates — prevents node selection via tap
Fixed 260px Graph column — wastes horizontal space

This tool replaces obv with our own renderer:

Touch-first design — bottom-nav on mobile, hamburger-tree, FAB+modal graph
Static HTML — each page is a real URL, deep-linkable, PWA-installable
No auto-rotation — graph is static, click-to-rotate, click-to-navigate
Native-feeling — service worker, pull-to-refresh, swipe-back

Architecture

my-karpathy-wiki/*.md          (input)
        |
        v
[watchdog observer]             (auto-regen on .md change)
        |
        v
generator.py                    (Python: markdown + frontmatter)
        |
        v
~/.local/share/hermes-wiki/site/   (static HTML output)
        |
        v
python3 http.server (loopback:8765)
        |
        v
tailscale serve                 (https://openclaw.wholphin-musical.ts.net/)

Files

generator.py — daemon with watchdog + HTTP server
requirements.txt — markdown, pyyaml, watchdog, python-frontmatter

Run

# Install deps (one-time, system Python)
pip install --break-system-packages markdown pyyaml watchdog python-frontmatter

# Start daemon
python3 generator.py --start

# Status / Stop
python3 generator.py --status
python3 generator.py --stop

# One-shot regen (no watcher, no HTTP server)
python3 generator.py --once

Output structure

site/
├── index.html              (redirect to first note)
├── concepts/<slug>.html    (one file per .md)
├── entities/<slug>.html
├── ...
└── __/
    ├── style.css
    ├── app.js
    ├── data.js             (all metadata inlined for offline)
    ├── tree.json
    ├── graph.json
    ├── tags.json
    ├── backlinks.json
    └── manifest.json       (PWA)

WikiLink syntax

[[entity-name]] or [[entity-name|display text]] resolves to a real <a class="wikilink" href="/path/to/entity.html"> if the target exists, otherwise <a class="wikilink-missing"> (greyed out).

Frontmatter

---
title: My Note
type: concept
status: stable
updated: 2026-07-15
sources:
  - https://example.com
tags:
  - hermes
  - architecture
---

Known limitations (Phase 1)

CSS is placeholder — touch design comes in Phase 2
JS is placeholder — search/tree/graph render comes in Phase 2
Bottom-Nav template is there but not styled
5 YAML files in the wiki have malformed frontmatter (parser warnings)
Graph only shows 27 edges — some WikiLinks not resolving due to those YAML issues

3.1 KiB Raw Blame History