https://github.com/integral-dw/org-superstar-mode

Make org-mode stars a little more super
https://github.com/integral-dw/org-superstar-mode

emacs emacs-package org-mode org-mode-configuration

Last synced: 3 days ago
JSON representation

Make org-mode stars a little more super

• Host: GitHub
• URL: https://github.com/integral-dw/org-superstar-mode
• Owner: integral-dw
• License: gpl-3.0
• Created: 2020-01-30T20:24:19.000Z (almost 5 years ago)
• Default Branch: master
• Last Pushed: 2023-03-03T13:40:44.000Z (over 1 year ago)
• Last Synced: 2024-05-08T16:19:18.426Z (6 months ago)
• Topics: emacs, emacs-package, org-mode, org-mode-configuration
• Language: Emacs Lisp
• Homepage:
• Size: 689 KB
• Stars: 485
• Watchers: 11
• Forks: 20
• Open Issues: 19
• Metadata Files:
  • Readme: README.org
  • License: LICENSE

Awesome Lists containing this project

README

        
#+TITLE: org-superstar-mode

#+STARTUP: showeverything

[[https://melpa.org/#/org-superstar][file:https://melpa.org/packages/org-superstar-badge.svg]] [[https://stable.melpa.org/#/org-superstar][file:https://stable.melpa.org/packages/org-superstar-badge.svg]]

[[file:sample_image.png]]

* About

  Prettify headings and plain lists in Org mode.  This package is a

  direct descendant of ‘[[https://github.com/sabof/org-bullets][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 bullets^{a)}

   + hiding leading stars^{b)}, customizing their look^{(new!)} or removing

     them from vision^{(new!)}

   + applying a custom face to the header bullet^{d)}

   + applying a custom face to the leading bullets^{(new!)}

   + making inline tasks (see =org-inlinetask.el=) more fancy by:

     - using double-bullets for inline tasks

     - applying a custom face to the marker star of inline tasks^{(new!)}

     - using a special bullet for the marker star^{(new!)}

     - introducing an independent face for marker stars^{(new!)}

   + (optional) using special bullets for =TODO= keywords^{(new!)}

 * Prettifying Org plain list bullets^{(new!)} by:

   + replacing each bullet type (~*~, ~+~ and ~-~) with UTF-8 bullets^{c)}

   + applying a custom face to item bullets

 * 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 [[https://github.com/Kaligule][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.

** Planned features

   There are currently no new features planned. For the time being

   only one historically planned feature remains listed, which is

   supposed to develop into a sister project.  See below.

   * +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 its own package to.

       - Update :: The package in question has matured, but suffers

                   from intricate timing errors which will require

                   looking into.  Especially since they are so far

                   impossible to test reliably due to their nature.

** Demos

   You can find a small demo reel with a variety of configurations

   [[file:DEMO.org][here]].

* Installation

  The package is available [[https://melpa.org/#/org-superstar][on MELPA]]!

  Furthermore, it ships with [[https://github.com/syl20bnr/spacemacs][Spacemacs]] and [[https://github.com/hlissner/doom-emacs][Doom Emacs]].

  If you prefer a manual installation, just plug =org-superstar.el= into

  your load path and add the following to your =.emacs=:

#+BEGIN_SRC elisp

(require 'org-superstar)

(add-hook 'org-mode-hook (lambda () (org-superstar-mode 1)))

#+END_SRC

* Customization

  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.

** "Can you make it more like =org-bullets=?"

   Naturally!  In fact, I made the answer to this its own function:

*** ~org-superstar-configure-like-org-bullets~

    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.

** "Where do I find UTF8-bullets to use?"

   While it strongly depends on the font(s) you are using which

   characters are going to be supported, here are some nifty Unicode

   blocks to consider.  I sorted them by the respective Unicode plane.

   * Basic Multilingual Plane (U+0000-U+FFFF) :: As the name suggests,

        the Unicode plane containing most languages, and hence the

        most commonly encoded.  I recommend the following blocks:

     + [[https://en.wikipedia.org/wiki/General_Punctuation][General Punctuation]] (U+2000-U+206F) :: Bullets, leaders, asterisms.

     + [[https://en.wikipedia.org/wiki/Dingbat#Unicode][Dingbats]] (U+2700-U+27BF) :: Common typesetting ornaments.

     + [[https://en.wikipedia.org/wiki/Geometric_Shapes][Geometric Shapes]] (U+25A0-U+25FF) :: Circles, shapes within

          shapes, etc.

     + [[https://en.wikipedia.org/wiki/Miscellaneous_Symbols][Miscellaneous Symbols]] (U+2600–U+26FF) :: Smileys and card suits.

     + [[https://en.wikipedia.org/wiki/Miscellaneous_Symbols_and_Arrows][Miscellaneous Symbols and Arrows]] (U+2B00-U+2BFF) ::

           Further stars and arrowheads, polygons, etc.

   * Supplementary Multilingual Plane (U+10000-U+1FFFF) ::  This one

        contains (among other things) Emoji and plenty of symbols.

     + [[https://en.wikipedia.org/wiki/Ornamental_Dingbats][Ornamental Dingbats]] (U+1F650-U+1F67F) :: A few more ornaments,

          some quotation marks and fancy ampersands.

     + [[https://en.wikipedia.org/wiki/Geometric_Shapes_Extended][Geometric Shapes Extended]] (U+1F780-U+1F7FF) ::

          Even more geometric shapes and shapes within shapes, but

          also asterisk variations.

     + [[https://en.wikipedia.org/wiki/Supplemental_Arrows-C][Supplemental Arrows-C]] (U+1F800-U+1F8FF) :: A collection of chunky

           arrows.

** Custom UTF8-bullets for heading lines

   Here's how you change which bullets are used for which level.

*** ~org-superstar-headline-bullets-list~

    Those of you familiar with =org-bullets= will 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.  Strings are not the only valid way to provide

    headline bullets, however.  Since version *1.3.0*, this variable

    also recognizes characters as well as specific lists, with

    characters being the new default way of providing bullets.  Lists

    on the other hand provide the user with the means to access

    advanced composition features and fallback options for terminal

    users.

*** ~org-superstar-cycle-headline-bullets~

    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.

*** ~org-superstar-leading-bullet~

    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 [[https://en.wikipedia.org/wiki/Leader_(typography)][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.

*** ~org-superstar-first-inlinetask-bullet~

    This bullet replaces the red star inline tasks use when

    ~org-inlinetask-show-first-star~ is non-nil.  Strings are

    superimposed according to the rules of ~compose-region~, characters

    render as expected.

    *Note for terminal users:* You can apply a simplified composition

    for terminal sessions.  See

    ~org-superstar-first-inlinetask-fallback~ for details.

*** Hide leading stars

    Since ~org-mode~ already takes care of hiding leading stars by

    providing the dedicated variable ~org-hide-leading-stars~ and its

    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.

    #+BEGIN_SRC emacs-lisp

      ;; 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 use Org Indent you also need to add this, otherwise the

      ;; above has no effect while Indent is enabled.

      (setq org-indent-mode-turns-on-hiding-stars nil)

    #+END_SRC

    If you want to get rid of the indentation caused by leading stars

    entirely, set ~org-superstar-remove-leading-stars~ to ~t~.

*** Fancy =TODO= items

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

*** No =TODO= bullets

    If you prefer a more minimal look for =TODO= items, try setting

    ~org-superstar-special-todo-items~ to the symbol ~hide~.  This causes

    the heading bullet to disappear entirely for =TODO= items.

** Custom UTF8-Bullets for plain lists

   Why stop at heading lines?  Customize the look of your list bullets

   to make plain lists a little less so.

*** ~org-superstar-item-bullet-alist~

    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.

*** ~org-superstar-prettify-item-bullets~

    Exactly as it says on the tin.  Set this variable to ~nil~ to stop

    ~org-superstar-mode~ from prettifying lists.  If set to the symbol

    ~only~, this disables prettifying Org headings entirely.

*** Fast Plain List Items

    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~:

    #+BEGIN_SRC emacs-lisp

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

    #+END_SRC

** Custom faces

   These faces allow you to further manipulate the look and feel of

   prettified bullets.

*** ~org-superstar-header-bullet~: "Use ~org-level-N~, but..."

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

*** ~org-superstar-leading~

    A face used to display leading stars if

    ~org-superstar-prettify-leading-stars~ is enabled.

*** ~org-superstar-item~

    A face used to display prettified plain list bullets if

    ~org-superstar-prettify-item-bullets~ is enabled.

*** ~org-superstar-first~

    A face used for the marker star of inline tasks (see the package

    ~org-inlinetask~, in particular ~org-inlinetask-show-first-star~

    instead of the default ~org-warning~, which it inherits from by

    default.

* FAQ / Troubleshooting

** "Question marks everywhere!  Help!"

   Did you enable this mode for example in a terminal session and have

   been greeted by wonky replacement characters like ‘�’ or plain

   question marks in headlines or items?  Try turning

   ~org-superstar-mode~ off to see what its /supposed/ to be if it is too

   visually broken to recognize.  The fix depends on whether you are

   experiencing this on a graphical or terminal display.

*** Question mark salad on terminal

    This usually happens because the font of your terminal does not

    have a glyph for a bullet character you are using.  There are two

    plausible fixes:

    1) *Change your terminal font:* Emacs has no control over the font

       of your terminal display.  As a consequence, if you want to

       keep these particular bullets, your best bet is to change the

       font.  For example, the default settings should work out of the

       box for the excellent *DejaVu Sans Mono*.

    2) *Utilize terminal fallback options:* Org Superstar is written

       with terminal users in mind.  Hence you can roll an entirely

       different set of bullets for terminal sessions without much

       effort.  Leading stars have ~org-superstar-leading-fallback~.

       Headline bullets themselves can be declared independently for

       graphical and terminal displays in

       ~org-superstar-headline-bullets-list~.  For example, replacing an

       entry ~?◉~ with the entry ~("◉" ?*)~ will make the headline bullet

       that would normally display as ‘◉’ a plain asterisk on terminal

       displays.

    3) *Replace the bullet character altogether:* A valid option, but

       likely not the most desirable.  Check out the documentation for

       more info on how to customize this package.

*** Borked even in graphical sessions

    In this case it is all up to your Emacs configuration.  The

    problem remains the fonts available, this time to Emacs.  You can

    either [[https://www.emacswiki.org/emacs/SetFonts][change your Emacs font]] or specify specific fonts for

    specific Unicode character ranges, which is part of Emacs'

    intricate face system.

** "This mode causes significant slowdown!"

   I have looked into the matter [[https://github.com/integral-dw/org-superstar-mode/issues/3][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=:

   #+BEGIN_SRC emacs-lisp

   (setq inhibit-compacting-font-caches t)

   #+END_SRC

   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!

*** "I experience lag when working with long plain lists!"

    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.

** "I get an error when trying to use it."

   This of course should not happen.  If your problem is not listed

   below, please file a bug report!

*** Unknown function: ~org-element-lineage~

    This is one of the functions my package relies on missing in older

    versions of Org.  The following hack should circumvent the issue,

    at the cost of the package treating some comments in code blocks

    as lists.  Just put it in your ~.emacs~ before loading up the

    package.  If I messed up and this does not fix the problem, be

    sure to open an Issue!

    #+BEGIN_SRC emacs-lisp

      (setq-default org-superstar-lightweight-lists t)

      (defun org-element-lineage (x)

        "Mock function for future Org feature."

        nil)

    #+END_SRC

** "What are these weird points in front of heading bullets?"

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

* NEWS

** =2021-02-16=

   *1.5.0* has been released, adding support for hiding TODO item

   bullets as well as specifying a default bullet.  As for the plans

   for *2.0.0*: after lots of deliberation I have come to the conclusion

   that there is no currently scheduled change that would justify a

   major version number change.

** =2021-02-11=

   Since I have been asked whether there is a way to extend Superstar

   to other minor modes.  The bad news is: no, not feasibly.  The good

   news is: I have created a comparably simple template for this exact

   purpose for other people to bring a Superstar-like mode to your

   favorite Outline-type of mode: [[https://github.com/integral-dw/superstar-kit][Superstar Kit]]!

   Also: Earlier this month, Superstar has reached over 65536 (2^{16})

   downloads!  Again, thank you!

* Announcement Log

** =2020-02-02=

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

** =2020-02-03=

   Everything went better than expected!  The tests seem to cover most

   use cases now, and it seems I have added proper terminal support.

** =2020-02-04=

   I set up a pull request, we will see how this goes.

** =2020-02-15=

   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.

** =2020-02-16=

   Version *0.4.0* has been released!  You can now associate =TODO=

   keywords with special headline bullets.

** =2020-02-17=

   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=).

** =2020-02-26=

   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.

** =2020-03-08=

   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! :)

** =2020-04-01=

   A minor status update.  [[https://melpa.org/#/org-superstar][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.

** =2020-04-14=

   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 [[https://melpa.org/#/org-superstar][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.

** =2020-08-08=

   Version *1.3.0* is here!  This version adds support for using

   advanced features of ~compose-region~ for headline bullets, thus

   continuing efforts to make the package more visually coherent for

   general setups while remaining terminal friendly.

   In other news, Org Superstar reached [[https://melpa.org/#/org-superstar][over 16000 downloads on MELPA]]!

   This is absolutely insane, and already surpasses my hopes for this

   year by more than a factor of 8!  I am speechless.  And, as

   promised, +I will contact the Spacemacs team sometimes this year.+

   Turns out, Org Superstar [[https://github.com/syl20bnr/spacemacs/issues/13831][replaced Org Bullets]] as of the 7th of June

   on Spacemacs' ~develop~ branch!  And it also ships with [[https://github.com/hlissner/doom-emacs][Doom Emacs]]!

   With that, I have essentially reached every goal I had for this

   package.  However, I will naturally continue maintenance and remain

   open towards feature suggestions.

** =2020-08-29=

   org-superstar has reached over 32768 (2^{15}) downloads this week!

   This is absolutely amazing.  If there is any room for improvement,

   I'm very open to suggestions from the community!

** =2020-08-18=

   We have reached version *1.4.0*, which concludes the series of

   feature updates I have planned out.  In other words, this package

   has reached a point of maturity where I would consider it complete.

   This does /not/ mean that no new features will be added/accepted, but

   it does mean that I will from now on rely on feature suggestions

   from the community, and focus on maintenance rather than

   innovation.  The next scheduled update (*2.0.0*) will likely involve

   a subtle revamp of the default values.  I will keep you posted.

#  LocalWords:  Org's MELPA ELPA Worg fontification TODO README UTF Spacemacs

#  LocalWords:  Org fallback setups asterisms Emoji Smileys Borked