meshfox

 /\_/\
( ¬‿¬ )──●──●──●
  c c

Website · Online editor · GitHub · Download binary

An interactive canvas: a hierarchical, node-based document where nodes hold Markdown, and code blocks inside that Markdown can be run.

Meshfox pulls together several documentation patterns that are usually spread across separate tools into one file format: the mindmap-style canvas of Miro and Obsidian, Livebook’s lightweight markdown-compatible storage, code-in-document execution from Jupyter Notebook and Livebook, and Make’s dependency graph for running scripts. A built-in Starlark constraint system (meshfox check) lets a canvas enforce its own consistency rules, and a canvas can be exported to a static HTML site or a PDF (both experimental — see EXPORT.canvas.md).

Status: β. To get started, see "Install" below.

This document is itself a valid meshfox canvas — every ## section here is a node, nested under this root. See SPEC.md for more details.

• A project is one canvas: a tree of nodes starting from a single root node.
• From the root, large section nodes branch off (e.g. one section per feature).
• From sections, further block nodes branch off. Blocks hold Markdown.
• A canvas is stored as a single, plain .md file — node metadata (ids, positions, edges) lives in HTML comments, so the file still renders sensibly in GitHub or any plain Markdown viewer, and diffs cleanly in git.
• Markdown inside a block can contain fenced code. A fence can be marked runnable; running it executes the code and (optionally) writes the result back into the same node, right under the code, so nobody has to re-run it just to see what happened last time.
• A runnable fence can declare deps= on other blocks — running it runs its whole dependency chain first, make-style, with nothing run twice. Blocks can also share document-scoped config values (declared once as meshfox:var), each block opting in individually via its own env= attribute — so running one block never prompts for a variable only some other block needs. A ```button fence is the same deps=/name=/default= machinery with no real code of its own — a prominent shortcut button, captioned by its own body (and, via name=/default=, a short CLI alias) for a chain that lives elsewhere in the document — see SPEC.md's "Button fences".
• Three ways to interact with the same files:
  • a browser UI (canvas view + block runner) backed by a small Rust server — opens read-only, so pulling up a canvas to look around never one-click-modifies it: running a block is always allowed (you're still explicitly clicking "run", and it's the whole point of a canvas), but a cached block's output isn't written back to the file until an explicit "Edit" button is clicked, which also unlocks dragging, resizing, and saving layout. Output streams into the browser live as the block runs (not just once it's finished), and a running block gets a Kill button, for when one hangs.
  • a CLI that runs blocks non-interactively, make-style, for use in scripts/CI — meshfox list prints every runnable block as a tree, so there's no need to go spelunking through the file to find out what's runnable. meshfox run streams output live too (the same async, killable executor as the browser UI); Ctrl+C kills whichever step is currently running, whole process group and all, and stops there — whatever earlier steps in the chain already completed stays cached.
  • a terminal UI (meshfox tui) — the browser's tree-and-block-runner experience without leaving the terminal: browse the node tree, read a node's rendered body (syntax-highlighted code, images), and run blocks with the same live streaming/kill/cache behavior as the other two. See "Terminal UI" in INTERFACES.canvas.md.
• Beyond editing and running: a built-in Starlark constraint system (meshfox check) lets a canvas validate its own consistency, and a canvas can be exported to a static HTML site or a PDF (both experimental — see EXPORT.canvas.md).

The web node editor keeps title and Markdown edits in a local draft. Apply (or Ctrl/Cmd+S) saves both together and leaves the editor open; Save & close waits for a successful save before closing. Cancel discards changes since the last save. Conflicts keep the draft open for comparison.

Install

Install on Linux/macOS in one line:

curl -fsSL https://raw.githubusercontent.com/orofarne/meshfox/main/scripts/install.sh | sh

Or install the Meshfox CLI on macOS or Linux with Homebrew (Apple Silicon/ARM64 and Intel/x86-64):

brew install orofarne/tap/meshfox

Update a Homebrew installation with:

brew update
brew upgrade orofarne/tap/meshfox

Use Homebrew to update this installation rather than meshfox check-updates. The formula installs the CLI, including its terminal and web interfaces.

Or run it in Docker (linux/amd64 and linux/arm64, nothing to install; see "Docker image" below for the options). There are two images. slim (the default) is meshfox with bash, git and DuckDB (for tables):

docker run --user "$(id -u):$(id -g)" -p 127.0.0.1:4590:4590 \
  -e MESHFOX_TOKEN=change-me -v "$PWD":/work ghcr.io/orofarne/meshfox

full adds Python 3, Node.js and Chromium (for blocks in those languages and for meshfox pdf):

docker run --user "$(id -u):$(id -g)" -p 127.0.0.1:4590:4590 \
  -e MESHFOX_TOKEN=change-me -v "$PWD":/work ghcr.io/orofarne/meshfox:full

This is the beginning of the README. Read the rest at the original. Read the full README ↗