# 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