{"id":29480466,"url":"https://github.com/noboomu/gnome-markdown-ql","last_synced_at":"2026-05-07T03:31:41.597Z","repository":{"id":304589118,"uuid":"1012682592","full_name":"noboomu/gnome-markdown-ql","owner":"noboomu","description":"Beautiful markdown previews for GNOME - Press Space in Nautilus to preview .md files with rich formatting, syntax highlighting, and multiple flavor support.","archived":false,"fork":false,"pushed_at":"2025-07-02T19:03:10.000Z","size":45,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-10T23:34:22.466Z","etag":null,"topics":["commonmark","gfm","gitlab","gnome","markdown","mmd","nautilus","pandoc","pymdown","quicklook"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/noboomu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-02T17:58:16.000Z","updated_at":"2025-07-02T19:02:23.000Z","dependencies_parsed_at":"2025-07-14T05:28:19.860Z","dependency_job_id":"74ef893f-5895-46e4-b098-84ca09b6cf1b","html_url":"https://github.com/noboomu/gnome-markdown-ql","commit_stats":null,"previous_names":["noboomu/gnome-markdown-ql"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/noboomu/gnome-markdown-ql","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noboomu%2Fgnome-markdown-ql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noboomu%2Fgnome-markdown-ql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noboomu%2Fgnome-markdown-ql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noboomu%2Fgnome-markdown-ql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/noboomu","download_url":"https://codeload.github.com/noboomu/gnome-markdown-ql/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noboomu%2Fgnome-markdown-ql/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282007156,"owners_count":26598240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-31T02:00:07.401Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["commonmark","gfm","gitlab","gnome","markdown","mmd","nautilus","pandoc","pymdown","quicklook"],"created_at":"2025-07-14T23:00:37.410Z","updated_at":"2025-10-31T15:03:56.622Z","avatar_url":"https://github.com/noboomu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GNOME Markdown QuickLook\n\n\u003e **Beautiful markdown previews for GNOME** - Press Space in Nautilus to preview .md files with rich formatting, syntax highlighting, and multiple flavor support.\n\n[![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![GNOME](https://img.shields.io/badge/GNOME-Sushi-orange.svg)](https://wiki.gnome.org/Apps/Sushi)\n\nSimilar to macOS [QLMarkdown](https://github.com/sbarex/QLMarkdown), this extension brings Quick Look-style markdown previews to GNOME Linux desktops.\n\n## ✨ Features\n\n- 🚀 **8 Markdown Flavors** - GitHub, CommonMark, Pandoc, GitLab, and more\n- 🎨 **Auto Theme Detection** - Seamlessly adapts to GNOME light/dark themes\n- 🔧 **Syntax Highlighting** - Powered by [Pygments](https://pygments.org/) with 40+ styles\n- 📊 **Rich Content** - Tables, task lists, math equations, Mermaid diagrams\n- ⚡ **Instant Preview** - Sub-second rendering with WebKit2GTK\n- 🌐 **Standards Compliant** - Full HTML5 + CSS3 + JavaScript support\n\n## 🚀 Quick Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/noboomu/gnome-markdown-quicklook/main/install.sh | bash\n```\n\n**That's it!** The installer will handle dependencies, setup, and configuration automatically.\n\n## 📋 Supported Markdown Flavors\n\n| Flavor | Specification | Key Features |\n|--------|---------------|--------------|\n| **[GFM](https://github.github.com/gfm/)** | GitHub Flavored Markdown | Tables, task lists, strikethrough, @mentions |\n| **[CommonMark](https://spec.commonmark.org/0.31.2/)** | CommonMark 0.31.2 | Standards-compliant parsing |\n| **[PyMdown](https://facelessuser.github.io/pymdown-extensions/)** | Enhanced GitHub-like | Emoji, keyboard keys, advanced highlighting |\n| **[Pandoc](https://pandoc.org/MANUAL.html#pandocs-markdown)** | Pandoc Markdown | Extensive extensions, citations, metadata |\n| **[Extra](https://python-markdown.github.io/extensions/extra/)** | PHP Markdown Extra | Definition lists, abbreviations, footnotes |\n| **[GitLab](https://docs.gitlab.com/ee/user/markdown.html)** | GitLab Flavored Markdown | GFM + GitLab-specific references (!123, etc.) |\n| **[MMD](https://fletcher.github.io/MultiMarkdown-6/)** | MultiMarkdown v6 | Metadata, citations, advanced tables |\n| **Standard** | [Python Markdown](https://python-markdown.github.io/) | Basic markdown features |\n\n## 🎯 Usage\n\n### Basic Usage\n1. **Open Nautilus** (GNOME Files)\n2. **Select any `.md` file**\n3. **Press `Space`** → Preview opens instantly!\n4. **Press `Escape`** to close\n\n### Advanced Usage\n\n**Test different flavors:**\n```bash\nsushi-markdown-converter document.md --flavor gfm\nsushi-markdown-converter document.md --flavor commonmark\nsushi-markdown-converter document.md --flavor pandoc\n```\n\n**Export to HTML:**\n```bash\nsushi-markdown-converter document.md --output preview.html --flavor gfm\n```\n\n**List all flavors:**\n```bash\nsushi-markdown-converter --help\n```\n\n## 📝 Supported File Types\n\n- `.md` - Standard Markdown\n- `.markdown` - Markdown document\n- `.mdown` - Markdown document\n- `.mkd` - Markdown document\n- `.mkdn` - Markdown document\n\n## 🔧 System Requirements\n\n- **OS**: Linux with GNOME desktop\n- **GNOME Sushi**: File previewer (`sudo apt install gnome-sushi`)\n- **WebKit2GTK**: Web rendering (`sudo apt install libwebkit2gtk-4.1-dev`)\n- **Python**: 3.8+ with pip or [uv](https://github.com/astral-sh/uv)\n\n### Dependencies Auto-Install\n\nThe installer automatically handles:\n- [Python Markdown](https://python-markdown.github.io/) - Core markdown processing\n- [Pygments](https://pygments.org/) - Syntax highlighting\n- [PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/) - Enhanced features\n- [CommonMark](https://github.com/readthedocs/commonmark.py) - Spec compliance\n- [markdown-it-py](https://github.com/executablebooks/markdown-it-py) - Modern parser\n- [python-markdown-math](https://github.com/mitya57/python-markdown-math) - Math support\n\n## 🏗️ Architecture\n\n```\n┌─────────────┐    ┌──────────────┐    ┌─────────────┐    ┌──────────────┐\n│ Markdown    │───▶│ Python       │───▶│ Styled      │───▶│ WebKit2      │\n│ File        │    │ Converter    │    │ HTML        │    │ Preview      │\n│ (.md)       │    │ (Multi-flavor)│    │ (CSS+JS)    │    │ (Sushi)      │\n└─────────────┘    └──────────────┘    └─────────────┘    └──────────────┘\n```\n\n**Components:**\n1. **[GNOME Sushi](https://gitlab.gnome.org/GNOME/sushi)** - File preview framework\n2. **Python Converter** - Multi-flavor markdown processor\n3. **JavaScript Viewer** - WebKit2GTK integration\n4. **MIME Integration** - File type associations\n\n## 🎨 Themes \u0026 Styling\n\n### Auto Theme Detection\n- Automatically detects GNOME light/dark theme\n- Switches styling and syntax highlighting accordingly\n- Consistent with system appearance\n\n### Syntax Highlighting\n- **Light Theme**: GitHub-style highlighting\n- **Dark Theme**: Dark-optimized color schemes\n- **40+ Languages**: Powered by Pygments\n\n## ⚡ Performance\n\n- **Rendering**: \u003c 100ms for typical documents\n- **Memory**: ~10MB per preview\n- **CPU**: Minimal impact, efficient caching\n- **Large Files**: Handles 1MB+ documents smoothly\n\n## 🔍 Feature Comparison\n\n| Feature | [QLMarkdown (macOS)](https://github.com/sbarex/QLMarkdown) | GNOME Markdown QuickLook |\n|---------|-------------------|---------------------------|\n| **Platform** | macOS only | Linux/GNOME |\n| **Flavors** | 1 (Custom GFM-like) | 8 markdown specifications |\n| **Themes** | Built-in themes | System theme integration |\n| **Math** | ✅ [MathJax](https://www.mathjax.org/) | ✅ [MathJax](https://www.mathjax.org/) |\n| **Diagrams** | ❌ | ✅ [Mermaid](https://mermaid.js.org/) |\n| **Syntax Highlighting** | ✅ | ✅ [Pygments](https://pygments.org/) |\n| **Tables** | ✅ | ✅ |\n| **Task Lists** | ✅ | ✅ |\n| **Extensibility** | Limited | Highly extensible |\n| **Performance** | Native (Swift) | WebKit2GTK |\n\n## 🧪 Development\n\n### Local Setup\n\n```bash\ngit clone https://github.com/noboomu/gnome-markdown-quicklook.git\ncd gnome-markdown-quicklook\nuv sync  # or pip install -e .\n```\n\n### Testing\n\n```bash\n# Test converter directly\nuv run python -m gnome_markdown_quicklook.converter tests/sample.md\n\n# Test different flavors\nuv run python -m gnome_markdown_quicklook.converter tests/sample.md --flavor gfm\nuv run python -m gnome_markdown_quicklook.converter tests/sample.md --flavor commonmark\n```\n\n### Adding Flavors\n\n1. Implement `render_\u003cflavor\u003e()` method in `converter.py`\n2. Add to `FLAVORS` dictionary\n3. Update CLI choices and documentation\n4. Test with various markdown documents\n\n## 🛠️ Manual Installation\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to expand manual installation steps\u003c/summary\u003e\n\n```bash\n# 1. Install system dependencies\nsudo apt install gnome-sushi libwebkit2gtk-4.1-dev python3-pip\n\n# 2. Clone repository\ngit clone https://github.com/noboomu/gnome-markdown-quicklook.git\ncd gnome-markdown-quicklook\n\n# 3. Install Python dependencies\nuv sync  # or pip install -r requirements.txt\n\n# 4. Install converter\nsudo cp src/gnome_markdown_quicklook/converter.py /usr/local/bin/sushi-markdown-converter\nsudo chmod +x /usr/local/bin/sushi-markdown-converter\n\n# 5. Install Sushi viewer\nsudo cp src/sushi-viewers/markdown.js /usr/share/sushi/viewers/\n\n# 6. Update MIME database\nsudo cp mime/markdown.xml /usr/share/mime/packages/\nsudo update-mime-database /usr/share/mime\n\n# 7. Restart Sushi\npkill -f sushi\n```\n\n\u003c/details\u003e\n\n## 🐛 Troubleshooting\n\n### Preview Not Working\n1. **Check Sushi**: `which sushi` and restart with `pkill -f sushi`\n2. **Check converter**: `sushi-markdown-converter --help`\n3. **Check logs**: `journalctl --user -f | grep sushi`\n\n### Dependency Issues\n1. **Python packages**: `uv sync` or `pip install markdown pygments`\n2. **System packages**: `sudo apt install gnome-sushi libwebkit2gtk-4.1-dev`\n3. **WebKit version**: Try both `webkit2gtk-4.0` and `webkit2gtk-4.1`\n\n### MIME Type Issues\n1. **Update database**: `update-mime-database ~/.local/share/mime`\n2. **Check associations**: `file --mime-type document.md`\n3. **Restart session**: Log out and back in\n\n## 🗑️ Uninstall\n\n```bash\n# Remove files\nsudo rm -f /usr/local/bin/sushi-markdown-converter\nsudo rm -f /usr/share/sushi/viewers/markdown.js\nsudo rm -f /usr/share/mime/packages/markdown.xml\n\n# Update MIME database\nsudo update-mime-database /usr/share/mime\n\n# Restart Sushi\npkill -f sushi\n```\n\n## 📄 License\n\nThis project is licensed under the [GNU General Public License v2.0](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html) - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **[QLMarkdown](https://github.com/sbarex/QLMarkdown)** - Original macOS inspiration by [Sbarex](https://github.com/sbarex)\n- **[GNOME Sushi](https://gitlab.gnome.org/GNOME/sushi)** - File preview framework by GNOME Project\n- **[Python Markdown](https://python-markdown.github.io/)** - Core markdown processing\n- **[PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/)** - Enhanced markdown features by [facelessuser](https://github.com/facelessuser)\n- **[Pygments](https://pygments.org/)** - Syntax highlighting by [Georg Brandl](https://github.com/birkenfeld)\n\n## 🌟 Contributing\n\nContributions welcome! Please read our [Contributing Guide](CONTRIBUTING.md) and submit pull requests to our [GitHub repository](https://github.com/noboomu/gnome-markdown-quicklook).\n\n---\n\n**Ready to use!** 🎉\n```bash\ncurl -fsSL https://raw.githubusercontent.com/noboomu/gnome-markdown-quicklook/main/install.sh | bash\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoboomu%2Fgnome-markdown-ql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnoboomu%2Fgnome-markdown-ql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoboomu%2Fgnome-markdown-ql/lists"}