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, so headings, tables, blockquotes, task lists, and alerts match what you would see on github.com. Fully offline.
| GitHub style | Theme-matched style |
|---|---|
Install katdown-git from the AUR with any helper:
yay -S katdown-git # or: paru -S katdown-gitThe package builds from the latest commit and pulls in every dependency. Then enable it: Settings, then Configure Kate, then Plugins, then check Katdown.
Download katdown-<version>-windows-x86_64.zip from the latest release, unzip it, close Kate, and run this in an elevated PowerShell:
powershell -ExecutionPolicy Bypass -File install.ps1It finds Kate on its own, or takes -KateDir "D:\Kate". -WhatIf shows what it would do, -Uninstall removes exactly what it installed.
Then enable it: Settings -> Configure Kate -> Plugins -> check Katdown.
The zip is about 90 MB and unpacks to roughly 220 MB, because Kate for Windows ships no Qt WebEngine, and the preview is a web view, so the runtime comes along with the plugin. Windows resolves a plugin's dependencies from the folder holding kate.exe, which is why those files install next to Kate rather than beside the plugin.
Two limits worth knowing before you download it:
- Kate has to come from the installer, Microsoft Store version is not supported.
- The build targets Kate's Qt 6.11.x.
install.ps1checks and refuses on a mismatch, because installing anyway produces a plugin that never loads and never says why.
git clone https://github.com/uwuclxdy/katdown.git
cd katdown
cmake -B build -S . -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=/usr
cmake --build buildSystem-wide install (loads in every Kate launch):
sudo cmake --install buildUser-local install (no root, but needs a re-login to take effect):
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.confEnable the plugin after installing: Settings -> Configure Kate -> Plugins -> 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.
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:
sudo pacman -S --needed base-devel cmake extra-cmake-modules \
ktexteditor qt6-webengine kcoreaddons ki18n kconfig kxmlgui ksyntaxhighlightingBuilding it yourself on Windows means KDE Craft with MSVC 2022, since the plugin has to match the ABI of Kate's own build and Kate ships no headers. .github/workflows/windows.yml is the working recipe.
Open any Markdown file in Kate:
kate path/to/notes.mdThen 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.
Closing the document's editor tab leaves the preview showing its last content, with (closed) in the tab title. Reopening the file re-attaches that same preview tab and it tracks again.
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.
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.
flowchart LR
A["Markdown document"] -->|"textChanged (debounced)"| B["PreviewWidget"]
B -->|"setHtml once"| C["QWebEngineView"]
B -->|"runJavaScript()"| D["preview.js"]
D --> E["markdown-it<br/>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. Small bundled plugins add task-list checkboxes and GitHub alerts, and leading YAML frontmatter is parsed with js-yaml into a metadata table.
- Code highlighting uses 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 is a faithful port of GitHub's highlighter and could replace highlight.js.
Build, then run Kate that loads the freshly built plugin without installing it:
cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j"$(nproc)"
QT_PLUGIN_PATH="$PWD/build/bin" kate some-file.mdTests render in a headless Chromium and keep their config out of your own Kate settings:
cmake -B build -S . -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBUILD_TESTING=ON
cmake --build build
ctest --test-dir build --output-on-failureSource layout:
src/plugin.*plugin entry point and config page registrationsrc/pluginview.*per-window action, toolbar/menu wiring, opening the tabsrc/previewwidget.*the web view, rendering, and theme derivationsrc/configpage.*the settings pagesrc/settings.*persisted settingsdata/bundled HTML, CSS, JS, and the qrc
- github-markdown-css by Sindre Sorhus
- markdown-it
- highlight.js
- js-yaml
GPL-3.0-or-later. See LICENSE.