Native GTK Markdown Reader

A lightweight, serverless, and native desktop Markdown reader and editor for Linux. It embeds a WebKit2 view to render beautiful Markdown documents, checklists, tables, syntax-highlighted code blocks, LaTeX math equations, and Mermaid diagrams offline without launching a local server or opening network ports.

---

Features

• Native Linux Window: Built on PyGObject (GTK 3) and uses system-wide WebKit2GTK for high performance.
• Dynamic Sidebar:
  • File Tree: Auto-scans and lists all .md and .markdown files in the active directory.
  • Auto Outline (TOC): Auto-extracts headers (H1-H6) and links them for instant jump scrolling.
  • Scroll Spy: Automatically highlights the outline section corresponding to the viewport scroll position.
  • Filter Search: Instantly filters files and outline headings by keywords.
• Reader, Editor & Split Modes:
  • Reader Mode: Elegant glassmorphic document viewer with distraction-free reading.
  • Editor Mode: Fast text editor with synchronized line numbers.
  • Split Mode: Side-by-side editor and viewer with synced scroll positions and real-time live preview rendering.
• Interactive Checklist Toggling: Click checkbox list items (- [ ]) directly in the viewer pane to immediately toggle and write their state back to the markdown file on disk.
• Mermaid.js Diagrams: Renders ```mermaid blocks into interactive, scalable charts and diagrams.
• Drag & Drop Opening: Drag any .md file from your desktop file manager and drop it onto the reader window to open it and refresh the directory workspace tree.
• Keyboard Shortcuts Helper: Press ? or click the help button to open a sleek overlay listing application keybindings.
• Formatting Support:
  • Full GitHub Flavored Markdown (GFM).
  • Code syntax highlighting via Highlight.js.
  • Math equation rendering via KaTeX (inline $ and block $$).
• Live Reload Watcher: Background folder monitor automatically refreshes the viewport if the markdown file is edited externally in tools like Vim, VS Code, or Emacs.
• Print & PDF Export: Native integration to export pages to paper or PDF files using standard Linux print dialog layouts.

---

Installation

1. Clone or download the repository into your preferred folder (e.g. ~/mdFile).
2. Run the included integration installer script:

   ./install.sh

3. This creates a symlink in ~/.local/bin/mdreader and adds a Desktop Entry (mdreader.desktop) to your applications launcher.

Make sure ~/.local/bin is in your environment $PATH variable by adding this line to your shell configuration (~/.bashrc or ~/.zshrc):

export PATH="$HOME/.local/bin:$PATH"

---

Usage

1. From the Desktop GUI

• Open your system app launcher and search for Markdown Reader.
• Right-click any .md file in your system file manager, select Open With, and choose Markdown Reader to associate the extension.

2. From the Terminal

Start in the current working directory:

mdreader

Open a specific markdown file:

mdreader sample.md

Start browsing in a specific directory:

mdreader ~/Documents/project-notes/

3. Drag & Drop

• Drag any .md file from your desktop file manager and drop it onto the reader window to open it.

---

Keyboard Shortcuts

Shortcut	Description
Ctrl+E	Cycle layout modes: Read → Split → Edit
Ctrl+B	Toggle sidebar layout visibility
Ctrl+F	Find text in current document
Ctrl+S	Save edited changes to file
F11	Toggle Fullscreen view
Ctrl+Q	Quit application
? or F1	Open / close Keyboard Shortcuts help modal

---

System Requirements

The application runs using native libraries installed by default on modern GNOME-based Linux distributions (Ubuntu, Fedora, Debian, Mint).

• Python (version 3.8+)
• PyGObject (python3-gi)
• WebKit2GTK (libwebkit2gtk-4.1)

If you are on a custom minimal Linux installation, you can install the necessary packages using:

sudo apt install python3-gi gir1.2-gtk-3.0 gir1.2-webkit2-4.1