Org Web Adapter

A lightweight local web app for browsing and editing Org files.

The app is implemented as a single Python server (main.py) plus one HTML template (templates/index.html) and one stylesheet (static/style.css). It scans a notes directory for .org files and renders a 3-pane UI.

⚠️ There is no authentication or encryption, only run this service on trusted networks. ⚠️

Screenshots

Desktop

Mobile

Instructions

1. Symlink your notes directory to notes.
2. Edit the bind address and port in config.yaml if desired.
3. python3 main.py.

How's it work?

1. main.py starts an HTTP server.
2. On each page request (GET /), it rescans the notes directory for .org files.
3. It resolves links/backlinks and builds HTML fragments.
4. It injects those fragments into templates/index.html placeholders:
   • {{NAV_ITEMS}}
   • {{MAIN_CONTENT}}
   • {{BACKLINKS}}
5. Browser JS in templates/index.html handles client-side interactions (search, shuffle, sorting, jump-to-current, theme toggle).

Server-side components (main.py)

• File discovery and parsing:
  • scan_org_files(...) recursively finds .org files.
  • Extracts title from #+TITLE: and ID from :ID:.
• Org link/backlink handling:
  • resolve_link_target(...) supports file:... and id:... links.
  • find_backlinks(...) computes notes linking to the selected note.
  • build_backlink_counts(...) computes backlink totals for sorting.
• Rendering:
  • render_org_to_html(...) converts headings (*, **, ...) and paragraphs to simple HTML.
  • render_line_with_links(...) converts org links in text to clickable app links where resolvable.
  • truncate_label(...) caps sidebar labels to 32 chars with ....
• Editing:
  • POST /edit updates a selected .org file and redirects back with status flags.
• Static files:
  • serve_static(...) serves files under static/ with path traversal protection.

Frontend components

• templates/index.html:
  • Base layout markup.
  • Sidebar controls.
  • Small JS controller for filtering/sorting/shuffling nav links.
  • MathJax initialization for inline $...$ rendering.
• static/style.css:
  • 3-column desktop grid and stacked mobile layout.
  • Independent scroll regions for note list and backlinks.
  • Mobile note-list cap (about 5 notes visible before scrolling).

Configuration

Startup config is read from config.yaml by default.

• bind_addr: host/IP to bind
• bind_port: TCP port (must be 1..65535)

Notes:

• If config.yaml is missing, defaults are 127.0.0.1:8000.
• CLI flags --host and --port override config values.
• You can choose a different config file with --config /path/to/config.yaml.

Useful run commands

python3 main.py --dir notes
python3 main.py --host 127.0.0.1 --port 9000
python3 main.py --config ./config.yaml
python3 main.py --no-browser

Features

Note browsing

• Recursive .org file discovery.
• Sidebar note list with active-note highlighting.
• Title/path search filter.

Sidebar ordering controls

• Shuffle notes.
• Sort by backlink count (descending).
• Sort by created date (ascending).
  • Notes without timestamps are treated as older than notes with timestamps.
• Jump to current note button.

Backlinks

• Right sidebar lists notes linking to the current note.
• Supports both file: and id: link resolution.

Editing

• Toggle Preview/Edit for the selected note.
• Save changes from browser to disk.
• Inline status messages for save success/errors.

Math rendering

• Inline math rendering via MathJax using $...$ delimiters.

UI behavior

• Light/dark theme toggle (persisted in localStorage).
• Desktop: independent scrollable sidebars.
• Mobile: notes list capped with its own scroll area.
• Sidebar text truncation with ellipsis and tooltip for full text.

Project layout

• main.py: server, parsing, rendering, routing.
• templates/index.html: page template + UI behavior JS.
• static/style.css: styling and responsive layout.
• config.yaml: bind config.
• notes/: notes directory (can be a symlink).
• old_notes/: alternate local notes snapshot.

Limitations

• Not a full Org parser; rendering is intentionally simple.
• Notes are rescanned on each request (simple and fresh, but not optimized for huge note sets).
• Math rendering depends on loading MathJax from CDN.