Make invisible parts of Org elements appear visible.
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.
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.
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
.
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 inorg-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)))
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.
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.