[[https://melpa.org/#/org-appear][file:https://melpa.org/packages/org-appear-badge.svg]] [[https://github.com/awth13/org-appear/actions/workflows/check.yml][file:https://github.com/awth13/org-appear/actions/workflows/check.yml/badge.svg?branch=master]]

• ~org-appear~

Make invisible parts of Org elements appear visible.

** About

[[https://orgmode.org/][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 [[https://github.com/io12/org-fragtog][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.

[[file:demo.gif]]

** 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 [[https://github.com/raxod502/straight.el][straight.el]], simply put the following line in ~init.el~:

+begin_src emacs-lisp

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

+end_src

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:

+begin_src emacs-lisp

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

+end_src

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.

+begin_src emacs-lisp

(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)))

+end_src

** Acknowledgements

Special thanks to [[https://github.com/SPFabGerman][SPFabGerman]], who came up with the idea and extended ~org-appear~ beyond emphasis marker toggling, and [[https://github.com/daviwil][daviwil]], who proposed the ~org-appear~ name.

** Known Issues

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

+begin_example

Why would someone /nest emphasis like that?/

+end_example

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.