kirigami.el - A Unified Method to Fold and Unfold Text in Emacs Across a diverse set of Modes

The kirigami Emacs package provides a unified method to fold and unfold text in Emacs across a diverse set of Emacs modes.

Supported modes include: outline-mode, outline-minor-mode, outline-indent-minor-mode, org-mode, markdown-mode, gfm-mode, embark-collect-mode, vdiff-mode, vdiff-3way-mode, hide-ifdef-mode, vimish-fold-mode, TeX-fold-mode (AUCTeX), fold-this-mode, origami-mode, yafolding-mode, folding-mode, ts-fold-mode, treesit-fold-mode, and hs-minor-mode (hideshow).

With Kirigami, folding key bindings only need to be configured once. After that, the same keys work consistently across all supported major and minor modes, providing a unified and predictable experience for opening and closing folds. The available commands include:

• kirigami-open-fold: Open the fold at point.
• kirigami-open-fold-rec: Open the fold at point recursively.
• kirigami-close-fold: Close the fold at point.
• kirigami-open-folds: Open all folds in the buffer.
• kirigami-close-folds: Close all folds in the buffer.
• kirigami-toggle-fold: Toggle the fold at point.

In addition to unified interface, the kirigami package enhances folding behavior in outline, markdown-mode, and org-mode packages. It ensures that deep folds open reliably, allows folds to be closed even when the cursor is positioned inside the content, and ensures that sibling folds at the same level are visible when a sub-fold is expanded. When Kirigami closes outline folds, it preserves the visibility of folded headings in the window. Additionally, it resolves upstream Emacs issues, such as bug#79286.

If kirigami enhances your workflow, please show your support by ⭐ starring kirigami.el on GitHub to help more Emacs users discover its benefits.

Features

Here are the features that kirigami offers:

• Uniform commands: The same commands and keys can be used to open, close, toggle, or check folds, no matter what mode is active. (Commands: kirigami-open-fold, kirigami-open-fold-rec, kirigami-open-folds, kirigami-close-fold, kirigami-toggle-fold, kirigami-close-folds)
• Automatic handler selection: Kirigami automatically chooses the right folding method based on the mode being used.
• Extensible fold list: Users can easily add or customize folding methods for different modes through the kirigami-fold-list alist.
• Support for multiple folding backends, including:
  • outline-mode, outline-minor-mode
  • outline-indent-minor-mode (outline-indent.el, a package that enables code folding based on indentation)
  • org-mode
  • markdown-mode and gfm-mode
  • vdiff-mode and vdiff-3way-mode
  • embark-collect-mode
  • hs-minor-mode (hideshow)
  • hide-ifdef-mode
  • vimish-fold-mode
  • TeX-fold-mode (AUCTeX)
  • fold-this-mode
  • yafolding-mode
  • origami-mode
  • treesit-fold-mode
  • ts-fold-mode
• In addition to unified interface for opening and closing folds, the kirigami package:
  • Visual Stability: Avoids the disruptive window jump by preserving the cursor's exact vertical position when expanding or collapsing headings, maintaining a constant relative distance between the cursor and the window start.
  • Enhances outline: Improves folding in outline-mode, outline-minor-mode, markdown-mode, gfm-mode, and org-mode by ensuring deep folds open reliably, keeping folded headings visible, and collapsing to the shallowest heading level.
  • Hooks: kirigami-pre-action-predicates and kirigami-post-action-functions run before and after each fold, allowing actions to be allowed or blocked and enabling UI or external updates after changes.

The kirigami package supports Emacs version 26.3 and above.

Installation

To install kirigami from MELPA:

1. If you haven't already done so, add MELPA repository to your Emacs configuration.

2. Add the following code to your Emacs init file to install kirigami from MELPA:

(use-package kirigami)

Usage

Vanilla Emacs Key bindings

Here is an example of default key bindings:

(global-set-key (kbd "C-c z o") 'kirigami-open-fold)     ; Open fold at point
(global-set-key (kbd "C-c z O") 'kirigami-open-fold-rec) ; Open fold recursively
(global-set-key (kbd "C-c z r") 'kirigami-open-folds)    ; Open all folds
(global-set-key (kbd "C-c z c") 'kirigami-close-fold)    ; Close fold at point
(global-set-key (kbd "C-c z m") 'kirigami-close-folds)   ; Close all folds
(global-set-key (kbd "C-c z TAB") 'kirigami-toggle-fold) ; Toggle fold at point

Evil-mode Key Bindings

Evil-mode users can override the default folding keys with the following configuration:

;; Configure Kirigami to replace the default Evil-mode folding key bindings
(with-eval-after-load 'evil
  (define-key evil-normal-state-map "zo" 'kirigami-open-fold)
  (define-key evil-normal-state-map "zO" 'kirigami-open-fold-rec)
  (define-key evil-normal-state-map "zc" 'kirigami-close-fold)
  (define-key evil-normal-state-map "za" 'kirigami-toggle-fold)
  (define-key evil-normal-state-map "zr" 'kirigami-open-folds)
  (define-key evil-normal-state-map "zm" 'kirigami-close-folds))

Commands

Kirigami defines several interactive commands. These commands abstract over all supported folding systems:

• kirigami-open-fold Open the fold at point.

• kirigami-open-fold-rec Open the fold at point recursively.

• kirigami-open-folds Open all folds in the buffer.

• kirigami-close-fold Close the fold at point.

• kirigami-toggle-fold Toggle the fold at point.

• kirigami-close-folds Close all folds in the buffer.

Extending Kirigami: Adding other fold methods

The core behavior is driven by kirigami-fold-list, a customizable list that associates folding actions with sets of major or minor modes. Each entry in the list specifies:

• A list of modes that act as a predicate.
• A property list describing supported folding actions.

Properties include:

• :open-all Function to open every fold in the current buffer.

• :close-all Function to close every fold in the current buffer.

• :toggle Function to toggle the fold at point.

• :open Function to open the fold at point.

• :open-rec Function to open the fold at point recursively.

• :close Function to close the fold at point.

Each property must specify a function. A value of nil indicates that the corresponding action is ignored for that handler.

Here is an example using the built-in hs-minor-mode, which Kirigami supports by default. This example demonstrates how additional folding actions can be configured:

(push
 '((hs-minor-mode)
   :open-all    hs-show-all
   :close-all   hs-hide-all
   :toggle      hs-toggle-hiding
   :open        hs-show-block
   :open-rec    nil
   :close       hs-hide-block)
 kirigami-fold-list)

Frequently Asked Questions

Why the author developed the kirigami package?

Code folding in Emacs has historically suffered from reliability issues, which led to the development of kirigami. Even built-in modes such as outline-mode and outline-minor-mode which are also used by org-mode, gfm-mode, and markdown-mode contain bugs that have not yet been addressed upstream, and kirigami fixes them.

The kirigami package also provides a unified interface for opening and closing folds. Without it, users must manually configure keybindings for each individual mode, a tedious process. It functions as a set-and-forget enhancement for code folding. It requires configuration only once. Subsequently, the same keys and functions enable consistent folding and unfolding across all supported major and minor modes.

(The kirigami package is highly recommended for use with outline-based modes, such as markdown-mode, gfm-mode, org-mode, outline-minor-mode, or outline-indent-minor-mode. This package resolves persistent inconsistencies and prevents incorrect folding behavior.)

What code folding packages does the author use in addition to kirigami.el?

In addition to the kirigami package, the author uses two reliable code folding packages:

1. Indentation-based folding (Python, YAML, Haskell, etc.): outline-indent
2. Tree-sitter-based folding: treesit-fold (The integration of Tree-sitter allows Emacs to operate on the Abstract Syntax Tree, making folding structurally accurate rather than heuristic.)
3. The built-in outline-minor-mode for emacs-lisp-mode, markdown-mode, and conf-mode/conf-unix-mode.

NOTE: The author prefers using outline-indent for languages like Python, despite having treesit-fold installed. The advantage of outline-indent is that it allows for infinite folding depth; it enables the folding of classes, functions within them, and even nested structures like while loops and if statements.

Maintaining Vertical Cursor Position During Folding

Folding packages such as Outline, Outline Indent, and Org mode depend on the native Emacs redisplay engine to handle visibility changes. Expanding or collapsing folds can cause window-start to shift relative to the current line. When this displacement mo