GNOME Markdown QuickLook

Beautiful markdown previews for GNOME - Press Space in Nautilus to preview .md files with rich formatting, syntax highlighting, and multiple flavor support.

Similar to macOS QLMarkdown, this extension brings Quick Look-style markdown previews to GNOME Linux desktops.

✨ Features

• 🚀 8 Markdown Flavors - GitHub, CommonMark, Pandoc, GitLab, and more
• 🎨 Auto Theme Detection - Seamlessly adapts to GNOME light/dark themes
• 🔧 Syntax Highlighting - Powered by Pygments with 40+ styles
• 📊 Rich Content - Tables, task lists, math equations, Mermaid diagrams
• ⚡ Instant Preview - Sub-second rendering with WebKit2GTK
• 🌐 Standards Compliant - Full HTML5 + CSS3 + JavaScript support

🚀 Quick Install

curl -fsSL https://raw.githubusercontent.com/noboomu/gnome-markdown-quicklook/main/install.sh | bash

That's it! The installer will handle dependencies, setup, and configuration automatically.

📋 Supported Markdown Flavors

Flavor	Specification	Key Features
GFM	GitHub Flavored Markdown	Tables, task lists, strikethrough, @mentions
CommonMark	CommonMark 0.31.2	Standards-compliant parsing
PyMdown	Enhanced GitHub-like	Emoji, keyboard keys, advanced highlighting
Pandoc	Pandoc Markdown	Extensive extensions, citations, metadata
Extra	PHP Markdown Extra	Definition lists, abbreviations, footnotes
GitLab	GitLab Flavored Markdown	GFM + GitLab-specific references (!123, etc.)
MMD	MultiMarkdown v6	Metadata, citations, advanced tables
Standard	Python Markdown	Basic markdown features

🎯 Usage

Basic Usage

1. Open Nautilus (GNOME Files)
2. Select any .md file
3. Press Space → Preview opens instantly!
4. Press Escape to close

Advanced Usage

Test different flavors:

sushi-markdown-converter document.md --flavor gfm
sushi-markdown-converter document.md --flavor commonmark
sushi-markdown-converter document.md --flavor pandoc

Export to HTML:

sushi-markdown-converter document.md --output preview.html --flavor gfm

List all flavors:

sushi-markdown-converter --help

📝 Supported File Types

• .md - Standard Markdown
• .markdown - Markdown document
• .mdown - Markdown document
• .mkd - Markdown document
• .mkdn - Markdown document

🔧 System Requirements

• OS: Linux with GNOME desktop
• GNOME Sushi: File previewer (sudo apt install gnome-sushi)
• WebKit2GTK: Web rendering (sudo apt install libwebkit2gtk-4.1-dev)
• Python: 3.8+ with pip or uv

Dependencies Auto-Install

The installer automatically handles:

• Python Markdown - Core markdown processing
• Pygments - Syntax highlighting
• PyMdown Extensions - Enhanced features
• CommonMark - Spec compliance
• markdown-it-py - Modern parser
• python-markdown-math - Math support

🏗️ Architecture

┌─────────────┐    ┌──────────────┐    ┌─────────────┐    ┌──────────────┐
│ Markdown    │───▶│ Python       │───▶│ Styled      │───▶│ WebKit2      │
│ File        │    │ Converter    │    │ HTML        │    │ Preview      │
│ (.md)       │    │ (Multi-flavor)│    │ (CSS+JS)    │    │ (Sushi)      │
└─────────────┘    └──────────────┘    └─────────────┘    └──────────────┘

Components:

1. GNOME Sushi - File preview framework
2. Python Converter - Multi-flavor markdown processor
3. JavaScript Viewer - WebKit2GTK integration
4. MIME Integration - File type associations

🎨 Themes & Styling

Auto Theme Detection

• Automatically detects GNOME light/dark theme
• Switches styling and syntax highlighting accordingly
• Consistent with system appearance

Syntax Highlighting

• Light Theme: GitHub-style highlighting
• Dark Theme: Dark-optimized color schemes
• 40+ Languages: Powered by Pygments

⚡ Performance

• Rendering: < 100ms for typical documents
• Memory: ~10MB per preview
• CPU: Minimal impact, efficient caching
• Large Files: Handles 1MB+ documents smoothly

🔍 Feature Comparison

Feature	QLMarkdown (macOS)	GNOME Markdown QuickLook
Platform	macOS only	Linux/GNOME
Flavors	1 (Custom GFM-like)	8 markdown specifications
Themes	Built-in themes	System theme integration
Math	✅ MathJax	✅ MathJax
Diagrams	❌	✅ Mermaid
Syntax Highlighting	✅	✅ Pygments
Tables	✅	✅
Task Lists	✅	✅
Extensibility	Limited	Highly extensible
Performance	Native (Swift)	WebKit2GTK

🧪 Development

Local Setup

git clone https://github.com/noboomu/gnome-markdown-quicklook.git
cd gnome-markdown-quicklook
uv sync  # or pip install -e .

Testing

# Test converter directly
uv run python -m gnome_markdown_quicklook.converter tests/sample.md

# Test different flavors
uv run python -m gnome_markdown_quicklook.converter tests/sample.md --flavor gfm
uv run python -m gnome_markdown_quicklook.converter tests/sample.md --flavor commonmark

Adding Flavors

1. Implement render_<flavor>() method in converter.py
2. Add to FLAVORS dictionary
3. Update CLI choices and documentation
4. Test with various markdown documents

🛠️ Manual Installation

Click to expand manual installation steps

# 1. Install system dependencies
sudo apt install gnome-sushi libwebkit2gtk-4.1-dev python3-pip

# 2. Clone repository
git clone https://github.com/noboomu/gnome-markdown-quicklook.git
cd gnome-markdown-quicklook

# 3. Install Python dependencies
uv sync  # or pip install -r requirements.txt

# 4. Install converter
sudo cp src/gnome_markdown_quicklook/converter.py /usr/local/bin/sushi-markdown-converter
sudo chmod +x /usr/local/bin/sushi-markdown-converter

# 5. Install Sushi viewer
sudo cp src/sushi-viewers/markdown.js /usr/share/sushi/viewers/

# 6. Update MIME database
sudo cp mime/markdown.xml /usr/share/mime/packages/
sudo update-mime-database /usr/share/mime

# 7. Restart Sushi
pkill -f sushi

🐛 Troubleshooting

Preview Not Working

1. Check Sushi: which sushi and restart with pkill -f sushi
2. Check converter: sushi-markdown-converter --help
3. Check logs: journalctl --user -f | grep sushi

Dependency Issues

1. Python packages: uv sync or pip install markdown pygments
2. System packages: sudo apt install gnome-sushi libwebkit2gtk-4.1-dev
3. WebKit version: Try both webkit2gtk-4.0 and webkit2gtk-4.1

MIME Type Issues

1. Update database: update-mime-database ~/.local/share/mime
2. Check associations: file --mime-type document.md
3. Restart session: Log out and back in

🗑️ Uninstall

# Remove files
sudo rm -f /usr/local/bin/sushi-markdown-converter
sudo rm -f /usr/share/sushi/viewers/markdown.js
sudo rm -f /usr/share/mime/packages/markdown.xml

# Update MIME database
sudo update-mime-database /usr/share/mime

# Restart Sushi
pkill -f sushi

📄 License

This project is licensed under the GNU General Public License v2.0 - see the LICENSE file for details.

🙏 Acknowledgments

• QLMarkdown - Original macOS inspiration by Sbarex
• GNOME Sushi - File preview framework by GNOME Project
• Python Markdown - Core markdown processing
• PyMdown Extensions - Enhanced markdown features by facelessuser
• Pygments - Syntax highlighting by Georg Brandl

🌟 Contributing

Contributions welcome! Please read our Contributing Guide and submit pull requests to our GitHub repository.

---

Ready to use! 🎉

curl -fsSL https://raw.githubusercontent.com/noboomu/gnome-markdown-quicklook/main/install.sh | bash