https://github.com/awth13/org-appear

Toggle visibility of hidden Org mode element parts upon entering and leaving an element
https://github.com/awth13/org-appear

Last synced: 20 days ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/awth13/org-appear
• Owner: awth13
• License: mit
• Created: 2021-01-23T15:10:45.000Z (almost 4 years ago)
• Default Branch: master
• Last Pushed: 2023-11-27T10:53:22.000Z (12 months ago)
• Last Synced: 2024-02-17T08:35:29.769Z (9 months ago)
• Language: Emacs Lisp
• Homepage:
• Size: 313 KB
• Stars: 348
• Watchers: 9
• Forks: 19
• Open Issues: 7
• Metadata Files:
  • Readme: README.org
  • License: LICENSE

Awesome Lists containing this project

README

        
[[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.