TypstPart

TypstPart is a KDE KPart providing a live Typst preview inside Kate.

The preview is powered by Tinymist and is embedded using Qt WebEngine. TypstPart keeps the preview session alive while editing and supports navigation between the Kate editor and the rendered preview.

Note

This project is provided as-is under the MIT License. There is no guarantee of support, maintenance, or compatibility with future Kate, KDE Frameworks, Qt, or Tinymist releases. Further, the macOS instructions below describe a development setup rather than a packaged installation.

Features

• Live Typst preview inside Kate
• Tinymist-based rendering
• Preview updates while editing
• Relative imports and assets resolved from the source document directory
• Editor-to-preview navigation
• Preview-to-editor navigation
• Typst compilation errors displayed in the preview pane

Currently built on OSX, Linux is pending, but should be rather similar if not easier.

Instructions below where constructed by letting AI loose on my dev note ramblings. Good luck!

Requirements

The project currently requires:

• macOS

• Python 3

• Xcode Command Line Tools

• CMake

• a C++17 compiler

• KDE Craft

• Qt 6

  • Widgets
  • WebEngineWidgets
  • WebSockets

• KDE Frameworks 6

  • CoreAddons
  • Parts
  • TextEditor

• Kate

• Tinymist

The setup below uses KDE Craft to provide the Qt and KDE Frameworks development environment.

1. Check the macOS development tools

Check that Python 3 is available:

python3 --version

Check that the Xcode Command Line Tools are installed:

xcode-select -p

If they are not installed:

xcode-select --install

2. Install KDE Craft

Install Craft into your home directory:

cd "$HOME"

curl https://raw.githubusercontent.com/KDE/craft/master/setup/CraftBootstrap.py \
    -o CraftBootstrap.py

python3 CraftBootstrap.py --prefix "$HOME/CraftRoot"

Enter the Craft environment:

source "$HOME/CraftRoot/craft/craftenv.sh"

This must be done in every new shell used to build TypstPart.

Check that Craft is working:

craft --version
craft --search kparts

KDE Frameworks version

The development environment used for this project pins KDE Frameworks to version 6.28.0:

craft --set version=6.28.0 kde/frameworks

Install KParts and its dependencies:

craft kparts

Check the resulting environment:

craft --search kparts
which qtpaths
qtpaths --version

If the project is intentionally updated to a newer KDE Frameworks version, adjust the version pin accordingly.

3. Make Tinymist available to Kate

TypstPart starts the tinymist executable at runtime.

Make sure Tinymist is installed:

which tinymist
tinymist --version

Kate must also be able to find the executable.

If Tinymist is installed somewhere that is not part of Kate's environment, add its directory in:

Kate → Preferences → Behaviour → Path

Then restart Kate.

4. Create a development copy of Kate

On macOS, modifying the contents of an application bundle invalidates its existing code signature.

For development, do not modify the normal Kate installation in /Applications. Instead, create a separate copy:

mkdir -p "$HOME/Applications"

cp -R \
    "/Applications/Kate.app" \
    "$HOME/Applications/Kate-TypstDev.app"

The remainder of these instructions assumes the development copy is located at:

~/Applications/Kate-TypstDev.app

5. Configure TypstPart

Clone the TypstPart repository and enter it:

git clone <repository-url> typstpart
cd typstpart

Make sure the Craft environment is active:

source "$HOME/CraftRoot/craft/craftenv.sh"

Configure a development build:

cmake -S . -B build \
    -DCMAKE_BUILD_TYPE=Debug \
    -DKATE_APP="$HOME/Applications/Kate-TypstDev.app"

KATE_APP specifies the Kate application bundle into which the development plugin will be deployed.

There is normally no need to edit CMakeLists.txt to change this path.

6. Build

Build TypstPart:

cmake --build build --parallel

7. Deploy into the development Kate bundle

The project provides a macOS-specific deploy-kate target:

cmake --build build --target deploy-kate

This copies the plugin into:

Kate-TypstDev.app/Contents/PlugIns/kf6/parts/

and adjusts the plugin's dynamic-library references so that KDE and Qt frameworks are loaded from the Kate application bundle.

8. Re-sign the development Kate copy

Modifying the contents of the Kate application bundle may invalidate its existing code signature.

For the initial development setup, ad-hoc sign the copied Kate application:

codesign --force --deep --sign - \
    "$HOME/Applications/Kate-TypstDev.app"

This signing method is intended for local development only. It is not a replacement for proper Developer ID signing and notarization when distributing an application.

You generally need to repeat the signing step whenever files inside the Kate application bundle are changed.

9. Run Kate with TypstPart

Start the development copy directly:

"$HOME/Applications/Kate-TypstDev.app/Contents/MacOS/kate"

Then open a .typ document.

You can also open a document directly from the command line:

"$HOME/Applications/Kate-TypstDev.app/Contents/MacOS/kate" \
    "/path/to/document.typ"

Debugging plugin loading

Qt's plugin loader diagnostics are useful when TypstPart does not appear or cannot be loaded:

QT_DEBUG_PLUGINS=1 \
"$HOME/Applications/Kate-TypstDev.app/Contents/MacOS/kate" \
"/path/to/document.typ"

To show only log output around TypstPart:

QT_DEBUG_PLUGINS=1 \
"$HOME/Applications/Kate-TypstDev.app/Contents/MacOS/kate" \
"/path/to/document.typ" 2>&1 \
| grep -i -A25 -B3 typstpart

For plugin-loading problems, it is often useful to run the command without grep first so that the complete Qt loader output is available.

Development workflow

After the initial configuration, the usual development cycle is:

source "$HOME/CraftRoot/craft/craftenv.sh"

cmake --build build --parallel
cmake --build build --target deploy-kate

codesign --force --deep --sign - \
    "$HOME/Applications/Kate-TypstDev.app"

"$HOME/Applications/Kate-TypstDev.app/Contents/MacOS/kate" \
    "/path/to/test-document.typ"

If the plugin itself changes, rebuild, deploy, and re-sign the development Kate bundle before testing it again.

Project structure

A typical checkout contains:

typstpart/
├── CMakeLists.txt
└── src/
    ├── CMakeLists.txt
    ├── typstpart.cpp
    └── typstpart.json

typstpart.cpp implements the KPart and its interaction with Tinymist.

typstpart.json contains the KDE plugin metadata.

License

MIT