Server Mode

Server mode starts a local web server, allowing you to browse your markdown files in any web browser with live reload.

Starting the Server

mbr -s /path/to/notes

By default, the server runs at http://127.0.0.1:5200/.

Features

Live Reload

When you save changes to a file, the browser automatically reloads:

1. mbr watches for file changes via the filesystem
2. Changes trigger a WebSocket notification
3. Connected browsers refresh the current page

This works for:

• Markdown file content
• YAML frontmatter changes
• Template modifications (in .mbr/)
• CSS/style changes

Full-Text Search

Press / or click the search icon to open search:

• Search across all markdown files
• Filter by metadata, content, or both
• Scope to current folder or everywhere
• Results show snippets with highlighted matches

Directory Browsing

Navigate your markdown repository:

• Folder listings with file counts
• Subdirectory navigation
• Breadcrumb trail for context
• Sort by name, date, or title

Tag Navigation

If your files use YAML frontmatter with tags:

---
tags: project, important, review
---

The sidebar shows a tag tree for filtering files.

Recent Files

mbr tracks recently viewed files (stored in browser localStorage), providing quick access to your working set.

External Links

Server mode deliberately does nothing with external links. https:// links, mailto:, message:, zoommtg: and every other scheme are left entirely to the browser you are visiting with, which already opens them the way you expect. Same for static builds.

This is the opposite of GUI mode, where there is no browser to defer to and mbr hands the URL to the operating system itself. That hand-off is GUI-only by design and enforced at runtime: the launcher refuses, before touching the OS, unless a GUI window is actually running in the process, and logs the refusal at warn.

The reason is worth stating plainly: a server must never be induced to launch applications on its host. Launching an application is something an interactive window does for the person in front of it. mbr -s has no such person, and if a page could make the serving process start programs, anyone who could reach that page — especially on a shared or non-loopback bind — could start programs on the machine running it. So the capability simply is not available outside GUI mode, regardless of what a page, a template override, or a future code path asks for.

File Browser Sidebar

Press - (minus key) to open the file browser sidebar. This is a three-pane navigator for exploring your entire markdown collection.

Layout

┌──────────────────────────────┐
│  × Close                     │
├──────────────────────────────┤
│  🔍 Filter...                │
├──────────────────────────────┤
│  SHORTCUTS                   │
│    ⭐ My Important File      │
│    ⭐ Daily Notes            │
├──────────────────────────────┤
│  RECENT                      │
│    📄 guide.md               │
│    📄 notes.md               │
├──────────────────────────────┤
│  TAGS                        │
│    ▸ project (12)            │
│    ▸ review (5)              │
│    ▾ important               │
│        ▸ urgent (3)          │
├──────────────────────────────┤
│  FOLDERS                     │
│    ▸ docs/ (24)              │
│    ▸ notes/ (156)            │
│    ▾ projects/               │
│        ▸ website/ (8)        │
└──────────────────────────────┘

Browser Sections

Keyboard Shortcuts

Pinning Shortcuts

Right-click any file in the browser to add it to your shortcuts. Shortcuts appear at the top for instant access to frequently used files.

To remove a shortcut, right-click it and select “Remove from shortcuts.”

Tag Hierarchy

Tags support hierarchical organization using / as a separator:

---
tags: project/website, project/website/frontend
---

This creates a nested tag tree:

• project (parent)
  • website (child with count)
    • frontend (grandchild)

Click a parent tag to see all files with that tag or any descendant tags.

Persistence

The browser remembers your preferences across sessions:

Full-Text Search

Press / (forward slash) to open the search dialog.

Search Features

Search Syntax

Keyboard Navigation

Link Explorer

Press f, F, or T to open the Link Explorer - a quick navigation modal for jumping between pages and headings.

Tabs

Features

• Fuzzy search - Type to filter items with intelligent matching
• Visibility awareness - In ToC mode, currently visible headings are prioritized and marked
• Internal vs External - External links open in new tabs, internal links navigate in place. In GUI mode there are no tabs, so external links go to your default browser instead
• Link handling is your browser’s - Server mode never touches external links itself; see External links below
• Tab cycling - Press Tab to cycle between the three views

Layout

┌──────────────────────────────────────────┐
│  [Links Out]  [Links In]  [ToC]          │
├──────────────────────────────────────────┤
│  🔍 Filter...                            │
├──────────────────────────────────────────┤
│  → Getting Started                       │
│  → Installation Guide                    │
│  → API Reference               ↗ (ext)   │
│  ← docs/intro (backlink)                 │
├──────────────────────────────────────────┤
│  ^n ^p navigate  Tab switch  Enter open  │
└──────────────────────────────────────────┘

Keyboard Shortcuts

Link Tracking

The Links Out and Links In tabs require link tracking to be enabled (default). This is controlled by the link_tracking config option:

# .mbr/config.toml
link_tracking = true  # default

When enabled, mbr automatically tracks:

• Outbound links - All markdown links [text](url) in the current page
• Inbound links - All pages that link to the current page (backlinks)

This enables wiki-style bidirectional link navigation without requiring any special syntax.

Server Endpoints

Canonical URL Redirects

Markdown pages have exactly one URL: the directory-style one with a trailing slash (docs/guide.md → /docs/guide/). Any other spelling gets a 301:

GET /docs/guide      → 301 Location: /docs/guide/
GET /docs/guide.md   → 301 Location: /docs/guide/
GET /docs            → 301 Location: /docs/          (docs/index.md)
GET /docs/index/     → 301 Location: /docs/
GET /docs/guide?x=1  → 301 Location: /docs/guide/?x=1

This is not cosmetic. The trailing slash decides the base a browser uses for the page’s own relative links: from /docs/guide/ a ../other/ href reaches /docs/other/, but from /docs/guide it reaches /other/. Serving the page in place at the slashless URL would break every link on it, one click later.

Static files (/images/photo.png, /LICENSE), directory listings and /.mbr/* routes are never redirected.

Search API

The search endpoint accepts POST requests:

{
  "q": "search query",
  "limit": 50,
  "scope": "all",
  "filetype": "markdown",
  "folder": "/docs"
}

Response:

{
  "query": "search query",
  "total_matches": 42,
  "results": [
    {
      "url_path": "/docs/guide/",
      "title": "Guide",
      "description": "...",
      "tags": "...",
      "score": 95,
      "snippet": "..."
    }
  ],
  "duration_ms": 15
}

Configuration

Port Configuration

Default port is 5200. Change via configuration:

# .mbr/config.toml
port = 3000

Or environment variable:

MBR_PORT=3000 mbr -s ~/notes

If the configured port is in use, mbr automatically tries the next port.

IP Binding

By default, mbr binds to 127.0.0.1 (localhost only). To allow network access:

# .mbr/config.toml
ip = "0.0.0.0"

Warning: Binding to 0.0.0.0 exposes your files to the network.

oEmbed Timeout

Control how long mbr waits for URL metadata:

mbr -s --oembed-timeout 1000 ~/notes  # 1 second

Development Workflow

A typical writing workflow:

# Terminal 1: Start server
mbr -s ~/notes

# Terminal 2: Edit files
vim ~/notes/new-article.md

Changes appear in the browser automatically.

With Editor Integration

Many editors can open URLs on save. Configure your editor to:

1. Save the file
2. Trigger browser refresh (or let live reload handle it)

Multiple Repositories

Run multiple servers on different ports:

mbr -s ~/notes &                    # Default port 5200
MBR_PORT=5201 mbr -s ~/docs &       # Custom port 5201

Caching

mbr provides proper cache headers for browser caching:

• ETag: Content-based cache validation
• Last-Modified: Time-based cache validation

Browsers can cache static assets and validate on subsequent requests.

Troubleshooting

Port Already in Use

If you see “Address already in use”:

1. Another mbr instance may be running
2. Another application is using the port
3. Try a different port: MBR_PORT=3000 mbr -s ~/notes

Live Reload Not Working

If changes don’t appear:

1. Check WebSocket connection in browser DevTools
2. Ensure file is being saved (not just buffered)
3. Verify file is in the watched directory
4. Check for errors with -v flag

Slow Initial Load

For large repositories:

1. First load scans all files for metadata
2. Subsequent loads are faster (browser caching)
3. Consider using ignore_dirs to skip large directories