159 lines
4.6 KiB
Markdown
159 lines
4.6 KiB
Markdown
# Micronomicon
|
|
|
|
A self-hosted web editor for writing Markdown and publishing `.mu` pages to a NomadNet node.
|
|
|
|
Write in Markdown → preview as Micron → publish directly to `~/.nomadnetwork/storage/pages/`.
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
- Docker + Docker Compose
|
|
- Python 3.13+ (for local backend development only)
|
|
- Node 20+ (for local frontend development only)
|
|
- A running NomadNet container named `nomadnet` (for the restart button)
|
|
|
|
---
|
|
|
|
## Quick Start (Docker)
|
|
|
|
```bash
|
|
# 1. Build the frontend
|
|
cd frontend
|
|
npm install
|
|
npm run build
|
|
cd ..
|
|
|
|
# 2. Create source directories
|
|
mkdir -p ~/.nomadnetwork/storage/pages ~/.micron-editor/sources
|
|
|
|
# 3. Start the stack
|
|
docker compose up --build
|
|
```
|
|
|
|
App is available at `http://localhost:8080`.
|
|
|
|
### Tailscale HTTPS
|
|
|
|
```bash
|
|
tailscale serve --bg https+insecure://localhost:8080
|
|
```
|
|
|
|
---
|
|
|
|
## Local Development
|
|
|
|
Run backend and frontend separately with hot reload.
|
|
|
|
**Backend**
|
|
|
|
```bash
|
|
cd backend
|
|
python -m venv .venv && source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
|
|
PAGES_DIR=~/.nomadnetwork/storage/pages \
|
|
SOURCES_DIR=~/.micron-editor/sources \
|
|
uvicorn main:app --reload --port 8080
|
|
```
|
|
|
|
**Frontend**
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev # proxies /api → localhost:8080
|
|
```
|
|
|
|
Open `http://localhost:5173`.
|
|
|
|
---
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
|----------------------|------------------|--------------------------------------|
|
|
| `PAGES_DIR` | `/data/pages` | NomadNet pages directory |
|
|
| `SOURCES_DIR` | `/data/sources` | Markdown source files directory |
|
|
| `NOMADNET_CONTAINER` | `nomadnet` | Docker container name to restart |
|
|
|
|
---
|
|
|
|
## API Reference
|
|
|
|
| Method | Path | Description |
|
|
|----------|---------------------|-----------------------------------------------|
|
|
| `GET` | `/api/health` | Health check |
|
|
| `POST` | `/api/convert` | Convert `{ markdown }` → `{ micron }` |
|
|
| `GET` | `/api/pages` | List all pages with metadata |
|
|
| `GET` | `/api/pages/{name}` | Read page (markdown source + micron output) |
|
|
| `POST` | `/api/pages/{name}` | Save `{ markdown, publish }` — draft or live |
|
|
| `DELETE` | `/api/pages/{name}` | Delete source and/or `.mu` file |
|
|
| `GET` | `/api/graph` | Graph nodes + edges from parsed link sources |
|
|
| `POST` | `/api/restart` | Restart NomadNet Docker container |
|
|
|
|
---
|
|
|
|
## Directory Layout
|
|
|
|
```
|
|
micronomicon/
|
|
Dockerfile
|
|
compose.yml
|
|
backend/
|
|
main.py ← FastAPI app + static file serving
|
|
converter.py ← md2txt wrapper (POST /api/convert)
|
|
pages.py ← file management (CRUD /api/pages)
|
|
graph.py ← link parser (GET /api/graph)
|
|
docker_utils.py ← container restart (POST /api/restart)
|
|
requirements.txt
|
|
frontend/
|
|
src/
|
|
App.tsx
|
|
routes/ ← DashboardView, EditorView, GraphView
|
|
components/ ← dashboard/, editor/, shared/, ui/ (shadcn)
|
|
stores/ ← editorStore, pagesStore (Zustand)
|
|
hooks/ ← useConversion, useGraph, useUnsavedGuard
|
|
lib/ ← utils (cn)
|
|
|
|
~/.nomadnetwork/storage/pages/ ← published .mu files (NomadNet serves these)
|
|
~/.micron-editor/sources/ ← markdown sources (managed by this app)
|
|
```
|
|
|
|
---
|
|
|
|
## Page Lifecycle
|
|
|
|
```
|
|
New Page → /editor/new → Save Draft → .md saved to sources/
|
|
→ Publish → .md saved + .mu written to pages/
|
|
```
|
|
|
|
- **Draft** — `.md` exists, no `.mu`. Not visible on NomadNet.
|
|
- **Published** — both `.md` and `.mu` exist.
|
|
- **Orphan** — `.mu` exists but no `.md` source (e.g. pages created outside this tool).
|
|
|
|
---
|
|
|
|
## Tech Stack
|
|
|
|
| Layer | Technology |
|
|
|-----------|-----------------------------------------|
|
|
| Backend | Python 3.13 + FastAPI + uvicorn |
|
|
| Converter | md2txt (micron renderer) |
|
|
| Frontend | React 19 + Vite + TypeScript |
|
|
| UI | shadcn/ui + Tailwind CSS v4 |
|
|
| Editor | CodeMirror 6 |
|
|
| Graph | React Flow + dagre |
|
|
| State | Zustand |
|
|
| Container | Docker + Compose |
|
|
|
|
---
|
|
|
|
## Known Limitations (Phase 1)
|
|
|
|
- Micron preview is plain text — full terminal rendering comes in a later phase (micron-parser-js iframe)
|
|
- `[[` link autocomplete not yet implemented (Phase 2)
|
|
- Graph view is read-only; click a node to open it in the editor
|
|
- No metrics (Phase 4)
|