Clearly for Linux

A Linux port of Clearly — a clean, native markdown editor originally written for macOS by Josh Pigford.

The original is Swift + AppKit + SwiftUI, which is macOS-only. This port is a from-scratch rewrite in Python with GTK4, libadwaita, GtkSourceView, and WebKitGTK. It tries to feel native on GNOME and stay close to the original's spirit: minimal UI, syntax-highlighted source, GFM preview, keyboard-driven.

Features

Carried over from macOS:

• Markdown syntax highlighting (via GtkSourceView)
• Instant GitHub Flavored Markdown preview — toggle with Ctrl+2
• Format shortcuts: Ctrl+B (bold), Ctrl+I (italic), Ctrl+K (link)
• Light & dark themes following the system
• Open .md, .markdown, .mdown, .mkd files
• Registered as a handler for markdown files in your file manager

Differences from macOS:

• No QuickLook (Linux desktops don't have that concept; we instead register as the default handler for .md files)
• No Sparkle auto-updater — updates come through apt like any Debian package
• No App Sandbox (runs as a normal Linux desktop app)

Install

sudo apt install ./clearly_1.0.0-linux1_all.deb

apt will pull in the GTK4, libadwaita, GtkSourceView 5, WebKitGTK 6, and Python markdown dependencies automatically.

Tested target: Debian 12+, Ubuntu 24.04+, Fedora 40+ (rebuild as RPM if needed). Anything older may not have WebKitGTK 6.0 and libadwaita 1 packaged.

Run

clearly                 # open with empty buffer
clearly README.md       # open a file

Or launch from your application menu — it appears as Clearly under Office / Text Editors.

Uninstall

sudo apt remove clearly

Build from source

You need dpkg-deb (in the dpkg package, present by default on Debian/Ubuntu).

./build-deb.sh

This produces clearly_1.0.0-linux1_all.deb in the project root.

Project layout

clearly-linux/
├── src/clearly.py                          # the application (single file)
├── debian/
│   ├── DEBIAN/
│   │   ├── control                         # package metadata
│   │   ├── postinst                        # refresh icon/mime/desktop caches
│   │   └── postrm
│   └── usr/
│       ├── bin/clearly                     # launcher shim
│       └── share/
│           ├── clearly/clearly.py          # installed app
│           ├── applications/...desktop     # menu entry
│           ├── icons/.../md.clearly.Clearly.svg
│           ├── mime/packages/...xml        # registers .md as text/markdown
│           └── metainfo/...metainfo.xml    # AppStream for software centers
└── build-deb.sh

License

MIT, same as the upstream macOS app.