Nice Org to HTML pipeline

Get the source files on your load path. E.g. with MELPA and use-package:

(require 'package)
(add-to-list 'package-archives
             '("melpa" . "http://melpa.org/packages/"))
(package-initialize)

(unless (package-installed-p 'use-package)
  (package-install 'use-package))

Add something like this to your configuration file:

(use-package nice-org-html
  :hook (org-mode . nice-org-html-mode)
  :config
  (setq nice-org-html-theme-alist
        '((light . solo-jazz)
          (dark  . tomorrow-night-eighties)))
  (setq nice-org-html-default-mode 'dark)
  (setq nice-org-html-headline-bullets nil) 

• Themes: tsdh-light and tsdh-dark distributed with GNU Emacs
• Default viewing mode: 'query
  • This will check against the visitor's browser-set preference, and default to 'dark if no preference is specified. Anti-fingerprinting settings may prevent reading the browser setting, or cause the browser to mask it (usually, by showing a preference for 'light).
• Headline bullets: 'nil – i.e. bullets will not be prefixed to headlines

  • To prefix headlines with the default bullets, instead use:

    EMACS-LISP⧉

    (setq nice-org-html-headline-bullets t)
    

  • Or you can specify headline bullets with a plist like this (the defaults):

    EMACS-LISP⧉

    (setq nice-org-html-headline-bullets
          '(:h1 "◉" :h2 "✸" :h3 "▷" :h4 "⦁" :h5 "○"))
    

• Admonitions are rendered from these org special blocks: _note, _tip, _important, _warning, _caution

  Note

  This is a note

  Tip

  This is a tip

  Warning

  This is a warning

  Important

  This is important

  Caution

  This is a caution

• The colours of these blocks can be custom-set to hex values by modifying the variable nice-org-html-clr-defs:

  ELISP⧉

  (setq nice-org-html-clr-defs
        ((light . (:note "#0969da" :tip "#1a7f37" :important "#8250df" :warning "#9a6700" :caution "#cf222e"))
         (dark  . (:note "#0969da" :tip "#1a7f37" :important "#8250df" :warning "#9a6700" :caution "#cf222e"))))
  

  or declaring some value(s) for :clr-defs in a call to the nice-org-html-publishing-function macro, discussed below.

Further look-and-feel customization is handled through the nice-org-html-options plist. The following properties and values are supported (so far):

• CSS and JS must be paths (strings) to files with contents to be injected.
• Header and footer may be a path to an HTML file, or a list of cons pairs.

• A default HTML structure will be used for the header and/or footer, if a list of this form:

  EMACS-LISP⧉

  '(("left" . uri0) ("link1" . "uri1") ... ("linkN" . "uriN"))
  

  • left will be displayed as anchor text, and hyperlinked if uri0 is non-nil.
  • link1 … linkN will be hyperlinks, collapsed into a drawer for mobile viewers.

These variables may also be set globally, and then used or overridden during interactive export. For example:

(setq nice-org-html-header
      '(("title" . "/home.html")
        ("foo" . "/foo.html") ("bar" . "/bar.html")))
;; Or: (setq nice-org-html-header "path/to/your/header.html")

(setq nice-org-html-footer
      '(("© author" . "mailto:a@b.c")
        ("oof" . "https://oof.a") ("rab" . "https://rab.b")))
;; Or: (setq nice-org-html-header "path/to/your/footer.html")

(setq nice-org-html-css "path/to/your/style.css")

(setq nice-org-html-js "path/to/your/script.js")

(setq nice-org-html-options '(:layout "compact" :collapsing t))

This package is particularly well-suited to publishing Org projects, as websites comprised of many linked pages. The included publishing function, nice-org-html-publish-to-html, relies on global values for all of the above variables. To use it, in specifying the value of org-publish-projects-alist, for a given project just specify:

;; ...
:publishing-function #'nice-org-html-publish-to-html
;; ...

For more granular per-project configuration, there is a publishing-function-generating macro, nice-org-html-publishing-function, which takes values for the above configuration variables, and defines a publishing function unique to that invocation. Note: the options plist is constructed out of remaining arguments to this macro, so options should be specified directly. For example, your per-project configuration - i.e. the value of org-publish-projects-alist - may look something like this:

`(("project-x/files"
   :base-extension "org"
   :base-directory "path/to/source-x/"       
   :publishing-directory "path/to/target-x/"
   ;; ...
   :publishing-function
   ,(nice-org-html-publishing-function
     :theme-alist ((light . spacemacs-light) (dark . spacemacs-dark))
     :default-mode dark
     :headline-bullets (:h1 "" :h2 "✸" :h3 "▷" :h4 "" :h5 "")
     :clr-defs ((light . (:note "#ffc0cb"))     ;; notes pink in light mode
                (dark  . (:warning "#ff4800"))) ;; warnings orange in dark mode         
     :header "path/to/your/header.html"
     :footer "path/to/your/footer.html"
     :css "path/to/your/style.css"
     :js "path/to/your/script.js"
     :layout "compact"
     :collapsing t)))

• Any variable for which values are not specified will take the global (or default) value.