agentandClaude
b5631986e6
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>
118 lines
3.1 KiB
Markdown
118 lines
3.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```yaml
|
|
---
|
|
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
|