markdownr

A local web server for browsing and reading markdown files with a clean, book-inspired interface.

Point it at any directory and get a navigable website with rendered markdown, syntax-highlighted code, YAML frontmatter display, wiki-link resolution, and auto-generated tables of contents.

Rendering docs/examples/overview.md

This was written primarily by Claude Code.

gem install markdownr

git clone https://github.com/brianmd/markdown-server.git
cd markdown-server
bundle install
ruby bin/markdownr [directory]

markdownr [options] [directory]

Serves the current directory if none is specified.

# Serve the current directory
markdownr

# Serve a specific directory on port 3000
markdownr -p 3000 ~/notes

# Run multiple servers at once (uses Procfile.markdownr)
overmind start -f Procfile.markdownr        # start all
overmind restart lofts                      # restart one
overmind restart                            # restart all
overmind quit                               # stop all

# Serve with a custom title
markdownr -t "Field Notes" ~/research

# Enable the bible citations plugin
markdownr --plugin bible_citations ~/bible-notes

# Load plugins from an external directory
markdownr --plugin-dir ~/my-markdownr-plugins ~/notes

A minimal config enabling the bible citations plugin:

plugins:
  bible_citations:
    enabled: true

A fuller config with all available options:

plugins:
  bible_citations:
    enabled: true
    version: "CEB"            # Bible translation (default: CEB)
    link_target: scrip        # "scrip" or "biblegateway"
    dictionary_url: https://example.com/dictionary.json

# Load additional plugins from external directories
plugin_dirs:
  - /path/to/custom/plugins
  - ~/my-markdownr-plugins

# Popup behavior for link previews
popups:
  local_md: true              # popups for internal .md links
  local_html: false           # popups for internal .html links
  external: true              # popups for external links
  external_domains: []        # limit external popups to specific domains

• GitHub Flavored Markdown -- tables, task lists, strikethrough, autolinks, and more (via Kramdown GFM)
• Syntax highlighting for fenced code blocks and standalone source files (via Rouge)
• YAML frontmatter parsed and displayed in a collapsible metadata table
• Wiki links -- [[page-name]] resolves to matching .md files anywhere in the directory tree

• Auto-generated sticky sidebar for documents with multiple headings (on wide screens)
• Scroll spy highlights the current heading as you read
• Swipe-to-reveal TOC drawer on touch devices -- swipe left to open, swipe right to dismiss
• Floating TOC button on narrow screens for mouse users -- click to open the sliding drawer
• Tapping a heading in the drawer navigates there and closes the panel

• Full-text search across file contents within any directory subtree
• Searching from a markdown file shows only matches within that file
• Multi-word queries require all words to match (AND logic, any order)
• Each search term can be a regex (e.g., \d{4} or e.*him)
• Results show matching lines with context, highlighted matches, and line numbers
• Clickable results jump directly to the matching line in the document
• Long lines are truncated with the match kept visible
• Search box available on every page (directories search within; files search their parent directory)

• Directory browsing with file sizes, modification dates, and sortable columns (name, modified, created)
• Sort persistence -- your chosen sort order is remembered across directories via localStorage
• Breadcrumb navigation on every page, auto-hides on scroll and reappears on scroll-up or tap
• Scroll position memory -- reopening a document returns you to the last heading you were reading

• JSON files rendered as syntax-highlighted YAML for readability
• PDF served in an inline viewer
• EPUB served as a download
• Source files (.py, .rb, .js, .sh, .yaml, .html, etc.) displayed with syntax highlighting
• Other text files shown as plain text; binary files served as downloads

• Hover preview -- hovering a local markdown link shows a popup with the linked document's content
• Click popup -- clicking a local markdown link shows the same popup; click again or follow to navigate
• Popup navigation -- links inside a popup load that document into the same popup, with a back button (←) to return to the previous document; browse several documents without leaving the page
• Popups auto-close on mouse leave; disabled with --no-link-tooltips

• Set --index-file index.md (or any filename) to render that file instead of the directory listing when it is present in a directory
• The directory listing is still accessible via the breadcrumb or direct URL
• Embed the directory listing inline inside any markdown file using these tokens, each on its own line:
  • {{directory}} -- always renders the listing at that position
  • {{admin-directory}} -- renders the listing only for admins; renders nothing for other visitors

Place a .setup.yml file in the root of the served directory to enable admin features:

admin:
  user: myusername   # login form username
  pw: mypassword     # login form password
  ip: 192.168.1.10   # optional: automatically grant admin if request comes from this IP

The ip field accepts a single address, a list of addresses, or CIDR notation:

admin:
  ip:
    - 192.168.86.0/24   # entire subnet
    - 10.0.0.5           # specific address

Admin access is required to save or delete CSV rows. Non-admin users can browse and view data but will be prompted to log in when attempting edits.

Admin routes:

• GET /admin/login -- login form (username + password)
• GET /admin/logout -- clears the session
• GET /setup-info -- shows your IP, served path (admins only), and any non-admin config keys from .setup.yml

Any non-admin keys in .setup.yml are public and displayed on /setup-info. The admin block is never exposed.

Sessions are signed with a random secret (re-generated on each server start). For sessions that survive restarts, set the MARKDOWNR_SESSION_SECRET environment variable to a long random string before starting the server.

When running behind a reverse proxy, pass --behind-proxy so the real client IP is read from X-Forwarded-For instead of the direct connection address.

Place a .markdownr.yml file in the root of your served directory (see Example .markdownr.yml above for the full format).

Plugin settings can also be controlled via environment variables:

MARKDOWNR_PLUGIN_BIBLE_CITATIONS_ENABLED=true markdownr ~/notes

Priority order (highest wins): CLI flags > environment variables > .markdownr.yml > defaults.

• Schema-driven database browser -- define tables with JSON Schema properties in a YAML config and browse CSV data in a popup-based UI
• Foreign key navigation -- columns can reference other tables; clicking a foreign key cell opens the referenced table filtered to that record
• Related tables -- tables automatically show links to other tables that reference them (e.g., a Students table shows an Enrollments button on each row)
• Per-column filtering -- global regex search plus per-column filter inputs that combine with AND logic
• View/edit modes -- view mode for navigating between tables; edit mode for inline cell editing with server-side JSON Schema validation
• Table colors -- each table can have a color used for title bars, FK cell tints, and related-table buttons

See CSV Browser documentation for setup instructions, configuration reference, and a walkthrough of all features. A working example is in the school fixture.

Quick start -- add to .markdownr.yml:

csv_databases:
  - data/school.yaml     # path relative to served directory

• Bare verse citations are auto-linked -- e.g. John 3:16, Rom. 12:1, 1 Cor 5:7
• Links are styled bold purple to distinguish them from regular links
• Citations inside code spans, fenced code blocks, or existing markdown links are left untouched
• Supports a wide range of book abbreviations (full names, standard short forms, dotted forms) for all OT, NT, and deuterocanonical books present in the CEB
• Opt-in -- enable with --plugin bible_citations or via .markdownr.yml (see Configuration)
• Configurable link target (scrip or biblegateway), Bible version (default: CEB), and Strong's dictionary URL

• Wide-mode expand -- each table has a floating expand button (⤢) that widens the page to full viewport width, left-aligning the content for maximum reading area
• Tables scroll horizontally when they overflow on small screens
• Swiping on a table does not trigger the TOC drawer, so horizontal table scrolling works without interference

• Clean, book-inspired interface that adapts from desktop to mobile
• TOC transitions from a fixed sidebar to a swipe drawer on narrow screens
• Metadata tables reflow to stacked layout on mobile

flowchart TD
    req[HTTP Request] --> route{Route}

    route -->|GET /| redir[redirect → /browse/]
    route -->|GET /robots.txt| robots[robots.txt response]
    route -->|GET /version| ver[version + active plugins → JSON]
    route -->|GET /download/*| dl[send_file as attachment]
    route -->|GET /fetch| fetch[plugin dispatch → JSON]
    route -->|GET /preview/*| prev[render_markdown → JSON]
    route -->|GET /search/*| srch[compile_regexes → search.erb]
    route -->|GET /browse/*| sp{safe_path\ncheck}

    sp -->|traversal / excluded| err[403 / 404]
    sp -->|directory| rd[render_directory\n→ directory.erb]
    sp -->|file| ext{Extension?}

    ext -->|.md| md[parse_frontmatter\nrender_markdown\nextract_toc\n→ markdown.erb]
    ext -->|.json| json[JSON → YAML\nsyntax_highlight\n→ raw.erb]
    ext -->|.pdf| pdf[send inline]
    ext -->|.epub| epub[redirect /download/]
    ext -->|source files| src[syntax_highlight\n→ raw.erb]
    ext -->|binary| bin[send as download]

The steps inside render_markdown must run in this order:

flowchart TD
    A[Raw markdown text] --> P

    P["0 · Plugin transforms\nEach enabled plugin's transform_markdown\nruns in sequence (e.g. Bible citation auto-linking)"]
    P --> B

    B["1 · Resolve wiki links\n\[\[page\]\] and \[\[page|label\]\] → inline HTML\nMust run before Kramdown so the pipe character\nis not consumed as a GFM table delimiter"]
    B --> C

    C["2 · Kramdown GFM\nConverts markdown → HTML\nGenerates heading IDs and numbers all\nfootnote references sequentially (1, 2, 3…)"]
    C --> D

    D["3 · Restore footnote labels\nKramdown replaces \[^name\] with a number;\ntwo post-processing regexes restore the\noriginal label in both the inline superscript\nand the footnote list at the bottom"]
    D --> E[Final HTML]

# Run unit and integration tests (no browser required)
bundle exec rspec

# Run all tests including browser tests (requires Chrome)
BROWSER_TESTS=1 bundle exec rspec

# Lint (style cops disabled, Lint/Security enabled)
bundle exec rubocop

Browser tests use headless Chrome via Capybara and selenium-webdriver. On macOS, the spec automatically locates the version-matched chromedriver from the selenium cache, clears any Gatekeeper quarantine, and ad-hoc signs it before running.

• Ruby >= 3.0

MIT