#+title: Modern Org Style
#+author: Daniel Mendler
#+language: en
#+export_file_name: org-modern.texi
#+texinfo_dir_category: Emacs misc features
#+texinfo_dir_title: Org-Modern: (org-modern).
#+texinfo_dir_desc: Modern Org Style

#+html: <a href="https://www.gnu.org/software/emacs/"><img alt="GNU Emacs" src="https://github.com/minad/corfu/blob/screenshots/emacs.svg?raw=true"/></a>
#+html: <a href="https://elpa.gnu.org/packages/org-modern.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/org-modern.svg"/></a>
#+html: <a href="https://elpa.gnu.org/devel/org-modern.html"><img alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/org-modern.svg"/></a>
#+html: <a href="https://melpa.org/#/org-modern"><img alt="MELPA" src="https://melpa.org/packages/org-modern-badge.svg"/></a>
#+html: <a href="https://stable.melpa.org/#/org-modern"><img alt="MELPA Stable" src="https://stable.melpa.org/packages/org-modern-badge.svg"/></a>

* Introduction

This package implements a modern style for your Org buffers using font locking
and text properties. The package styles headlines, keywords, tables and source
blocks. The styling is configurable, you can disable or modify the style of each
syntax element individually via the =org-modern= customization group.

[[https://github.com/minad/org-modern/blob/screenshots/example.gif?raw=true]]

The screenshots shows [[file:example.org][example.org]] with =org-modern-mode= turned on and off. The
elegant theme featured in the screenshot is [[https://protesilaos.com/emacs/modus-themes][modus-operandi]].

Since this package adjusts text styling, it depends on your font settings. You
should ensure that your =variable-pitch= and =fixed-pitch= fonts combine
harmonically and have approximately the same height. As default font, I
recommend variants of the [[https://github.com/be5invis/Iosevka][Iosevka]] font, e.g., Iosevka Term Curly.
=org-modern-mode= tries to adjust the tag label display based on font height.

* Configuration

The package is available on GNU ELPA and MELPA. You can install the package with
=package-install=. Then =org-modern= can be enabled manually in an Org buffer by
invoking =M-x org-modern-mode=. In order to enable =org-modern= for all your Org
buffers, add =org-modern-mode= to the Org mode hooks.

#+begin_src emacs-lisp
;; Option 1: Per buffer
(add-hook 'org-mode-hook #'org-modern-mode)
(add-hook 'org-agenda-finalize-hook #'org-modern-agenda)

;; Option 2: Globally
(with-eval-after-load 'org (global-org-modern-mode))
#+end_src

Try the following more extensive setup in =emacs -Q= to reproduce the looks of the
screenshot above after the installation of =org-modern=.

#+begin_src emacs-lisp
;; Minimal UI
(package-initialize)
(menu-bar-mode -1)
(tool-bar-mode -1)
(scroll-bar-mode -1)
(modus-themes-load-operandi)

;; Choose some fonts
;; (set-face-attribute 'default nil :family "Iosevka")
;; (set-face-attribute 'variable-pitch nil :family "Iosevka Aile")
;; (set-face-attribute 'org-modern-symbol nil :family "Iosevka")

;; Add frame borders and window dividers
(modify-all-frames-parameters
 '((right-divider-width . 40)
   (internal-border-width . 40)))
(dolist (face '(window-divider
                window-divider-first-pixel
                window-divider-last-pixel))
  (face-spec-reset-face face)
  (set-face-foreground face (face-attribute 'default :background)))
(set-face-background 'fringe (face-attribute 'default :background))

(setq
 ;; Edit settings
 org-auto-align-tags nil
 org-tags-column 0
 org-catch-invisible-edits 'show-and-error
 org-special-ctrl-a/e t
 org-insert-heading-respect-content t

 ;; Org styling, hide markup etc.
 org-hide-emphasis-markers t
 org-pretty-entities t
 org-agenda-tags-column 0
 org-ellipsis "…")

(global-org-modern-mode)
#+end_src

Furthermore I recommend to use =line-spacing= with a value between 0.1 and 0.4 to
give the text some room to breathe. From Emacs 31, the text can be centered by
setting =line-spacing= to a pair of two numbers (see Emacs [[https://debbugs.gnu.org/cgi/bugreport.cgi?bug=76390][bug#76390]]).

* Incompatibilities

- If =org-indent-mode= is enabled, =org-modern= will disable the block
  prettification in the fringe. See the package [[https://github.com/jdtsmith/org-modern-indent][org-modern-indent]] which provides
  a different mechanism for block styling, than using the fringe.
- =org-num-mode= interferes with the =org-modern= prettification of TODO keywords.
- =visual-wrap-prefix-mode= relies on the =wrap-prefix= text property which is also
  used by =org-modern=.

* Alternatives

The tag style of =org-modern= is inspired by Nicholas Rougier's [[https://github.com/rougier/svg-tag-mode][svg-tag-mode]]. In
contrast to =svg-tag-mode=, the package =org-modern= avoids images and uses more
efficient Emacs box text properties. By only styling the text via text
properties, the styled text, e.g., dates or tags stay editable and are easy to
interact with.

The approach used here restricts the flexibility (e.g., no rounded corners) and
creates dependence on the size and alignment of the font. Combining
=org-modern-mode= with =svg-tag-mode= is possible. You can use SVG tags and use the
table and block styling from =org-modern=. If you are interested in further
tweaks, Emacs comes with the builtin =prettify-symbols-mode= which can be used for
individual styling of custom keywords.

Alternatives are the older [[https://github.com/integral-dw/org-superstar-mode][org-superstar]] and [[https://github.com/sabof/org-bullets][org-bullets]] packages, which are
more limited and mainly adjust headlines and lists. =org-superstar= relies on
character composition, while =org-modern= uses text properties, which are
considered more future-proof. Note that =org-modern= is a full replacement for
both =org-superstar= and =org-bullets=. You can disable styling of certain elements,
e.g., =org-modern-timestamp=, if you only want to use the subset of =org-modern=
equivalent to =org-superstar=.

For an alternative source block styling technique, please take a look at the
[[https://github.com/jdtsmith/org-modern-indent][org-modern-indent]] package. Org-modern-indent can even style source blocks when
=org-indent-mode= is enabled.

* Contributions

Since this package is part of [[https://elpa.gnu.org/packages/org-modern.html][GNU ELPA]] contributions require a copyright
assignment to the FSF.
