https://github.com/uwuclxdy/katdown
GitHub-styled Markdown preview plugin for Kate (KTextEditor/KF6)
https://github.com/uwuclxdy/katdown
kate-plugin kde kf6 ktexteditor markdown-preview vibecoded
Last synced: 17 days ago
JSON representation
GitHub-styled Markdown preview plugin for Kate (KTextEditor/KF6)
- Host: GitHub
- URL: https://github.com/uwuclxdy/katdown
- Owner: uwuclxdy
- License: gpl-3.0
- Created: 2026-05-28T08:49:16.000Z (21 days ago)
- Default Branch: mommy
- Last Pushed: 2026-05-28T15:54:15.000Z (21 days ago)
- Last Synced: 2026-05-28T17:13:34.077Z (21 days ago)
- Topics: kate-plugin, kde, kf6, ktexteditor, markdown-preview, vibecoded
- Language: C++
- Homepage:
- Size: 349 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Katdown - Kate Markdown Preview
[](LICENSE)
KDE Kate plugin for viewing GitHub-styled preview of Markdown files with live updates. Supports both GitHub's own colors and also your active editor/system theme.
> [!NOTE]
> It's vibecoded. (it works better than anything else tho)
## Screenshots
| GitHub style | Theme-matched style |
| :----------: | :-----------------: |
|  |  |
## Installation
### Arch Linux (recommended)
Install [`katdown-git`](https://aur.archlinux.org/packages/katdown-git) from the AUR with any helper:
```bash
yay -S katdown-git # or: paru -S katdown-git
```
The package builds from the latest commit and pulls in every dependency. Then enable it: Settings, then Configure Kate, then Plugins, then check Katdown.
### Build from source
```bash
git clone https://github.com/uwuclxdy/katdown.git
cd katdown
cmake -B build -S . -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=/usr
cmake --build build
```
Then pick install type:
**System** (loads in every Kate launch):
```bash
sudo cmake --install build
```
**User-local** (no root, but needs a re-login to take effect). The second command adds `~/.local/lib/qt6/plugins` to Qt's plugin search path so Kate finds it:
```bash
cmake --install build --prefix ~/.local
mkdir -p ~/.config/environment.d
printf 'QT_PLUGIN_PATH=%s/.local/lib/qt6/plugins\n' "$HOME" \
> ~/.config/environment.d/katdown.conf
```
After installing, enable it: Settings, then Configure Kate, then Plugins, then check Katdown.
> [!NOTE]
> Qt WebEngine is initialized from inside Kate. On some setups you may see a console warning about `Qt::AA_ShareOpenGLContexts`. It is harmless in practice.
## Requirements
The AUR package resolves these for you. You only need them to build from source.
- Kate / KTextEditor 6 (KF6)
- Qt 6 with WebEngine
On Arch:
```bash
sudo pacman -S --needed base-devel cmake extra-cmake-modules \
ktexteditor qt6-webengine kcoreaddons ki18n kconfig kxmlgui ksyntaxhighlighting
```
## Why this exists
Kate's built-in preview uses a plain Qt renderer that looks nothing like GitHub. The other option, `kmarkdownwebview`, was abandoned in 2020 and never ported to KF6. This plugin fills that gap: it renders with the actual [github-markdown-css](https://github.com/sindresorhus/github-markdown-css), so headings, tables, blockquotes, task lists, and alerts match what you would see on github.com. It also runs fully offline (unless you opt in).
## Features
- Preview opens in a real tab next to your document, not a cramped side panel
- Live updates while you type (debounced)
- GitHub light and dark, picked automatically from your system, or forced
- A theme-matched mode that recolors the same GitHub layout from your active Kate editor theme, so code blocks use the exact same syntax colors as the editor
- GitHub Flavored Markdown: tables, strikethrough, autolinks, and `- [ ]` task list checkboxes
- GitHub alerts (`> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]`) with the matching octicons and colors
- YAML frontmatter rendered as a GitHub-style metadata table at the top of the file
- Toolbar button and a configurable Ctrl+Shift+M shortcut
- Everything is bundled — the renderer and all its assets are fully offline. Remote image loading is off by default and can be enabled in settings.
## Usage
Open any Markdown file in Kate:
```bash
kate path/to/notes.md
```
Then trigger the preview in one of three ways:
- press Ctrl+Shift+M, or
- click the Katdown button in the main toolbar (Settings, then Toolbars Shown, then Main Toolbar if it is hidden), or
- use Tools, then Katdown.
The button is greyed out unless the active tab is a Markdown document. The preview tab tracks the document and re-renders as you edit. Triggering it again focuses the existing tab instead of opening a second one.
## Configuration
Settings -> Configure Kate -> (Plugins -> enable `Katdown`) -> Katdown.
| Setting | Options | What it does |
|---------|---------|--------------|
| Style | GitHub / Match editor or system theme | GitHub uses GitHub's palette. Match recolors the same layout from your active editor theme. |
| GitHub variant | Auto / Light / Dark | Which GitHub palette to use. Auto follows whether your system is light or dark. Only applies in GitHub style. |
| Load media previews from remote URLs | On / Off (default) | When on, images referencing `http(s)` URLs are fetched and rendered. When off (the default), the preview loads no remote resources and works fully offline. Images with paths relative to the document always load regardless of this setting. |
Change the shortcut under Settings, then Configure Keyboard Shortcuts, search for Katdown.
## How it works
The preview is a `QWebEngineView` added to Kate's tab area through `KTextEditor::MainWindow::addWidget`. The page is one self-contained HTML document with the assets inlined, so nothing loads over the network.
```mermaid
flowchart LR
A["Markdown document"] -->|"textChanged (debounced)"| B["PreviewWidget"]
B -->|"setHtml once"| C["QWebEngineView"]
B -->|"runJavaScript()"| D["preview.js"]
D --> E["markdown-it
tasks · alerts · frontmatter"]
D --> F["highlight.js"]
G["Editor theme / GitHub palette"] -->|"CSS variables"| C
```
- Layout and typography come from `github-markdown-css`. The built-in color values are stripped out so the plugin can drive them from CSS custom properties.
- Markdown is parsed by [markdown-it](https://github.com/markdown-it/markdown-it). Small bundled plugins add task-list checkboxes and GitHub alerts, and leading YAML frontmatter is parsed with [js-yaml](https://github.com/nodeca/js-yaml) into a metadata table.
- Code highlighting uses [highlight.js](https://github.com/highlightjs/highlight.js). In GitHub style it uses the github/github-dark themes. In theme-matched style the token colors are generated at runtime from `KTextEditor::View::theme()`, so they line up with the editor.
Code highlighting is close to GitHub but not byte-identical, because GitHub uses its own server-side highlighter rather than highlight.js. If needed, [starry-night](https://github.com/wooorm/starry-night) is a faithful port of GitHub's highlighter and could replace highlight.js.
## Development
Build, then run Kate that loads the freshly built plugin without installing it:
```bash
cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j"$(nproc)"
QT_PLUGIN_PATH="$PWD/build/bin" kate some-file.md
```
Source layout:
- `src/plugin.*` plugin entry point and config page registration
- `src/pluginview.*` per-window action, toolbar/menu wiring, opening the tab
- `src/previewwidget.*` the web view, rendering, and theme derivation
- `src/configpage.*` the settings page
- `src/settings.*` persisted settings
- `data/` bundled HTML, CSS, JS, and the qrc
## Credits
- [github-markdown-css](https://github.com/sindresorhus/github-markdown-css) by Sindre Sorhus
- [markdown-it](https://github.com/markdown-it/markdown-it)
- [highlight.js](https://github.com/highlightjs/highlight.js)
- [js-yaml](https://github.com/nodeca/js-yaml)
## License
GPL-3.0-or-later. See [LICENSE](LICENSE).