Folio: a mobile-friendly file browser with Markdown and Code rendering.

Serve any directory as a browsable website. Markdown files are rendered with LaTeX math and syntax-highlighted code. Code files get syntax highlighting and a navigable outline. PDFs and images display natively. Everything else shows as plain text.

Built for one workflow: run it on your laptop, read your notes on your phone. Pair it with Tailscale to securely access your files from anywhere without exposing your laptop to the internet.

Install

npm install -g folio-serve

Or clone and link locally:

git clone <repo-url>
cd folio
npm install
npm run build   # generate dist.css (gitignored) — required for page styling
npm link

Usage

folio /path/to/your/notes

Then open http://localhost:3000.

| Option | Default | Description | |--------|---------|-------------| | [directory] | . | Directory to serve | | --port PORT | 3000 | Port number | | --address ADDR | 127.0.0.1 | Bind address. Loopback-only by default — this server has no authentication, so binding wider exposes every served file to anyone who can reach the port. To reach it from another device: 0.0.0.0 only behind a firewall; the node's Tailscale IP (100.x.y.z) for tailnet-only access; or keep the default and run tailscale serve <port> (adds HTTPS via your *.ts.net name). | | --allow-symlinks | off | Follow symlinks that resolve outside the served directory | | --dev | off | Enable livereload for development |

Features

Directory listing — folders and files sorted separately by last-modified time (latest first), each row showing size and mtime. Breadcrumb navigation at the top.

Markdown — rendered with:

• LaTeX math ($...$ and $$...$$), rendered server-side with KaTeX
• Syntax-highlighted code blocks via shiki (same grammar engine as VS Code)
• Floating outline button for navigating long documents
• Tables, links, images, and all standard Markdown features

Code files (.py, .js, .mjs, .jsx, .ts, .tsx, .c, .h, .cc, .cpp, .hpp, .rs, .go, .sh, .bash, .zsh, .json, .yaml, .toml, .sql, .html, .css) — syntax-highlighted, with a floating outline panel for Python, JavaScript, and TypeScript (incl. JSX/TSX).

Everything else — PDFs, images, and media display in the browser. Text files show as plain text. Files over 2 MB show a download button instead of rendering.

How it works

The server is a single Node.js process using the built-in http module. No framework. It leverages three tools from the VS Code ecosystem:

• markdown-it — the same Markdown engine behind VS Code's preview, with plugins for KaTeX math and heading anchors
• shiki — VS Code's TextMate grammars for syntax highlighting, producing inline styles server-side
• Tree-sitter — structural parsing for code outlines (class and function definitions)

Pages are server-rendered HTML with Tailwind CSS for styling. No client-side JavaScript is needed to display content — your phone receives a static HTML page. The only client JS is the outline toggle button and the optional livereload script in --dev mode.

Development

For live editing of styles and templates:

npm run dev -- /path/to/notes --port 3000

This uses node --watch (Node 18+) to auto-restart the server on source file changes, and --dev injects a livereload script that auto-refreshes the browser after each restart.

Security

Designed for private networks (e.g. Tailscale). No authentication or HTTPS.

Path traversal and symlink escape attacks are prevented — the server verifies that every resolved path stays within the served directory.

License

MIT