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-autolinks

if non-nil, toggle links

org-appear-autosubmarkers

if non-nil, toggle subscripts and superscripts

org-appear-autoentities

if non-nil, toggle Org entitites

org-appear-autokeywords

if non-nil, toggle keywords in org-hidden-keywords

org-appear-delay

seconds of delay before toggling

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.

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.