Org Web Adapter: A Lightweight Local Web App for Org Mode Notes

Org Web Adapter is a lightweight local web application designed to provide a simple and intuitive way to browse and edit Org Mode files. Built as a single Python server with an HTML template and stylesheet, it offers a 3-pane UI for managing your notes. This tool is perfect for those who prefer a straightforward interface for their Org files without the need for complex setups.

Key Features

Note Browsing

• Recursive .org file discovery: Scans your notes directory for .org files and renders them in a user-friendly interface.
• Sidebar note list with active-note highlighting: Easily navigate through your notes with a clear visual indicator of the currently selected note.
• Title/path search filter: Quickly find specific notes using the search functionality.
• Sidebar ordering controls: Organize your notes by shuffling, sorting by backlink count, or sorting by creation date.

Backlinks

• Right sidebar lists notes linking to the current note: View all notes that reference the currently selected note, supporting both file: and id: link resolution.

Editing

• Toggle Preview/Edit for the selected note: Seamlessly switch between viewing and editing modes.
• Save changes from browser to disk: Make edits directly in the browser and save them to your Org files.
• Inline status messages for save success/errors: Receive immediate feedback on the success or failure of your save operations.

Math Rendering

• Inline math rendering via MathJax using $...$ delimiters: Render mathematical expressions directly in your notes for a more comprehensive documentation experience.

UI Behavior

• Light/dark theme toggle (persisted in localStorage): Customize the appearance of the interface to suit your preferences.
• Desktop: independent scrollable sidebars: Enjoy a seamless browsing experience with independently scrollable sidebars.
• Mobile: notes list capped with its own scroll area: Optimize the interface for mobile devices with a capped notes list and dedicated scroll area.

How It Works

Org Web Adapter operates by starting an HTTP server that rescans the notes directory for .org files on each page request. It resolves links and backlinks, builds HTML fragments, and injects them into the HTML template placeholders. The browser-side JavaScript handles client-side interactions such as search, shuffle, sorting, jump-to-current, and theme toggle.

Server-Side Components

• File discovery and parsing: Recursively finds .org files, extracts titles and IDs, and handles Org link/backlink resolution.
• Rendering: Converts headings and paragraphs to simple HTML and renders Org links as clickable app links.
• Editing: Updates selected .org files and redirects back with status flags.
• Static files: Serves files under the static directory with path traversal protection.

Frontend Components

• Base layout markup: Provides the structure for the 3-pane UI.
• Sidebar controls: Allows for filtering, sorting, and shuffling of navigation links.
• MathJax initialization: Enables inline math rendering using $...$ delimiters.

Configuration and Usage

Org Web Adapter reads its startup configuration from a config.yaml file by default, which includes the bind address and port. If the config file is missing, it defaults to 127.0.0.1:8000. You can override these values using CLI flags or specify a different config file.

Useful Run Commands

• python3 main.py --dir notes: Start the server with the notes directory.
• python3 main.py --host 127.0.0.1 --port 9000: Specify the host and port.
• python3 main.py --config ./config.yaml: Use a custom config file.
• python3 main.py --no-browser: Start without opening the browser automatically.

Project Layout

• main.py: The server, parsing, rendering, and routing logic.
• templates/index.html: The page template and UI behavior JavaScript.
• static/style.css: The styling and responsive layout.
• config.yaml: The configuration file for bind settings.
• notes/: The directory for your Org files (can be a symlink).
• old_notes/: An alternate local notes snapshot.

Limitations

While Org Web Adapter is a powerful tool for managing Org files, it is not a full Org parser. The rendering is intentionally simple, and notes are rescanned on each request, which may not be optimized for very large note sets. Additionally, math rendering depends on loading MathJax from a CDN.

Org Web Adapter is an excellent choice for those seeking a lightweight and efficient way to manage their Org Mode notes locally. Its simplicity and ease of use make it a valuable addition to any Org Mode user's toolkit.