Emacs: Customizing the Ellipsis (…) in Outline Mode and Outline Minor Mode

5/5

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 either globally or locally within a buffer.

Set the global outline ellipsis

The following function can be used to change the ellipsis in both outline-mode and outline-minor-mode to ▼:

(defun my-outline-set-global-ellipsis (ellipsis)
  "Apply the ellipsis ELLIPSIS to outline mode globally."
  (let* ((face-offset (* (face-id 'shadow) (ash 1 22)))
         (value (vconcat (mapcar (lambda (c) (+ face-offset c)) ellipsis))))
    (set-display-table-slot standard-display-table 'selective-display value)))

(my-outline-set-global-ellipsis " ▼ ")
Code language: Lisp (lisp)

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 or outline-yaml.el, which leverages outline-minor-mode to outline and enable code folding in YAML files.)

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. This ensures that any changes made affect only the current buffer, leaving the global Emacs environment unaffected. This approach is particularly useful for customizing displays in specific files or testing new configurations without affecting other buffers or sessions.

Here is the Emacs Lisp code snippet to achieve this:

(defun my-outline-set-buffer-local-ellipsis (ellipsis)
  "Apply the ellipsis ELLIPSIS to outline mode locally to a buffer."
  (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)) ellipsis))))
    (set-display-table-slot display-table 'selective-display value)
    (setq buffer-display-table display-table)))Code language: Lisp (lisp)

And here is an example of applying the buffer-local ellipsis to text-mode:

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

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.

2 thoughts on “Emacs: Customizing the Ellipsis (…) in Outline Mode and Outline Minor Mode

  1. Very nice. Thank you much for sharing.

    One of the reasons I don’t use outline-mode is that often I can’t see if the ellipsis belong to a folded block or if I typed these myself. This will no longer be the case with your customization tip so I don’t have to be afraid anymore of ending a line with 3 dots. I don’t need it in org-mode where I easily recognize folded headlines and code blocks, but also there does it increase my overview. Thanks.

    • You’re welcome E3D3! I’m glad you found the customization helpful.

      Indeed, distinguishing between folded blocks and manually typed ellipses can be challenging with the default settings.

      If you have any other comments or suggestions, feel free to reach out!

Leave a Reply

Your email address will not be published. Required fields are marked *