The Kalem Book GitHub

This Book describes Kalem's main branch, which may be ahead of the latest release.

The extension model

Kalem can be changed in two ways. The first is data: settings, key bindings and themes, in files that Kalem reads, checks and reports on; that way is available today. The second is code: plugins, which add modes, completers, block types, link types, views and export formats; that way is designed and decided (D25, D28, D29), and its runtime runs viewers and extension plugins today. Every planned item below is named by its task in the former work breakdown, docs/todo.md; the plan is docs/roadmap.md.

What Status Where
Settings (settings.toml, workspace layers) Available Settings
Key bindings (keymap.json, two profiles) Available Commands, scopes and keys
Command registry, scopes and when-clauses Available Commands, scopes and keys
Themes (themes/light.toml, dark.toml) Available this chapter, below
Completer contract (in Rust, inside Kalem) Available Completers, modes and highlighters
Highlighting of code (syntect, built in) Available Completers, modes and highlighters
Command line for scripts and CI Available The command line
Document mode contract (ModeSpec) Available Completers, modes and highlighters
Viewer plugins (WASM components, WIT API) Available Plugins
Extension plugins: commands, events, panels Available Plugins
Plugin repository getkalem/plugins, index Available Plugins
Completers and layers over modes as plugins Available Completers, modes and highlighters
Modes, renderers as plugins Planned crates/kalem-plugin/coverage.toml
Inspection panel, debug socket Planned T3.2.1 to T3.2.5

"Available" means it works in the current version, in both editors, and this Book describes it from the code. "Planned" means the design is decided and the task is open; the names and shapes given for it may still change.

1. The principle: new features, same format

Plugins must be able to add real features, new block types, link types, views, export targets and document checks, while every document stays valid Org that Emacs opens without Kalem. So plugins extend semantics, not syntax: the parser's grammar is fixed, and plugins give meaning to the extension points Org already has, as Emacs packages do: special blocks (#+BEGIN_kanban), source block languages (#+BEGIN_SRC mermaid), link types ([[jira:ABC-123]]), drawers and properties, keywords, tags and TODO keywords, export snippets and macros, dynamic blocks. A document that uses a plugin still opens in Emacs, and in Kalem without the plugin, as ordinary Org.

2. A small core, one contract

The core of Kalem is five things (D29): Org, with its parser, model, editing, tables and export engine; the Markdown, CSV and LaTeX modes; the text engine with the view model; the two frontends; and the infrastructure that runs before any plugin: commands, keymaps, settings, files, projects, search and the plugin loader. Everything else is to be a plugin on the public contracts, installed when it is wanted (none is built into the binary), and new modes and file types are developed in getkalem/plugins, never in the core. Today the core holds more than this: the export back-ends beyond HTML are built in, because the plugin API has no export interface yet.

Highlighters, document modes and completers each have one contract, shared by the built-in ones and by plugins (D25), so a plugin can do everything a built-in does and the contract is proven before any plugin uses it. The completer contract and the document mode contract exist in kalem-core today (Completers, modes and highlighters); plugins offer completers already, and the plugin side of modes is phase 3.

3. What you can change today

  • Settings. settings.toml in the settings directory, and .kalem/settings.toml in a project, which applies over yours. Every value is checked; a wrong one is reported and the layer below applies. Tables under plugins.<id> are each plugin's settings; the list plugins.enabled is accepted but not read yet (every installed plugin loads). See Settings.
  • Keys. keymap.json: add, change and remove bindings, with arguments, when-clauses and terminal variants. See Commands, scopes and keys.
  • Themes. themes/light.toml and themes/dark.toml change any color of the built-in themes: the page, text, links, the selection, TODO keywords, headline levels, and six colors of source code (keyword, string, comment, number, function, type). Themes with other names are planned with the plugin API.
  • Document modes of files. A mode line on the first line (-*- mode: org -*-), and Set Document Mode, remembered in the workspace's files.modes.
  • Scripts. The kalem command line checks, formats, exports, queries and completes files without a window. See The command line.

An extension plugin adds commands, keys and completers today (see Plugins); adding a mode still means changing Kalem's source: the contracts are Rust types in kalem-core, described in the chapters that follow for contributors, and for the plugin authors who will implement them later.