Katemark is a plugin for Kate, the KDE text editor. It shows the Markdown document you are editing as GitHub would, in a panel beside the editor that follows what you type and scrolls with it. The renderer, the styles and the fonts ship with the plugin, so it works offline.
This is a fork of Katdown by uwuclxdy, which shows the preview in a tab of its own.
| CodiMD, Obsidian and MkDocs blocks | The same document with "GitHub only" | The colors of the editor theme |
|---|---|---|
 |
 |
 |
| Feature | What it does | From |
|---|---|---|
| GitHub rendering | Headings, tables, task lists, alerts and highlighted code look as they do on github.com | original |
| Two styles | GitHub's colors (light or dark) or the colors of your Kate theme | original |
| Front matter | Shows a YAML header as a table | original |
| Offline | No network request, unless you allow pictures from the web | original |
| Side panel | Docks the preview beside the editor and re-renders it as you type | fork |
| Scroll sync | Scrolling the editor or the preview brings the other to the same place | fork |
| More syntax | markdown-it extensions, CodiMD, Obsidian and MkDocs | fork |
| GitHub only | A check box above the preview leaves out what GitHub would not render | fork |
| Math | LaTeX formulas, rendered by KaTeX | fork |
| Diagrams | Mermaid | fork |
| Export | A PDF, its pages numbered when it has more than one (Qt 6.10 or later), or a single self-contained HTML file | fork |
| Editing actions | Bold, italic, strikethrough, heading level, paste as link, table formatting | fork |
| Image paste | Saves a picture from the clipboard beside the document and links it | fork |
| Languages | 44 interface languages | fork |
| Your system | What to do |
|---|---|
| KDE neon | Install the package katemark_<version>_neon_amd64.deb |
| Kubuntu 26.04 | Install the package katemark_<version>_ubuntu26.04_amd64.deb |
| Windows | Install the zip katemark-<version>-windows-x86_64.zip |
| Arch Linux | Install from the AUR katemark-git |
| openSUSE Tumbleweed, Leap 16.0 | Install from KDE:Extra katemark |
| Another Debian or Ubuntu release | Build the package with build.sh |
| Any other Linux | Build from source |
| Kubuntu 24.04 | Not possible: its Kate still uses KDE Frameworks 5 |
Kate has to be a KDE Frameworks 6 build, with Qt 6.5 or later. If you installed Katemark from source before, uninstall it first.
Download the file for your system from the latest release, then:
sudo apt install ./katemark_*_amd64.debsudo apt remove katemark uninstalls it. Each package installs only on the
system named in its file, because KDE neon and Ubuntu name their Qt and KDE
Frameworks packages differently.
Download katemark-<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.
The zip is about 90 MB and unpacks to 220 MB: Kate for Windows ships no Qt
WebEngine, so the runtime comes with the plugin. It installs next to
kate.exe, where Windows looks for the libraries a plugin needs.
- Kate has to come from the installer. The Microsoft Store version is not supported.
- The build targets the Qt 6.11 of Kate's own Windows build.
install.ps1refuses to install on another version. - A workflow builds the zip. One user runs it on Windows 11, where the preview and both exports work: please report what you see on yours.
Install katemark-git
from the AUR:
git clone https://aur.archlinux.org/katemark-git.git
cd katemark-git
makepkg -sisudo pacman -R katemark-git uninstalls it.
Katemark is in the KDE:Extra repository. On Tumbleweed:
sudo zypper addrepo https://download.opensuse.org/repositories/KDE:/Extra/openSUSE_Tumbleweed/KDE:Extra.repo
sudo zypper refresh
sudo zypper install katemarkOn Leap 16.0, write openSUSE_Leap_16.0 instead of openSUSE_Tumbleweed.
sudo zypper remove katemark uninstalls it.
- Enable the plugin: Settings > Configure Kate > Plugins, check Katemark, click OK.
- Open a Markdown document: a file ending in
.md,.markdownor.mkd. A document whose highlighting mode is Markdown counts too. - Press Ctrl+Shift+M. The preview opens on the right of the editor.
The documents in examples/ show what the preview renders:
github.md, codimd.md, obsidian.md, mkdocs.md and teaching.md.
| To | Do this |
|---|---|
| Show or hide the preview | Ctrl+Shift+M, the Preview button of the main toolbar or Tools > Preview |
| See the document as GitHub will show it | Check GitHub only above the preview |
| Export what the preview shows | The PDF and HTML buttons above the preview, or Tools > Export Preview as PDF and Tools > Export Preview as HTML |
| Follow a link | Click it: a local file opens in Kate, a web address in your browser, a link to a heading scrolls the preview. Any other link, such as zotero: or obsidian:, asks before it starts another program. Point at a link to see where it goes |
| Zoom the preview, diagrams included | Ctrl + mouse wheel over it; Ctrl+0 or Reset Zoom in its context menu puts it back to 100% |
| Paste a picture | Copy an image, then paste in the editor |
- The preview follows the active Markdown document. It keeps its last content when you close that document or switch to one that is not Markdown, and stays open until you hide it.
- Both exports use GitHub's light colors, whatever the preview shows. The HTML file embeds the pictures of the document's folder and holds no script.
- Raw HTML in a document is shown, but its scripts, frames and forms are not run.
- Katemark saves a pasted picture as
image-<date>-<time>.pngin the folder of the document, so save the document first. It inserts the linkand leaves the cursor between the brackets. It does so when the clipboard holds an image and no text. - If the toolbar button is missing, show the toolbar: Settings > Toolbars Shown > Main Toolbar.
| Family | Syntax | Also understood by |
|---|---|---|
| GitHub | Tables, task lists (- [ ]), alerts (> [!NOTE]), ~~strikethrough~~, bare links, highlighted code blocks, YAML front matter |
Alerts: Obsidian, VitePress, GitLab |
| markdown-it plugins | ==mark== (mark), ++ins++ (ins), H~2~O (sub), 19^th^ (sup), footnotes (footnote), emoji by name such as :warning: (emoji) |
|
| CodiMD | :::success, :::info, :::warning and :::danger alert areas, also under the Docusaurus names note, tip and caution; :::spoiler; [TOC] |
Alert areas: HackMD, Docusaurus (:::note[Title]), VitePress (::: info) |
| Obsidian | Callouts (> [!faq]- Title) with every type and alias, custom titles and folding; wiki links ([[Note]], [[Note|label]], [[Note#Heading]]); image embeds with a size (![[image.png|300]]); %%comments%% |
|
| MkDocs | !!! note "Title" admonitions with an indented body, ??? note for a folded one, ???+ note for one that starts open |
Python-Markdown's admonition extension, Material for MkDocs; ??? comes from pymdownx.details |
| Teaching | Callouts definition, theorem, lemma, proposition, corollary, proof, exercise, solution, remark... and their short names (def, thm, pf...), plus method; also under their French names, with or without accents (théorème, propriété, démonstration, correction...); a picture's size, {width=50%} |
Callouts: the Obsidian plugin Academic Notes; sizes: Pandoc |
| Math | $...$, $$...$$, \(...\) and \[...\], rendered by KaTeX |
|
| Diagrams | Mermaid in ```mermaid blocks |
- Obsidian links resolve against the folder of the document, not across a vault.
- With GitHub only checked, the preview reads the GitHub row alone, plus
what GitHub renders too: footnotes, emoji, math and Mermaid. It also
strikes
~text~between single tildes, as GitHub does. The result is close to GitHub's without being identical: the code highlighter and the math engine differ. - markdown-it-container
parses the
:::blocks. - Math accepts what MathJax does where KaTeX is stricter:
\require{...}, inline math over several lines,\newcommandon a command that exists. - A macro defined in a formula serves the formulas after it, and
$$...$$ (1)numbers an equation.
Tools > Markdown holds these actions. They work in Markdown documents only.
| Action | Shortcut | What it does |
|---|---|---|
| Bold | Ctrl+Alt+B | Wraps the selection or the word under the cursor in **, and takes the marker off when it is already there |
| Italic | Ctrl+Alt+E | The same with * |
| Strikethrough | Ctrl+Alt+S | The same with ~~ |
| Increase Heading Level | Ctrl+Alt+= | Adds one heading level to the selected lines or to the line of the cursor |
| Decrease Heading Level | Ctrl+Alt+- | Removes one |
| Paste as Link | Ctrl+Shift+V | Turns the selection into a link to the address in the clipboard |
| Format Table | Ctrl+Alt+F | Aligns the columns of the table under the cursor |
Ctrl+B and Ctrl+I are Kate's bookmark and indentation shortcuts. To change any shortcut: Settings > Configure Keyboard Shortcuts, search for Katemark.
On Windows the Ctrl+Alt shortcuts are not set: Windows
sends AltGr as Ctrl+Alt, so they would take
the euro sign or the | of a table. Give the actions a key of your own in
the same dialog.
Settings > Configure Kate, then the Katemark page. It appears once you enable the plugin.
| Setting | Values | What it does |
|---|---|---|
| Style | GitHub, Match editor / system theme | Match recolors the GitHub layout from your Kate theme |
| GitHub variant | Follow system (auto), Light, Dark | Applies in GitHub style only |
| Load media previews from remote URLs | Off (default), On | When off, the preview fetches nothing and says where a picture from the web was left out. Pictures stored beside the document load in both cases |
| Math macros | \newcommand lines |
Macros available in the formulas of every document |
| Check for updates | Button | Compares the installed version with the latest release of this repository. Katemark contacts GitHub only when you click |
| Problem | Cause and remedy |
|---|---|
| Katemark is not in the list of plugins | Check in Help > About Kate that Kate uses KDE Frameworks 6. After a user-local install, log out and back in |
| The preview stays empty or shows another document | The active document is not Markdown: see First steps |
apt reports unmet dependencies |
The package is for another system: see Install |
| A picture from the web is missing | Enable "Load media previews from remote URLs" in the settings |
| Ctrl+B does not make bold | See Editing shortcuts |
Kate's Output panel says Failed to find server binary 'marksman' |
That message comes from Kate's LSP Client plugin, not from Katemark: it looks for a Markdown language server. Ignore it, install marksman or turn that plugin off in Settings > Configure Kate > Plugins |
The console warns about Qt::AA_ShareOpenGLContexts |
Harmless: the plugin starts Qt WebEngine once Kate is running |
Install the build dependencies:
# KDE neon
sudo apt install g++ cmake extra-cmake-modules gettext dpkg-dev qt6-webengine-dev \
kf6-ktexteditor-dev kf6-kcoreaddons-dev kf6-ki18n-dev kf6-kconfig-dev \
kf6-kxmlgui-dev kf6-kwidgetsaddons-dev kf6-syntax-highlighting-dev
# Ubuntu 26.04
sudo apt install g++ cmake extra-cmake-modules gettext dpkg-dev qt6-webengine-dev \
libkf6texteditor-dev libkf6coreaddons-dev libkf6i18n-dev libkf6config-dev \
libkf6xmlgui-dev libkf6widgetsaddons-dev libkf6syntaxhighlighting-dev
# Arch Linux
sudo pacman -S --needed base-devel cmake extra-cmake-modules \
ktexteditor qt6-webengine kcoreaddons ki18n kconfig kxmlgui kwidgetsaddons \
syntax-highlightingGet the sources:
git clone https://github.com/obook/katemark.git
cd katemarkThen choose one of three ways to install.
On Debian, Ubuntu and KDE neon. build.sh configures, compiles, runs the
tests and makes the package:
./build.sh
sudo apt install ./build/katemark_*.debOn any distribution:
cmake -B build -S . -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=/usr
cmake --build build
sudo cmake --install buildWithout root. Configure and build as above, then:
cmake --install build --prefix ~/.local
mkdir -p ~/.config/environment.d
plugins=$(grep -om1 '.*/plugins' build/install_manifest.txt)
printf 'QT_PLUGIN_PATH=%s\n' "$plugins" > ~/.config/environment.d/katemark.confLog out and back in for Kate to find the plugin.
From the source folder, with its build folder still there:
sudo cmake --build build --target uninstall # system-wide install
cmake --build build --target uninstall # user-local installAfter a user-local install, also delete
~/.config/environment.d/katemark.conf.
.github/CONTRIBUTING.md covers running the
plugin without installing it, the tests, the translations, the layout of the
sources and how the preview works.
No native speaker has reviewed the translations, French apart: corrections are welcome.
Author of this fork: Olivier Booklage (olivier.booklage@ac-bordeaux.fr).
Original project: Katdown by uwuclxdy (GPL-3.0-or-later).
Matija Šuklje maintains the Arch Linux package.
Olivier Belleux (Wolfheri) made the openSUSE package and Christophe Marin
added it to KDE:Extra.
Bundled libraries:
The license texts are in THIRD-PARTY-NOTICES.md.
This fork reimplements the Obsidian syntax and three parts of CodiMD: its alert areas, its spoiler and its table of contents. No code comes from either project. The other text extensions come from the markdown-it plugins listed above. The colors of the CodiMD alert areas are those of Bootstrap 3 alerts (MIT).
GPL-3.0-or-later. See LICENSE.