Tag Archives: code-folding

The Definitive Guide to Code Folding in Emacs

Reply

Navigating large source files containing thousands of lines of code with Emacs makes it difficult to perceive the underlying structure. For a software engineer spending the majority of the day reading and writing code, reliable folding is a requirement for maintaining focus and managing complexity.

Before we dive in, please consider sharing this article on your website/blog, Mastodon, Reddit, X, or your preferred social media platforms. Sharing it will help fellow Emacs users discover better ways to manage code folding.

In this article, we explore:

  • A folding Frontend: Consolidating folding commands into a single, predictable keymap that operates consistently across all code folding modes.
  • Folding Backends: Ready-to-use hooks to activate the most effective folding backend for the following major modes: C, C++, Java, Rust, Go, Python, JavaScript, TypeScript, Emacs Lisp, shell scripts, Lua, Haskell, YAML, Org-mode, Markdown…
  • Editor Integration: Using indirect buffers to maintain independent folding states, configuring search operations to strictly ignore folded text, and setting up display-line-numbers-mode…
  • Discouraged Folding Engines: A review of legacy or poorly performing packages to avoid.

Why code folding?

Code folding is about managing cognitive load, preserving spatial memory, and controlling screen real estate:

  • Navigating through code (e.g., with LSP) can create a vacuum of context. Folding an entire file to its top-level headings allows the manipulation of the file skeleton directly in the main buffer. Revealing only a specific entry and its parents provides an immediate understanding of the hierarchy without losing position.
  • When tasked with debugging a 20,000 line legacy file, immediate refactoring is rarely an option. Folding enables the visual modularization of massive files on the fly, making hostile codebases readable.
  • Every visible line of code on the screen requires a fraction of subconscious attention to ignore. During debugging sessions, folding adjacent functions or complex implementations acts as a visual garbage collector.
  • Moving or deleting a massive function or block is prone to selection errors. When a block is folded, it behaves as a single logical unit that can be cut, copied, or moved safely and cleanly.
  • Folding is effective for tracking progress during extensive pull requests. Collapsing previously examined functions or blocks actively filters out visual noise.

Code Folding Frontend

The primary drawback of code folding modes is inconsistency. For example, hs-minor-mode and outline-minor-mode use entirely different functions and keybindings to perform the exact same logical action.

The solution is a package called kirigami, which acts as a universal frontend for text folding. You define your keybindings once, and kirigami automatically detects the active folding and routes your commands to the appropriate engine, whether that is outline-minor-mode, outline-indent-minor-mode, org-mode, markdown-mode, gfm-mode, treesit-fold-mode, hs-minor-mode (hideshow), and many others…

To install and configure kirigami, add the following code to your Emacs init file:

(use-package kirigami
  :commands (kirigami-open-fold
             kirigami-open-fold-rec
             kirigami-close-fold
             kirigami-toggle-fold
             kirigami-open-folds
             kirigami-close-folds-except-current
             kirigami-close-folds)

  :bind
  ;; Vanilla Emacs keybindings
  (("C-c z o" . kirigami-open-fold)          ; Open fold at point
   ("C-c z O" . kirigami-open-fold-rec)      ; Open fold recursively
   ("C-c z r" . kirigami-open-folds)         ; Open all folds
   ("C-c z c" . kirigami-close-fold)         ; Close fold at point
   ("C-c z m" . kirigami-close-folds)        ; Close all folds
   ("C-c z a" . kirigami-toggle-fold)))      ; Toggle fold at pointCode language: Lisp (lisp)

If you are an evil-mode user, add the following keybindings to your init file:

;; Uncomment the following if you are an `evil-mode' user:
(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))Code language: Lisp (lisp)

In addition to providing a unified interface, the kirigami package enhances folding behavior in outline, markdown-mode, and org-mode packages. It ensures that deep folds and sibling folds open and close reliably.

Code Folding Backends

A code folding backend is the underlying engine that handles the logic of identifying and hiding specific blocks of text. While the kirigami package provides the user interface and keybindings, it requires a backend, such as outline-minor-mode or hs-minor-mode, to perform the folding.

NOTE: When configuring folding backends, ensure that only one folding minor mode is active concurrently in a single buffer, as conflicts and unexpected behavior may occur. For this reason, adding folding hooks to broad categories like prog-mode-hook or text-mode-hook is discouraged. Instead, hooks should be applied specifically to individual language modes, such as emacs-lisp-mode-hook.

Below are ready-to-use hooks to activate the optimal folding backend for each major mode:

Outline (built-in)

outline-minor-mode relies on hierarchical headings to determine collapsible sections. It is effective for structured text and is my default choice for Elisp, Lisp, Markdown, Diff, and configuration files.

(add-hook 'emacs-lisp-mode-hook #'outline-minor-mode)
(add-hook 'lisp-interaction-mode-hook #'hs-minor-mode) ; scratch
(add-hook 'lisp-mode-hook #'outline-minor-mode)
(add-hook 'conf-mode-hook #'outline-minor-mode)
(add-hook 'markdown-mode-hook #'outline-minor-mode)
(add-hook 'diff-mode-hook #'outline-minor-mode)Code language: Lisp (lisp)

Hideshow (built-in)

hs-minor-mode parses buffer syntax to accurately detect the start and end of blocks. It is the best tool for C-style languages, or anything using braces {} and explicit block structures like sh/Bash shell scripts.

;; Systems and General Purpose
(add-hook 'c-mode-hook #'hs-minor-mode)
(add-hook 'c++-mode-hook #'hs-minor-mode)
(add-hook 'java-mode-hook #'hs-minor-mode)
(add-hook 'rust-mode-hook #'hs-minor-mode)
(add-hook 'go-mode-hook #'hs-minor-mode)
(add-hook 'ruby-mode-hook #'hs-minor-mode)
(add-hook 'php-mode-hook #'hs-minor-mode)
(add-hook 'perl-mode-hook #'hs-minor-mode)

;; Web and Frontend
(add-hook 'js-mode-hook #'hs-minor-mode)
(add-hook 'typescript-mode-hook #'hs-minor-mode)
(add-hook 'css-mode-hook #'hs-minor-mode)

;; Scripting, Data, and Infrastructure
(add-hook 'sh-mode-hook #'hs-minor-mode) ; for bash/shell scripts
(add-hook 'json-mode-hook #'hs-minor-mode)
(add-hook 'lua-mode-hook #'hs-minor-mode)
(add-hook 'nxml-mode-hook #'hs-minor-mode)
(add-hook 'html-mode-hook #'hs-minor-mode)  ;; mhtml and htmlCode language: Lisp (lisp)

hs-minor-mode folds a single level at a time, such as entire functions, without providing convenient access to nested blocks. This makes it less practical for languages that require deep folding, such as YAML, where multiple nested levels are common. Even in languages like Python, Hideshow can be impractical, because it allows folding classes but does not provide convenient folding for the functions within those classes for example.

Outline-indent

The outline-indent package provides code folding based on indentation levels. It is recommended for Python, Haskell, and YAML because it supports an unlimited number of folding levels. For instance, it allows folding an entire function or specific nested blocks within that function, such as if statements inside while loops.

(use-package outline-indent
  :commands outline-indent-minor-mode
  :custom
  (outline-indent-ellipsis " ▼"))

;; Python
(add-hook 'python-mode-hook #'outline-indent-minor-mode)
(add-hook 'python-ts-mode-hook #'outline-indent-minor-mode)

;; Yaml
(add-hook 'yaml-mode-hook #'outline-indent-minor-mode)
(add-hook 'yaml-ts-mode-hook #'outline-indent-minor-mode)

;; Haskell
(add-hook 'haskell-mode-hook #'outline-indent-minor-mode)Code language: Lisp (lisp)

In addition to code folding, outline-indent allows moving indented blocks up and down, indenting/unindenting to adjust indentation levels, inserting a new line with the same indentation level as the current line, and moving backward/forward to the indentation level of the current line.

Treesit-fold

The treesit-fold package provides Intelligent code folding by using the structural understanding of the built-in tree-sitter parser. Unlike traditional folding methods that rely on regular expressions or indentation, treesit-fold uses the actual syntax tree of the code to accurately identify foldable regions such as functions, classes, comments, and documentation strings.

(use-package treesit-fold
  :commands (treesit-fold-close
             treesit-fold-close-all
             treesit-fold-open
             treesit-fold-toggle
             treesit-fold-open-all
             treesit-fold-mode
             global-treesit-fold-mode
             treesit-fold-open-recursively
             treesit-fold-line-comment-mode)

  :custom
  (treesit-fold-line-count-show t)
  (treesit-fold-line-count-format " ▼")

  :config
  (set-face-attribute 'treesit-fold-replacement-face nil
                      :foreground "#808080"
                      :box nil
                      :weight 'bold))

;; Systems and General Purpose
(add-hook 'c-ts-mode-hook #'treesit-fold-mode)
(add-hook 'c++-ts-mode-hook #'treesit-fold-mode)
(add-hook 'java-ts-mode-hook #'treesit-fold-mode)
(add-hook 'rust-ts-mode-hook #'treesit-fold-mode)
(add-hook 'go-ts-mode-hook #'treesit-fold-mode)
(add-hook 'ruby-ts-mode-hook #'treesit-fold-mode)
(add-hook 'php-ts-mode-hook #'treesit-fold-mode)
(add-hook 'csharp-ts-mode-hook #'treesit-fold-mode)
(add-hook 'go-mod-ts-mode-hook #'treesit-fold-mode)
(add-hook 'lua-ts-mode-hook #'treesit-fold-mode)

;; Web and Frontend
(add-hook 'js-ts-mode-hook #'treesit-fold-mode)
(add-hook 'typescript-ts-mode-hook #'treesit-fold-mode)
(add-hook 'tsx-ts-mode-hook #'treesit-fold-mode)
(add-hook 'css-ts-mode-hook #'treesit-fold-mode)
(add-hook 'html-ts-mode-hook #'treesit-fold-mode)
(add-hook 'heex-ts-mode-hook #'treesit-fold-mode)
(add-hook 'xml-ts-mode-hook #'treesit-fold-mode)

;; Scripting and Infrastructure
(add-hook 'bash-ts-mode-hook #'treesit-fold-mode)
(add-hook 'cmake-ts-mode-hook #'treesit-fold-mode)
(add-hook 'dockerfile-ts-mode-hook #'treesit-fold-mode)
(add-hook 'awk-ts-mode-hook #'treesit-fold-mode)
(add-hook 'vimscript-ts-mode-hook #'treesit-fold-mode)
(add-hook 'nix-ts-mode-hook #'treesit-fold-mode)

;; Data and Configuration
(add-hook 'json-ts-mode-hook #'treesit-fold-mode)
(add-hook 'toml-ts-mode-hook #'treesit-fold-mode)

;; Build Systems and Makefiles
(add-hook 'makefile-ts-mode-hook #'treesit-fold-mode)

;; Hardware Description and Shaders
(add-hook 'verilog-ts-mode-hook #'treesit-fold-mode)
(add-hook 'vhdl-ts-mode-hook #'treesit-fold-mode)
(add-hook 'hlsl-ts-mode-hook #'treesit-fold-mode)

;; Scientific, Data Science, and Academic
(add-hook 'latex-ts-mode-hook #'treesit-fold-mode)
(add-hook 'beancount-ts-mode-hook #'treesit-fold-mode)

;; Documentation and Diagrams
(add-hook 'markdown-ts-mode-hook #'treesit-fold-mode)
(add-hook 'mermaid-ts-mode-hook #'treesit-fold-mode)
 
;; Other
(add-hook 'gdscript-ts-mode-hook #'treesit-fold-mode)
(add-hook 'clojure-ts-mode-hook #'treesit-fold-mode)
(add-hook 'caml-ts-mode-hook #'treesit-fold-mode)
(add-hook 'ocaml-ts-mode-hook #'treesit-fold-mode)
(add-hook 'erlang-ts-mode-hook #'treesit-fold-mode)
(add-hook 'elixir-ts-mode-hook #'treesit-fold-mode)
(add-hook 'scala-ts-mode-hook #'treesit-fold-mode)
(add-hook 'dart-ts-mode-hook #'treesit-fold-mode)
(add-hook 'haskell-ts-mode-hook #'treesit-fold-mode)
(add-hook 'julia-ts-mode-hook #'treesit-fold-mode)
(add-hook 'kotlin-ts-mode-hook #'treesit-fold-mode)
(add-hook 'gleam-ts-mode-hook #'treesit-fold-mode)
(add-hook 'noir-ts-mode-hook #'treesit-fold-mode)
(add-hook 'swift-ts-mode-hook #'treesit-fold-mode)
(add-hook 'zig-ts-mode-hook #'treesit-fold-mode)Code language: Lisp (lisp)

For the treesit-fold block to function, you must be using Emacs 29.1 or newer, and you must have the actual Tree-sitter grammars installed on your machine for those specific languages.

Markdown-mode

The markdown-mode package provides a major mode for syntax highlighting, editing commands, and preview support for Markdown documents. It supports core Markdown syntax as well as extensions like GitHub Flavored Markdown (GFM). Markdown-mode and gfm-mode support outline-minor-mode folding. 

(use-package markdown-mode
  :commands (gfm-mode
             gfm-view-mode
             markdown-mode
             markdown-view-mode)
  :mode (("\\.markdown\\'" . markdown-mode)
         ("\\.md\\'" . markdown-mode)
         ("README\\.md\\'" . gfm-mode))
  :bind
  (:map markdown-mode-map
        ("C-c C-e" . markdown-do)))

;; Hooks
(add-hook 'markdown-mode-hook #'outline-minor-mode)Code language: Lisp (lisp)

Maintaining independent folding states in separate windows via indirect buffers (clones)

Opening the same buffer in multiple windows results in synchronized folding states; any folding or unfolding action performed in one window is immediately reflected in all others.

This occurs because folding engines use buffer-local overlays, which are shared across all windows associated with that specific buffer.

Indirect buffers provide a robust solution to this limitation. An indirect buffer shares the underlying text of its parent buffer but maintains an independent set of overlays. This distinction allows for the maintenance of different folding configurations for the same file simultaneously.

To create an indirect buffer (clone) of the current buffer in a separate window, execute:

M-x clone-indirect-buffer-other-windowCode language: plaintext (plaintext)

Creating an indirect buffer provides a separate buffer object that references the same text while maintaining its own isolated set of opened/closed folds.

Persisting and restoring folding state across sessions with savefold

By default, Emacs does not preserve the state of your folds when you close a buffer or exit the editor. The savefold package resolves this limitation. It records the positions of opened and closed folds to disk, automatically restoring them when a file is reopened.

The package integrates with most overlay-based folding frameworks. Currently supported systems include outline, org-mode, markdown-mode, hideshow, treesit-fold, ts-fold, etc.

To install and activate savefold globally using use-package, add the following snippet to your initialization file.

(use-package savefold
  :init
  ;;  list of symbols indicating active backends. Default: '(outline)
  (setq savefold-backends '(outline org hideshow treesit-fold markdown))

  ;; The directory path where the serialization files are stored.
  (setq savefold-directory (locate-user-emacs-file "savefold"))

  ;; When using `savefold' alongside `org-mode', configure the default Org startup
  ;; visibility to ensure that the saved state applies correctly without
  ;; conflicting with internal Org visibility cycles:
  (setq org-startup-folded 'showeverything)

  :config
  (savefold-mode 1))Code language: Lisp (lisp)

Preventing Emacs search from matching text within folded blocks

Note: This setting is for users who want search operations to ignore folded blocks instead of expanding them. This behavior is subjective and may not suit every workflow.

By default, search operations can match text within folded blocks, which often causes Emacs to automatically expand the hidden content.

To instruct Emacs to strictly ignore invisible text during search operations, add the following configuration to your init file:

(setq-default search-invisible nil)Code language: Lisp (lisp)

Alternatively, to restrict this behavior to specific modes, apply a buffer-local configuration via a mode hook:

(add-hook 'prog-mode-hook (lambda ()
                            (setq-local search-invisible nil)))Code language: Lisp (lisp)

Integrating display-line-numbers-mode with code folding

The built-in display-line-numbers-mode renders line numbers in the side margin of the window. By default, it uses absolute line numbering, which tracks the absolute line count in the buffer. Consequently, when a block is folded, the line numbers skip the hidden range (e.g., jumping from 15 to 120).

For users who prefer visual line numbering, display-line-numbers-mode can be configured to ignore collapsed content and assign numbers sequentially based only on what is currently rendered on the screen.

To implement visual line numbering as your global default, set the following variable in your configuration:

(setq-default display-line-numbers-type 'visual)Code language: Lisp (lisp)

(Note that you must still enable the mode itself using M-x global-display-line-numbers-mode for the line numbers to appear.)

Discouraged Emacs Folding Engines

Choosing an appropriate folding engine is important for maintaining performance and stability within Emacs. While several third-party and legacy options exist, the following packages and methods are generally discouraged in favor of more modern or integrated alternatives:

  • Origami: This package is slow and largely unmaintained. Origami uses a non-standard API and a complex implementation that frequently conflicts with other overlay-based minor modes. Its overhead can lead to performance degradation, especially when handling large buffers or deeply nested code. (Modern alternatives to origami: outline-indent, treesit-fold, outline-minor-mode, hs-minor-mode)
  • Yafolding: This package is also unmaintained and suffers from performance issues. (Modern alternative to yafolding: outline-indent)
  • Semantic (CEDET): Part of the legacy CEDET suite, Semantic folding is widely regarded as heavyweight. The parsing overhead required for its operation often introduces noticeable latency, making it vastly less efficient than modern built-in alternatives like Tree-sitter. (Modern alternatives to CEDET code folding: treesit-fold, outline-minor-mode, hs-minor-mode, outline-indent)
  • Selective Display (set-selective-display): This is Emacs’ oldest built-in folding method (often bound to C-x $). It causes unpredictable cursor jumping, and lacks any contextual awareness.
  • Folding-mode: This ancient package relies on explicit structural markers placed manually inside code comments (e.g., {{{ and }}}). While robust for the user, markers pollute the source code with editor-specific metadata. This is heavily frowned upon in modern collaborative environments where team members use varying IDEs.
  • Vimish-fold: Although useful for manual, ad-hoc text folding, vimish-fold is not recommended as a primary automated folding engine. Unlike Vim’s set foldmethod=marker, the vimish-fold implementation does not support recursive markers, such as {{{ inside of {{{. Additionally, like folding-mode, vimish-fold also uses markers that pollute the source code with editor-specific markers, a practice discouraged in collaborative environments where team members use a variety of editors and IDEs.

Conclusion

Establishing a unified folding interface in Emacs converts a buffer into a structured environment. Whether you are refactoring complex Python classes or navigating extensive Org documents, relying on a standardized command set simplifies the experience. Integrating the hooks outlined in this article ensures you enable the optimal backend for each major mode, allowing you to focus on logic rather than editor mechanics.

kirigami.el – A Unified Interface for Text Folding across a diverse set of Emacs modes (outline-mode, outline-minor-mode, outline-indent-mode, org-mode, markdown-mode, vdiff-mode, hs-minor-mode, treesit-fold-mode…)

Reply

Build Status MELPA MELPA Stable License

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, outli-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, hs-minor-mode (hideshow), ibuffer-mode (M-x ibuffer), and profiler-report-mode (M-x profile-report).

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 interactive 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.

It features both a buffer-local minor mode (kirigami-mode) and an editor-wide global minor mode (kirigami-global-mode) that expose all text-folding operations through keybindings, a menu bar entry, and context menus.

In addition to providing a unified interface, the kirigami package enhances folding behavior in the 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. For org-mode specifically, Kirigami now provides native folding support for elements such as source blocks (#+begin_src), drawers (:TEST_DRAWER:), and results (#+RESULTS:). 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 (built-in), and external packages based on outline such as outli (outli-mode) or outline-indent (outline-indent-minor-mode), a package that enables code folding based on indentation.
    • hs-minor-mode (hideshow, built-in)
    • outline-indent-minor-mode (outline-indent.el, a package that enables code folding based on indentation)
    • org-mode (built-in)
    • markdown-mode and gfm-mode (markdown-mode)
    • vdiff-mode and vdiff-3way-mode
    • treesit-fold-mode (treesit-fold, which provides intelligent code folding by using the structural understanding of the built-in tree-sitter parser)
    • embark-collect-mode
    • hide-ifdef-mode
    • vimish-fold-mode
    • origami-mode
    • TeX-fold-mode (AUCTeX)
    • fold-this-mode
    • yafolding-mode
    • ts-fold-mode
    • ibuffer-mode (toggle filter groups in M-x ibuffer)
    • profiler-report-mode (expand/collapse M-x profile-report tree entries)
  • 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 and org-mode: 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. In org-mode, it intercepts folding commands to natively toggle source blocks (#+begin_src), drawers (:TEST_DRAWER:), and results (#+RESULTS:) sections without falling back to standard heading behavior.
    • 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
  :custom
  ;; Add Kirigami to the menu bar and context menu (`context-menu-mode').
  (kirigami-show-menu-bar t)
  (kirigami-show-context-menu t)
  :config
  (kirigami-global-mode 1))

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 a") '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))

Configuring and Enabling Folding Backends

Kirigami acts as a unified interface and requires an underlying folding backend to be active in the current buffer.

The following article provides a comprehensive guide on installing and enabling the supported folding backends: The Definitive Guide to Code Folding in Emacs.

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 code folding?

Code folding is about managing cognitive load, preserving spatial memory, and controlling screen real estate:

  • Navigating through code (e.g., with LSP) can create a vacuum of context. Folding an entire file to its top-level headings allows the manipulation of the file skeleton directly in the main buffer. Revealing only a specific entry and its parents provides an immediate understanding of the hierarchy without losing position.
  • When tasked with debugging a 20,000 line legacy file, immediate refactoring is rarely an option. Folding enables the visual modularization of massive files on the fly, making hostile codebases readable.
  • Every visible line of code on the screen requires a fraction of subconscious attention to ignore. During deep debugging sessions, folding adjacent functions or complex implementations acts as a visual garbage collector.
  • Moving or deleting a massive function or block is prone to selection errors. When a block is folded, it behaves as a single logical unit. Large chunks of logic can be cut, copied, or moved safely and cleanly without manually highlighting hundreds of lines.
  • Folding is effective for tracking progress during extensive pull requests. Collapsing previously examined functions or blocks actively filters out visual noise and enforces a strict focus on the unreviewed code.

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.)

Preventing Emacs search from matching text within folded blocks

By default, search operations can match text within folded blocks, which often causes Emacs to automatically expand the hidden content.

To instruct Emacs to strictly ignore invisible text during search operations, add the following configuration to your init file:

(setq-default search-invisible nil)

Alternatively, to restrict this behavior to specific modes, apply a buffer-local configuration via a mode hook:

(add-hook 'prog-mode-hook (lambda ()
                            (setq-local search-invisible nil)))

Integrating display-line-numbers-mode with code folding

The built-in display-line-numbers-mode renders line numbers in the side margin of the window. By default, it uses absolute line numbering, which tracks the absolute line count in the buffer. Consequently, when a block is folded, the line numbers skip the hidden range (e.g., jumping from 15 to 120).

For users who prefer visual line numbering, display-line-numbers-mode can be configured to ignore collapsed content and assign numbers sequentially based only on what is currently rendered on the screen.

To implement visual line numbering as your global default, set the following variable in your configuration:

(setq-default display-line-numbers-type 'visual)

Note that you must still enable the mode itself (for example, via M-x global-display-line-numbers-mode) for the line numbers to appear.

Maintaining independent folding states in separate windows via indirect buffers (clones)

Opening the same buffer in multiple windows results in synchronized folding states; any folding or unfolding action performed in one window is immediately reflected in all others.

This occurs because folding engines use buffer-local overlays, which are shared across all windows associated with that specific buffer.

Indirect buffers provide a robust solution to this limitation. An indirect buffer shares the underlying text of its parent buffer but maintains an independent set of overlays. This distinction allows for the maintenance of different folding configurations for the same file simultaneously.

To create an indirect buffer (clone) of the current buffer in a separate window, execute:

M-x clone-indirect-buffer-other-window

Creating an indirect buffer provides a separate buffer object that references the same text while maintaining its own isolated set of opened/closed folds.

Discouraged Emacs Folding Engines

Choosing an appropriate folding engine is important for maintaining performance and stability within Emacs. While several third-party and legacy options exist, the following packages and methods are generally discouraged in favor of more modern or integrated alternatives:

  • Origami: This package is slow and largely unmaintained. Origami uses a non-standard API and a complex implementation that frequently conflicts with other overlay-based minor modes. Its overhead can lead to performance degradation, especially when handling large buffers or deeply nested code. (Modern alternatives to origami: outline-indent, treesit-fold, outline-minor-mode, hs-minor-mode)
  • Yafolding: This package is also unmaintained and suffers from performance issues. (Modern alternative to yafolding: outline-indent)
  • Semantic (CEDET): Part of the legacy CEDET suite, Semantic folding is widely regarded as heavyweight. The parsing overhead required for its operation often introduces noticeable latency, making it vastly less efficient than modern built-in alternatives like Tree-sitter. (Modern alternatives to CEDET code folding: treesit-fold, outline-minor-mode, hs-minor-mode, outline-indent)
  • Selective Display (set-selective-display): This is Emacs’ oldest built-in folding method (often bound to C-x $). It causes unpredictable cursor jumping, and lacks any contextual awareness.
  • Folding-mode: This ancient package relies on explicit structural markers placed manually inside code comments (e.g., {{{ and }}}). While robust for the user, markers pollute the source code with editor-specific metadata. This is heavily frowned upon in modern collaborative environments where team members use varying IDEs.
  • Vimish-fold: Although useful for manual, ad-hoc text folding, vimish-fold is not recommended as a primary automated folding engine. Unlike Vim’s set foldmethod=marker, the vimish-fold implementation does not support recursive markers, such as {{{ inside of {{{. Additionally, like folding-mode, vimish-fold also uses markers that pollute the source code with editor-specific metadata, a practice discouraged in collaborative environments where team members use a variety of editors and IDEs.

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 moves the cursor off-screen, Emacs triggers an abrupt recentering. This visual discontinuity disrupts spatial context and requires manual effort to relocate the cursor.

To address these issues, the following option can be used to eliminate visual discontinuities by preventing window shifts and suppressing forced recentering when headings are expanded or collapsed:

(setq kirigami-preserve-visual-position t)

What is the meaning of the word Kirigami?

Kirigami is a form of Origami, the Japanese art that transforms a flat sheet of paper into a figure through controlled folds. In kirigami, the sheet is both folded and cut to form a three-dimensional structure that rises from the surface.

Kirigami and code folding in Emacs share a structural analogy based on selective concealment and controlled revelation. In kirigami, cuts and folds create regions that can be collapsed or expanded, revealing depth or hiding detail depending on how the paper is manipulated.

Code folding in Emacs operates on a similar principle. Blocks of text remain present in the buffer, but their visibility is adjusted by folding or unfolding sections.

Comments from users

  • neurolit on GitHub: “Thank you very much for this package!”

  • jcs090218: “Thanks for this great package!”

  • RideAndRoam3C: “I enabled it today while doing some Org technical docs work. Solid.”

  • mickeyp: “Nice job. So many different packages.”

  • Anthea_Likes: “I’ve been using Kirigami for a few months now, and it’s absolutely gorgeous! Thank you for this quality work 🙏”

Author and License

The kirigami Emacs package has been written by James Cherti and is distributed under terms of the GNU General Public License version 3, or, at your choice, any later version. Special thanks to the developers of Evil mode. Kirigami builds upon the idea and function from Evil mode to provide enhanced and unified code folding functionality to all Emacs users.

Copyright (C) 2025-2026 James Cherti

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program.

Links

Other Emacs packages by the same author:

  • minimal-emacs.d: This repository hosts a minimal Emacs configuration designed to serve as a foundation for your vanilla Emacs setup and provide a solid base for an enhanced Emacs experience.
  • compile-angel.el: Speed up Emacs! This package guarantees that all .el files are both byte-compiled and native-compiled, which significantly speeds up Emacs.
  • outline-indent.el: An Emacs package that provides a minor mode that enables code folding and outlining based on indentation levels for various indentation-based text files, such as YAML, Python, and other indented text files.
  • easysession.el: Easysession is lightweight Emacs session manager that can persist and restore file editing buffers, indirect buffers/clones, Dired buffers, the tab-bar, and the Emacs frames (with or without the Emacs frames size, width, and height).
  • vim-tab-bar.el: Make the Emacs tab-bar Look Like Vim’s Tab Bar.
  • elispcomp: A command line tool that allows compiling Elisp code directly from the terminal or from a shell script. It facilitates the generation of optimized .elc (byte-compiled) and .eln (native-compiled) files.
  • tomorrow-night-deepblue-theme.el: The Tomorrow Night Deepblue Emacs theme is a beautiful deep blue variant of the Tomorrow Night theme, which is renowned for its elegant color palette that is pleasing to the eyes. It features a deep blue background color that creates a calming atmosphere. The theme is also a great choice for those who miss the blue themes that were trendy a few years ago.
  • Ultyas: A command-line tool designed to simplify the process of converting code snippets from UltiSnips to YASnippet format.
  • dir-config.el: Automatically find and evaluate .dir-config.el Elisp files to configure directory-specific settings.
  • flymake-bashate.el: A package that provides a Flymake backend for the bashate Bash script style checker.
  • flymake-ansible-lint.el: An Emacs package that offers a Flymake backend for ansible-lint.
  • inhibit-mouse.el: A package that disables mouse input in Emacs, offering a simpler and faster alternative to the disable-mouse package.
  • quick-sdcv.el: This package enables Emacs to function as an offline dictionary by using the sdcv command-line tool directly within Emacs.
  • enhanced-evil-paredit.el: An Emacs package that prevents parenthesis imbalance when using evil-mode with paredit. It intercepts evil-mode commands such as delete, change, and paste, blocking their execution if they would break the parenthetical structure.
  • stripspace.el: Ensure Emacs Automatically removes trailing whitespace before saving a buffer, with an option to preserve the cursor column.
  • persist-text-scale.el: Ensure that all adjustments made with text-scale-increase and text-scale-decrease are persisted and restored across sessions.
  • pathaction.el: Execute the pathaction command-line tool from Emacs. The pathaction command-line tool enables the execution of specific commands on targeted files or directories. Its key advantage lies in its flexibility, allowing users to handle various types of files simply by passing the file or directory as an argument to the pathaction tool. The tool uses a .pathaction.yaml rule-set file to determine which command to execute. Additionally, Jinja2 templating can be employed in the rule-set file to further customize the commands.
  • kirigami.el: The kirigami Emacs package offers a unified interface for opening and closing folds across a diverse set of major and minor modes in Emacs, including outline-mode, outline-minor-mode, outline-indent-minor-mode, org-mode, markdown-mode, vdiff-mode, vdiff-3way-mode, hs-minor-mode, hide-ifdef-mode, origami-mode, yafolding-mode, folding-mode, and treesit-fold-mode. 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 folding experience.
  • buffer-guardian.el: Automatically saves Emacs buffers without requiring manual intervention. By default, it triggers a save when the user switches to another buffer, switches to another window or frame, Emacs loses focus, or the minibuffer is opened. Beyond standard file buffers, buffer-guardian also manages specialized editing buffers such as org-src and edit-indirect. Additional features, disabled by default, include periodic or idle-time saving of all buffers, automatic exclusion of remote, nonexistent, or large files, and support for custom exclusion rules via regular expressions or predicate functions.