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.

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

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

• 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
• Collapsible TOC at the top of the page on narrow/mobile screens
• 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

• Clean, book-inspired interface that adapts from desktop to mobile
• TOC transitions from a fixed sidebar to a collapsible panel and swipe drawer on narrow screens
• Tables scroll horizontally when they overflow on small screens
• Metadata tables reflow to stacked layout on mobile

• Ruby >= 3.0

MIT