The built-in Emacs outline-mode and outline-minor-mode allow structuring documents with collapsible sections. By default, these modes use an ellipsis (“…”) to indicate folded text. However, the default ellipsis and its face can make it hard to distinguish between folded text and regular text. This is why it can be beneficial to customize the ellipsis.

The code snippets provided in this article allow for customizing the ellipsis locally within a buffer.

Set the buffer local outline ellipsis

To apply the ellipsis locally to a buffer, the following Elisp code snippet modifies the display settings within that buffer.

The ellipsis string is displayed using the shadow face for visual consistency. Internally, a buffer-local display table is constructed (or reused if one already exists), and the selective display slot is updated to render the given ellipsis.

Here is the Emacs Lisp code snippet to achieve this:

(defun my-outline-set-buffer-local-ellipsis (ellipsis)
  "Set a buffer-local ellipsis string ELLIPSIS for outline folding display.

This function configures the current buffer to use a custom ellipsis string for
selective display, typically in `outline-mode' or `outline-minor-mode'.

The string ELLIPSIS is trimmed of trailing whitespace before use, as such
whitespace can be misleading when lines are truncated or visually wrapped. In
those cases, the trailing space may appear on a new visual line, creating the
false impression of an additional line. Deleting this apparent line can
inadvertently remove the entire folded logical line."
  (let* ((display-table (or buffer-display-table (make-display-table)))
         (face-offset (* (face-id 'shadow) (ash 1 22)))
         (value (vconcat (mapcar (lambda (c)
                                   (+ face-offset c))
                                 (string-trim-right ellipsis)))))
    (set-display-table-slot display-table 'selective-display value)
    (setq buffer-display-table display-table)))Code language: Lisp (lisp)

Here is an example of applying a buffer-local ellipsis when outline-minor-mode is enabled:

(add-hook 'outline-minor-mode
          #'(lambda()
              (my-outline-set-buffer-local-ellipsis " ▼")))Code language: PHP (php)

The Elisp code above will change the outline-mode and outline-minor-mode ellipsis to:

(The screenshot above shows a YAML file folded using outline-indent.el, which leverages outline-minor-mode to enable code folding, , serving as a modern replacement for deprecated packages such as origami.)

Conclusion

Customizing the ellipsis in outline-mode and outline-minor-mode is a simple yet effective way to personalize your Emacs and create a more visually appealing way to handle folds.