markymark Markymark icon

Marky Mark spinning docs

Say hi to your docs 👋 Your personal documentation DJ - one server, always spinning

Finally, a Dedicated Markdown Viewer That Works Everywhere

Double-click a .md file in Finder? Opens in markymark. Cmd-click a path in iTerm? Opens in markymark. Run open README.md in terminal? Opens in markymark.

No more markdown files opening in Xcode, VS Code, or raw text editors. markymark gives you a beautiful, dedicated markdown viewer with navigation that integrates seamlessly with macOS - just like Preview for PDFs or QuickTime for videos.

markymark is a lightweight local markdown documentation browser that stays running in the background. Call it once from any directory, and it's always ready. Switch directories on the fly without starting new servers. Perfect for Claude Code workflows where you're constantly documenting and exploring context engineering prompts.

Quick Start (2 Steps)

# Step 1: Install the gem
gem install markymark

# Step 2: Run the setup wizard
markymark init

That's it! The wizard will:

  • Install Markymark.app to ~/Applications
  • Set markymark as the default app for .md files
  • Configure your preferred server mode

Now double-click any .md file or cmd-click paths in iTerm - they'll open beautifully rendered in markymark.

Scripted Install

For automated setups, accept all defaults:

gem install markymark && markymark init -y

Features

  • 🍎 Native macOS integration - Double-click .md files, cmd-click in iTerm, open command support
  • 🔄 Smart directory switching - Run markymark from any directory to switch existing server
  • 📁 Auto-discovery - Recursively finds all your markdown files
  • 📂 Accordion file organization - Files grouped by directory with expand/collapse controls
  • 🔖 Bookmarks - Save frequently-used directories for quick access
  • 🌐 Directory browser - Navigate to any folder via the UI with quick shortcuts
  • 🎨 GitHub-Flavored Markdown - Tables, task lists, syntax highlighting
  • 📊 Mermaid diagrams - Flowcharts, sequence diagrams render beautifully
  • 🌙 Dark/Light theme toggle - One-click switching, persisted in localStorage
  • 🔗 Bookmarkable URLs - Share links to specific docs
  • 🖼️ Image support - Images in assets/ folders render properly
  • 🌐 Pumadev integration - Optional .test domain support

Usage

Opening Files Directly

# Open a specific markdown file (the killer feature!)
markymark README.md
markymark ~/docs/ARCHITECTURE.md

# Browse current directory
markymark

# Browse specific directory
markymark ~/my-docs

When you open a file directly, markymark:

  1. Sets the root to the file's directory
  2. Opens the browser with that file displayed
  3. Shows all other markdown files in the sidebar

Server Management

# Check server status
markymark --status

# Stop running server
markymark --stop

# Custom port
markymark --port 8080

# Don't open browser automatically
markymark --no-browser

Setup Commands

# Interactive setup wizard
markymark init

# Individual setup commands
markymark --install-app     # Install Markymark.app
markymark --uninstall-app   # Remove Markymark.app
markymark --set-default     # Set as default .md handler

One Server, All Your Docs

markymark runs as a single background process. Once started, it stays running and responds to all your commands:

# Start once from anywhere
cd ~/docs/project-a
markymark

# Switch to different docs instantly - same server!
cd ~/work/api-docs
markymark  # Server switches to api-docs, no restart

# Open a specific file from anywhere
markymark ~/notes/TODO.md  # Switches to ~/notes, opens TODO.md

One server. Any directory. Always ready.

Browse & Bookmarks

markymark includes a built-in directory browser accessible via the sidebar:

  • Quick shortcuts: Jump to Home, Downloads, Desktop, or Work directories
  • Bookmarks: Save frequently-accessed directories for one-click access
  • Full navigation: Browse to any directory on your system

Bookmarks are stored in ~/.markymark/bookmarks.json and persist across sessions.

Why markymark?

If you work with AI coding assistants like Claude Code, you're probably generating documentation constantly. Design docs, implementation plans, debugging notes, context engineering prompts - all in markdown, all needing quick reference.

Claude Code Workflow

# Claude creates ARCHITECTURE.md, IMPLEMENTATION_PLAN.md, etc.
# Double-click any of them → beautifully rendered in markymark

# Exploring Claude's built-in skills?
markymark ~/.claude/commands

# Check out your AI framework prompts
markymark ~/bmad-agent

Context Engineering Made Visual

Modern AI frameworks use markdown for prompts and skills:

  • Claude Code: Skills and commands in ~/.claude/
  • BMAD: Agent method prompts and templates
  • AgentOS / OpenSpec: Specification documents
  • Custom frameworks: Your own prompt libraries

markymark renders these beautifully with:

  • Formatted tables and lists
  • Mermaid diagrams for workflows
  • Syntax-highlighted code blocks
  • Accordion navigation for nested directories

Pumadev Integration

For those who prefer .test domains over remembering ports:

# Set up pumadev integration
markymark --setup-pumadev

# Now always available at http://markymark.test

See markymark --pumadev-info for detailed setup instructions.

Requirements

  • Ruby >= 2.7

Installing Ruby

markymark requires Ruby 2.7 or higher. macOS includes Ruby 2.6, which is too old. Install a modern Ruby via:

# Homebrew
brew install ruby

# Or use a version manager (rbenv, rvm, asdf)
rbenv install 3.3.0

Platform Support

markymark's core markdown viewer works on any platform with Ruby - macOS, Linux, Windows.

# Works everywhere
markymark ~/docs
markymark README.md

macOS Native Integration

The native app integration (double-click .md files, cmd-click in iTerm, open command) is macOS only and requires:

  • Xcode Command Line Tools (for Swift compilation during markymark init)
# Install Xcode Command Line Tools if you don't have them
xcode-select --install

# Then run the setup wizard
markymark init

Contributing Cross-Platform Native Integration

We'd love native file associations on other platforms! Contributions welcome for:

  • Linux: .desktop file integration, xdg-open support
  • Windows: Registry associations, shell integration

Development

git clone https://github.com/fkchang/markymark.git
cd markymark
bundle install

# Run locally
bundle exec exe/markymark /path/to/docs

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/fkchang/markymark.

License

The gem is available as open source under the terms of the MIT License.

♪ ♫ ♪
♫ Markymark ♪
♫ ♪ ♫

Built with good vibrations 🎵