legalnonsense / org-visual-outline

Make Orgmode look better

This package is split into two separate packages: org-dynamic-bullets which handles the dynamic bullets, and org-visual-indent which adds vertical lines to org-indent. They can be used independently.

To get the above effect, clone the repository, put it in your load path and:

(require 'org-dynamic-bullets)
(require 'org-visual-indent)
(org-dynamic-bullets-mode)
(org-visual-indent-mode)

org-dynamic-bullets

The icons are meaningful. ▶ means the heading has children and is folded. ▼ means the heading is unfolded. ▬ means the heading does not have any children. If the icon is filled (i.e., ▬ or ▼), it means the heading has text in its body. If the icon is not filled (i.e., ▭ or ▽), it means there is no body text. You can customize these characters by setting the following variables:

variable	default
org-dynamic-bullets-folded-body-text-bullet	▶
org-dynamic-bullets-folded-no-body-text-bullet	▷
org-dynamic-bullets-unfolded-body-text-bullet	▼
org-dynamic-bullets-unfolded-no-body-text-bullet	▽
org-dynamic-bullets-leaf-body-text-bullet	▬
org-dynamic-bullets-leaf-no-body-text-bullet	▭

The bullets are updated using various org-mode cycling and insertion hooks and also by relying on font lock. There may be better ways to do this, but it has not resulted in any detectable slow down for me.

org-dynamic-bullets does not provide any indentation or way to discern the level of a heading (i.e., it replaces all leading stars with a single bullet and without indentation). If you don’t like the vertical lines shown above, use it with vanilla org-indent-mode.

org-visual-indent

There are two faces you’ll want to set if you use org-visual-indent: org-visual-indent-pipe-face and org-visual-indent-blank-pipe-face. The foreground and background color of org-visual-indent-blank-pipe-face should match your background. You need to set both of these faces to the same height.

The foreground and background color of org-visual-indent-pipe-face should both be the desired color of the vertical line. By default, these colors are set based on the default face, which may or may not match the theme you are using if the the package is loaded before your theme is set. If you load org-visual-outline-mode before you set your theme,

You need to set both the foreground and background colors for there to be an unbroken vertical line from one line of next to the next.

I like using a height of .1 for these faces, which is the default, but you can make the lines thicker with a higher value.

If the vertical lines do not align properly, you’ll have to fuck with org-visual-indent-span, which is a bunch of spaces and represents the space between the vertical lines.

This package appropriates (via advice) much of org-indent and will likely break if org-indent gets a substantive updated. Everything words with Org 9.4. Until I pull out the useful parts of org-indent and package them separately, you’ll just have to hope nothing breaks.

Custom vertical line colors

The following variable allows the user to define the color of the vertical bars:

(setq org-visual-indent-color-indent '((1 (:background "blue" :foreground "blue" :height .1))
                                       (2 (:background "red" :foreground "red" :height .1))
                                       (3 (:background "green" :foreground "green" :height .1))))

The colors will cycle through to the beginning of the list once the max depth is reached. This overrides the color set by org-visual-indent-pipe-face.

One nice use of these colors would be to set it to match the org-heading face at point.

(setq org-visual-indent-color-indent
      (cl-loop for x from 1 to 8
               with color = nil
               do (setq color (or (face-foreground
                                   (intern 
                                    (concat "org-level-"
                                            (number-to-string x))))
                                  (face-foreground 'org-level-1)))
               collect `(,x ,(list
                              :background color
                              :foreground color
                              :height .1))))

;; If you don’t have all of the org-level-x faces set, this will use
;; org-level-1 as the backup. Or figure out your own way of doing it.
;; None of it matters anyway. 

Or you can create a gradient:

;; This uses some functions from https://github.com/legalnonsense/elgantt/,
;; but you can accomplish the same thing with built in functions from the
;; `color’  package.  But you’ll have to read the documentation and I choose
;; not to do that right now.  Or just do it by hand.  The world is a cold 
;; dark place and you will die.  Choose the color scheme, and the means of 
;; setting it, that brings you happiness. 

  (setq org-visual-indent-color-indent
        (cl-loop for x from 1 to 5
                 for color in (elgantt--create-gradient "gray" "black" 5)
                 collect `(,x  ,(list :background (elgantt--color-rgb-to-hex color)
                                      :foreground (elgantt--color-rgb-to-hex color)
                                      :height .1 ))))

If you do not want to use custom colors, set org-visual-indent-color-indent to nil (which is the default value) and the bars will be set using org-visual-indent-pipe-face.

The line colors are loaded once when the minor mode is activated. If you experiment with the colors, you’ll have to turn org-visual-indent-mode off and on for the changes to take effect.

Please open issues for any bugs. I am still testing this and feedback is welcome.

org-visual-outline's Issues

strange indent behavior with emacs -q

I cannot explain this behavior. It is related to org-dynamic-bullets and happens with either org-visual-indent or vanilla org-indent. Can only reproduce it with emacs -q; works fine with my config. This behavior only occurs when editing the line immediately following the headline; edits on the lines following do not cause the indentation to change.

colorful indentation lines

I find this might be attractive to some users: https://discuss.logseq.com/t/css-mod-colorful-indentation-lines/229

Just a sharing with the owner and perhaps the user of org-visual-outline.

Thanks for writing this package.

org-dynamic-bullets interferes with org-mode column view

In testing with a fresh git copy of emacs (containing org-mode 9.5.2) and minimal config on Ubuntu 21.10, I have found that the org-dynamic-bullets causes problems with positioning point when a column overlay is used. Here is an example of the contents of an org file that can demonstrate this problem:

* A column
** Top node for columns view
   :PROPERTIES:
   :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
   :END:
*** TODO Example 1
*** TODO Example 2
*** DONE Example 3

After turning on org-dynamic-bullets-mode and calling the column view (C-c C-x C-c), I try to move point around but find there are entries that point skips over when navigating with the arrow keys. Turning off org-dynamic-bullets instantly restores the expected behavior, being able to navigate to any entry.

org-dynamic-bullets also for bullet lists ?

Hi,

strictly spoken, this is not an issue, more a "howto"-question...

Is there a way to enable the org-dynamic-bullets also for bullet lists, not just for headlines ?

Thank you
Uli

First indent line has leading white pixels and lines always stay black

On dark themes in doom, the outermost indent line * is significantly wider than the inner lines. It is also a different color. doom-one theme doom-gruvbox-light gives some hints i guess.

How do I fix this? I'm up to date with origin/master.

Upstream into Org.git?

Hi, rediscovering this package from your reorg repo, I wonder, have you considered upstreaming this into Org? It's a really cool feature, both the lines and the dynamic bullets, and it'd be nice to have it "permanently." Also, upstreaming it would get more eyes on it and likely help solve any potential performance issues (I haven't tried it, so I'm not saying that there are any, but libraries that do this kind of thing often have them).