Prettify headings and plain lists in Org mode. This package is a direct descendant of ‘org-bullets’, with most of the code base completely rewritten. Currently, this package supports:
- Prettifying Org heading lines by:
- replacing trailing bullets by UTF-8 bulletsa)
- hiding leading starsb), customizing their look(new!) or removing them from vision(new!)
- applying a custom face to the header bulletd)
- applying a custom face to the leading bullets(new!)
- using double-bullets for inline tasks (see
org-inlinetask.el) - (optional) using special bullets for
TODOkeywords(new!)
- Prettifying Org plain list bullets(new!) by:
- replacing each bullet type (
*,+and-) with UTF-8 bulletsc) - applying a custom face to item bullets
- replacing each bullet type (
- Gracefully degrading features when viewed from terminal
a) These features are mostly the same as in org-bullets-mode.
b) Plain hiding is now left to Org mode and the associated
variable org-hide-leading-stars as well as org-hide, as suggested
by Kaligule.
c) org-superstar-mode tries to prettify in a context-sensitive
fashion: It strives to only recognize item bullets which are really
meant to be item bullets. Your SRC blocks are safe!
d) Instead of providing the symbol of an existing face in a variable to replace Org’s usual title face(s) for the UTF-8 character, superstar merges a custom face with the face that would have been used, allowing the user to inherit the level-dependent default look.
In this section I maintain a list of possible feature candidates.
hiding leading commas of quoted stars-
unhiding commas whilst editing- I have realized that this feature exceeds the scope of the package, being too interactive. This would require a lot of font-lock related boilerplate which I am currently in the process of dedicating it’s own package to.
- optionally display a leading bullet for inline tasks
- Please see this issue.
The package is available on MELPA!
If you prefer a manual installation, just plug org-superstar.el into
your load path and add the following to your .emacs:
(require 'org-superstar)
(add-hook 'org-mode-hook (lambda () (org-superstar-mode 1)))A variety of customization features has been added to allow further tweaking. Suggestions are always welcome!
NOTE: Many of the variables listed below require you to restart
org-superstar-mode to take effect. See the corresponding variable’s
documentation.
Naturally! In fact, I made the answer to this it’s own function:
This function configures superstar-mode to be as similar to
org-bullets as possible. Since this function automatically sets
various custom variables, it should only be called once per
session, before any other (manual) customization of this package.
org-superstar-configure-like-org-bullets is only meant as a small
convenience for people who just want minor departures from
org-bullets-mode. For a more fine-grained customization, it’s
better to just set the variables you want.
Here’s how you change which bullets are used for which level.
Those of you familiar with org-bullets will be recognize this
list: It’s a list of single-character strings where the Nth entry
is used to determine the bullet used for heading level N. By
default, this list is cycled through for N greater than the length
of the list.
This variable gives you more control over how superstar-mode picks
headline bullets. The default, t, cycles through the list as
explained above. Other values are:
nil- Go through the list, then repeat the last entry indefinitely.
- any integer k
- Cycle through the first k elements of the list.
Maybe you actually like that Org’s heading lines are connected to
the left margin, but you find a line of stars too visually busy?
Enter org-superstar-leading-bullet. Provide a character of your
choice to be displayed instead. Strings are superimposed
according to the rules of compose-region. org-superstar ships
with a subtle leader as the default.
Note for terminal users: You can apply a simplified composition to
leading stars for terminal sessions. See
org-superstar-leading-fallback for details.
Since org-mode already takes care of hiding leading stars by
providing the dedicated variable org-hide-leading-stars and it’s
associated face org-hide, there is no extra option for hiding
leading stars like that. Instead, org-hide-leading-stars
implicitly disables further fontification.
While there is no explicit feature for hiding leading stars, you
can also use org-superstar-leading-bullet to hide leading stars
independently of org-hide: Simply choose a space character as your
leading bullet.
;; This is usually the default, but keep in mind it must be nil
(setq org-hide-leading-stars nil)
;; This line is necessary.
(setq org-superstar-leading-bullet ?\s)If you want to get rid of the indentation caused by leading stars
entirely, set org-superstar-remove-leading-stars to t.
You can substitute standard headline bullets with specialized ones
fitting the current TODO keyword! To enable this feature, set
org-superstar-special-todo-items to t. To set which TODO keywords
you want to have displayed differently, see
org-superstar-todo-bullet-alist.
Why stop at heading lines? Customize the look of your list bullets to make plain lists a little less so.
Since the concept of “levels” does not really apply to lists, this association list simply assigns a UTF-8 character to each of the three possible bullet characters for plain Org lists.
Exactly as it says on the tin. Set this variable to nil to stop
org-superstar-mode from prettifying lists.
The default syntax-checking done to ensure only actual plain list
items are prettified is rather expensive, but usually not
expensive enough to cause significant slowdown. This can change
when dealing with Org files containing hundreds or even thousands
of plain list items. The command
org-superstar-toggle-lightweight-lists allows the user to disable
syntax checking for plain lists both interactively and in code.
For example, if you experience issues for files with more than 100
list items, you could simply add the following to org-mode-hook
instead of a direct call to org-superstar-mode:
(defun my-auto-lightweight-mode ()
"Start Org Superstar differently depending on the number of lists items."
(let ((list-items
(count-matches "^[ \t]*?\\([+-]\\|[ \t]\\*\\)"
(point-min) (point-max))))
(unless (< list-items 100)
(org-superstar-toggle-lightweight-lists)))
(org-superstar))
(add-hook 'org-mode-hook #'my-auto-lightweight-mode)These faces allow you to further manipulate the look and feel of prettified bullets.
A face containing essentially the difference between the default
heading face for the given level (like org-level-1) and the
bullet. This face is completely unspecified by default. Any
property set will override the corresponding face property of
org-level-N.
A face used to display leading stars if
org-superstar-prettify-leading-stars is enabled.
A face used to display prettified plain list bullets if
org-superstar-prettify-item-bullets is enabled.
I have looked into the matter in the past, and from what I
understand the usual cause of this is relates to a deeper rooted
issue involving fonts and font-lock reliant packages. I recommend
adding the following to your .emacs:
(setq inhibit-compacting-font-caches t)or any more fancy variation thereof. This variable also holds further information regarding what I believe is the cause of the problem. If this should not fix the problem, please consider opening an issue or sending me a mail!
By default, Org Superstar does expensive syntax checking to ensure
plain lists are actual plain lists. This is usually not an issue
for small files. However, this may pose a problem when your file
contains hundreds or thousands of items! You can deal with this
interactively using the command
org-superstar-toggle-lightweight-lists. See also the subsection
”Fast Plain List Items” above.
While Org Bullet mode ships only with a feature to hide leading
stars, Org Superstar allows you to customize leading stars to still
provide some visual guidance without causing too much visual noise.
For more information on this topic, see the Section Customization
above, in particular the subsections org-superstar-leading-bullet
and Hide leading stars.
Version 1.2.0 is now available. This version adds support for
using advanced features of compose-region for TODO item bullets.
Also, the package’s downloads doubled in less than two weeks, meaning Org Superstar now has over 1000 downloads on MELPA! I have given the whole situation some more thought, and decided that I will contact the Spacemacs team should we reach 2000 downloads this year, which I would consider enough proof of the package’s popularity.
Good news! The project is reaching an acceptable first draft state. This means I am now preparing getting this package properly wrapped up and published on MELPA, with a side goal of trying to also be available on ELPA. My conservative estimate for at least being available on MELPA is roughly by the end of this month.
Everything went better than expected! The tests seem to cover most use cases now, and it seems I have added proper terminal support.
I set up a pull request, we will see how this goes.
Version 0.3.0 is out and tagged for your convenience. I am now content enough with the package to “freeze” elements of the API for good and move to version 1.0.0 once the pull request is closed. I will keep the “under construction” tags around for the time being, however.
Version 0.4.0 has been released! You can now associate TODO
keywords with special headline bullets.
Version 0.5.0 now supports a new kind of way to hide leading
bullets: Instead of using org-hide, setting
org-superstar-remove-leading-stars allows you hide them akin to
emphasis markers (see org-hide-emphasis-markers).
Version 1.0.0 has been released! With this I consider the package as ready for use as it gets. The change primarily means that:
- I will try my best not to break backwards compatibility.
- If I conclude that I have to, I will not do it silently. Instead, you can rely on appropriate warnings.
- Even then, a backwards incompatible change will result it a major version number change.
The package is now available on MELPA! My sincerest thanks to all the people on GitHub and the Org mailing list that helped me along! I would not have managed without you! :)
A minor status update. We cracked the 500 downloads mark on MELPA! Unbelievable! Thank you all for your support! Should we reach the 1-2000 downloads mark by the end of the year, I will consider contacting major Emacs releases shipping with org-bullets, such as Spacemacs or Doom.
In other news, version 1.1.0 is now available, providing a few minor fixes, as well as a new feature to disable expensive syntax checks for plain list items. See the FAQ for more info.