MDView - Markdown Viewer

A modern Chrome extension for viewing Markdown files with beautiful themes, syntax highlighting, and interactive Mermaid diagrams.

Features

Core Functionality

• Markdown Rendering: Full CommonMark + GitHub Flavored Markdown support
• 8 Beautiful Themes: GitHub (Light/Dark), Catppuccin (Latte/Frappé/Macchiato/Mocha), Monokai, Monokai Pro
• Syntax Highlighting: Support for 195+ programming languages with Highlight.js
• Interactive Mermaid Diagrams: All diagram types with zoom, pan, maximize, and export
• Table of Contents: Floating overlay for quick navigation and document structure visualization
• Auto Dark Mode: Automatically switch themes based on system preference
• File Change Detection: Auto-reload when markdown files are modified

Advanced Features

• Progressive Hydration: Instant rendering for large files (instant skeleton + background hydration)
• Worker-Based Processing: Heavy tasks (parsing, highlighting) run in web workers to keep UI responsive
• Lazy Loading: Images, code highlighting, and Mermaid diagrams load on-demand
• Copy Code Blocks: One-click copy button for all code blocks
• Export Diagrams: Export Mermaid diagrams as SVG files
• Document Export: Export to Word (.docx) and PDF formats with Mermaid diagrams as embedded graphics
• Keyboard Shortcuts: Navigate and interact without mouse
• Multi-Tab Sync: Sync theme and settings across all markdown tabs
• Responsive Design: Works on all screen sizes

Installation

From Chrome Web Store

Coming soon! MDView will be available on the Chrome Web Store.

From Source

1. Clone this repository:

   git clone https://github.com/jamesainslie/mdview.git
   cd mdview

2. Install dependencies:

   npm install

3. Build the extension:

   npm run build
   # or using Makefile
   make build

4. Load in Chrome:

   • Open chrome://extensions/
   • Enable "Developer mode"
   • Click "Load unpacked"
   • Select the dist folder

⚠️ REQUIRED: Enable File Access

MDView will not work without this step!

To view local markdown files:

1. Go to chrome://extensions/
2. Find MDView - Markdown Viewer
3. Click "Details"
4. Scroll down and enable "Allow access to file URLs"

Usage

Opening Markdown Files

1. Open any .md or .markdown file in Chrome using file:// protocol
2. The file will automatically be rendered with your selected theme

Changing Themes

• Popup: Click the extension icon and select a theme
• Options Page: Right-click icon → Options → Appearance
• Auto Mode: Enable "Auto Dark Mode" to switch based on system preference

Using Table of Contents

• Enable: Click extension icon → Toggle "Table of Contents"
• Navigate: Click any heading to jump to that section
• Auto-highlight: Current section is automatically highlighted as you scroll
• Collapse: Enable auto-collapse in Options for cleaner nested structure
• Depth Control: Configure max heading depth (H1-H2, H1-H3, etc.) in Options
• Close: Click X button or press Esc
• Responsive: Automatically hidden on screens narrower than 768px

Interacting with Mermaid Diagrams

• Zoom: Mouse wheel (+ Ctrl/Cmd) or +/- keys
• Pan: Click and drag, or Shift + arrow keys
• Reset: Click reset button or press 0
• Fit to View: Click fit button or press f
• Maximize: Click maximize button or press m
• Export SVG: Click export button or press e
• Close Maximize: Click X or press Esc

Exporting Documents

MDView allows you to export rendered markdown documents to Word (DOCX) and PDF formats.

Export Options

• Word Document (.docx): Creates a properly formatted Word document with embedded diagrams
• PDF / Print: Opens the browser print dialog for saving as PDF

How to Export

1. Click the export button (download icon) next to the TOC toggle
2. Select your desired format from the dropdown menu
3. Optionally adjust page size and table of contents options
4. Click the format button to start export

Export Features

• Mermaid Diagrams: Embedded as scalable vector graphics (SVG) for crisp rendering at any zoom level
• Code Blocks: Preserved with monospace formatting
• Tables: Exported with proper borders and headers
• Links: External URLs shown in printed/PDF output
• Word Compatibility: SVG diagrams include automatic style inlining for reliable rendering in Word 2016+

Customizing Export Settings

Access export preferences via Options page (right-click icon → Options → Export):

• Default export format
• Default page size (A4 or Letter)
• Include table of contents
• Filename template with variables ({title}, {date}, etc.)

Known Limitations

• Syntax highlighting colors are not preserved in DOCX (uses monospace font)
• Complex nested lists may have simplified formatting
• Very large documents (>5MB) may take longer to export
• SVG diagrams require Microsoft Word 2016 or later (older versions may show placeholder images)

Keyboard Shortcuts

• +/=: Zoom in
• -: Zoom out
• 0: Reset zoom
• f: Fit diagram to view
• m: Maximize diagram
• e: Export diagram as SVG
• Esc: Close maximized diagram
• Shift + Arrows: Pan diagram

Development

Build System

MDView includes both NPM scripts and a Makefile for building and development tasks. The Makefile provides a convenient, standardized interface for common operations with helpful shortcuts and clean output.

Project Structure

mdview/
├── src/
│   ├── background/        # Service worker
│   ├── content/           # Content script
│   ├── core/              # Core rendering logic (pipeline, converter)
│   ├── renderers/         # Syntax & Mermaid renderers
│   ├── workers/           # Web workers for heavy processing
│   ├── ui/                # UI components
│   ├── utils/             # Utilities
│   ├── themes/            # Theme definitions
│   ├── popup/             # Extension popup
│   └── options/           # Options page
├── public/                # Static assets
├── tests/                 # Test files
└── docs/                  # Documentation

Development Commands

Using NPM

# Development mode (auto-reload)
npm run dev

# Build for production
npm run build

# Run unit tests
npm test

# Run E2E tests
npm run test:e2e

# Lint code
npm run lint

# Format code
npm run format

Using Makefile

# Show all available targets
make help

# Build for production
make build

# Development mode (auto-reload)
make dev

# Run unit tests (watch mode)
make test

# Run tests once (CI mode)
make test-ci

# Lint code
make lint

# Format code
make format

# Install dependencies
make install

# Generate icons from SVG
make icons

# Create distribution zip
make dist-zip

# Clean build artifacts
make clean

# Rebuild from scratch
make rebuild

# Run all checks (lint + test)
make check

Tech Stack

• Build: Vite 5.x + TypeScript 5.3+
• Markdown: markdown-it v14.x + plugins
• Syntax Highlighting: Highlight.js v11.x
• Diagrams: Mermaid.js v11.x + Panzoom v9.x
• Document Export: @jamesainslie/docx (fork with SVG support)
• Security: DOMPurify v3.x
• Testing: Vitest + Playwright

Configuration

Settings

Access full settings via Options page (right-click icon → Options):

Appearance

• Theme selection
• Auto dark mode
• Light/dark theme pairs

Editor

• Font family and size
• Line height
• Maximum width

Code Blocks

• Syntax highlighting theme
• Line numbers toggle
• Code font family

Table of Contents

• Show/hide toggle
• Max heading depth (H1-H2, H1-H3, H1-H4, H1-H5, or all levels)
• Auto-collapse nested sections

Diagrams

• Default zoom level
• Animations toggle
• Render timeout

Export

• Default format (DOCX/PDF)
• Page size (A4/Letter)
• Include table of contents
• Filename template

Performance

• Auto-reload on file change
• Reload debounce time
• Lazy loading threshold

Advanced

• Tab synchronization
• Cache management
• Settings import/export

Theme Customization

Themes are defined in src/themes/ directory. Each theme includes:

• 25+ color variables
• Typography settings
• Spacing configuration
• Syntax highlighting theme
• Mermaid theme variables

Performance

Benchmarks

• Initial Render: < 200ms for files < 100KB
• Theme Switching: < 100ms
• Scrolling: 60fps maintained
• Memory Usage: < 200MB typical
• Bundle Size: < 2MB gzipped

Optimization Techniques

• Progressive Hydration: Instant skeleton rendering for perceived performance
• Web Workers: Off-main-thread parsing and syntax highlighting
• Intersection Observer: Lazy loading for images and heavy components
• Three-tier caching: Memory → IndexedDB → Service Worker
• Code splitting: Dynamic imports for large dependencies (Mermaid, Highlight.js)
• Debounced file change detection: Efficient file watching

Browser Support

• Chrome 110+
• Edge 110+
• Other Chromium-based browsers

Security

• Strict Content Security Policy
• DOMPurify sanitization for all content
• No external network calls
• Minimal permissions (storage, scripting, file://)
• Safe Mermaid rendering (securityLevel: 'strict')

Accessibility

• WCAG 2.1 Level AA compliant
• Full keyboard navigation
• Screen reader support
• Semantic HTML elements
• ARIA labels where appropriate
• Focus indicators
• High contrast mode support

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request

Code Standards

• TypeScript strict mode
• ESLint + Prettier
• Conventional commits
• 80% test coverage minimum

License

MIT License - see LICENSE for details.

Acknowledgments

• markdown-it
• Highlight.js
• Mermaid.js
• DOMPurify
• Catppuccin
• docx (upstream library for DOCX generation)

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Changelog

See CHANGELOG.md for version history.

Screenshots

---

Made with ❤️ by James Ainslie