awth13 / org-appear

Toggle visibility of hidden Org mode element parts upon entering and leaving an element

org-appear

Make invisible parts of Org elements appear visible.

About

Org mode provides a way to toggle visibility of hidden elements such as emphasis markers, links, etc. by customising specific variables, e.g., org-hide-emphasis-markers. However, it is currently not possible to do this interactively and on an element-by-element basis. This package, inspired by org-fragtog, enables automatic visibility toggling depending on cursor position. Hidden element parts appear when the cursor enters an element and disappear when it leaves.

Installation

The easiest way to install org-appear is from MELPA, using your favourite package manager or package-install. For Guix users, org-appear is also available in the official GNU Guix channel.

Manual installation

With straight.el, simply put the following line in init.el:

(straight-use-package '(org-appear :type git :host github :repo "awth13/org-appear"))

Alternatively, git clone this repository and point Emacs to it using the :load-path keyword of use-package or require.

Usage

The package can be enabled interactively or automatically on Org mode start-up:

(add-hook 'org-mode-hook 'org-appear-mode)

By default, toggling is instantaneous and only emphasis markers are toggled. The following custom variables can be changed to enable additional functionality.

org-appear-autoemphasis

if non-nil and org-hide-emphasis-markers is on, toggle emphasis markers

org-appear-autolinks

if non-nil and org-link-descriptive is on, toggle links

org-appear-autosubmarkers

if non-nil and org-pretty-entities is on, toggle subscripts and superscripts

org-appear-autoentities

if non-nil and org-pretty-entities is on, toggle Org entitites

org-appear-autokeywords

if non-nil and org-hidden-keywords is on, toggle keywords in org-hidden-keywords

org-appear-inside-latex

if non-nil, toggle entities and sub/superscripts in LaTeX fragments

org-appear-delay

seconds of delay before toggling

org-appear-trigger

when to toggle elements

If Org mode custom variables that control visibility of elements are configured to show hidden parts, the respective org-appear settings do not have an effect.

org-appear-trigger can be set to always, on-change, or manual. With on-change, elements will be toggled only when the buffer is modified or on mouse click. This option disables delayed toggling. With manual, toggling must be enabled by calling org-appear-manual-start. org-appear-manual-stop is used to disable toggling with this option.

The manual option is useful for, e.g., integrating org-appear with evil-mode. Below is an example configuration for toggling elements in Insert mode only. Note that org-appear expects to be enabled in Org mode buffers only, which is why the example attaches evil-mode hooks to the Org mode startup hook.

(setq org-appear-trigger 'manual)
(add-hook 'org-mode-hook (lambda ()
                           (add-hook 'evil-insert-state-entry-hook
                                     #'org-appear-manual-start
                                     nil
                                     t)
                           (add-hook 'evil-insert-state-exit-hook
                                     #'org-appear-manual-stop
                                     nil
                                     t)))

Acknowledgements

Special thanks to SPFabGerman, who came up with the idea and extended org-appear beyond emphasis marker toggling, and daviwil, who proposed the org-appear name.

Known Issues

org-appear does not handle overlapping emphasis elements correctly, e.g.,

*Why would someone /nest emphasis* like that?/

In the above example, org-appear can only detect and reveal the first (bold) element. This is due to the reliance on the org-element API – org-element-context in particular – which also fails to detect the second (italic) element.

org-appear will fail to detect elements nested inside certain other elements, such as comments or document titles.