ui/doom-dashboard: expand README #1166

modules/ui/doom-dashboard/README.org

@@ -1,20 +1,63 @@
 #+TITLE:   ui/doom-dashboard
 #+DATE:    October 9, 2019
 #+SINCE:   v1.3
-#+STARTUP: inlineimages
+#+STARTUP: inlineimages nofold
 
 * Table of Contents :TOC_3:noexport:
 - [[#description][Description]]
   - [[#module-flags][Module Flags]]
 - [[#prerequisites][Prerequisites]]
+- [[#configuration][Configuration]]
+  - [[#a-custom-banner][A custom banner]]
+  - [[#adding-text-to-the-dashboard][Adding text to the dashboard]]
 
 * Description
-This module gives Doom Emacs a dashboard buffer.
+This module adds a minimalistic, Atom-inspired dashboard to Emacs.
 
-It is loosely inspired by Atom's dashboard.
+Besides eye candy, the dashboard serves two other purposes:
+
+1. To improve Doom's startup times (the dashboard is lighter than the scratch
+   buffer in many cases).
+
+2. And to preserve the "last open directory" you were in. Occasionally, I kill
+   the last buffer in my project and I end up who-knows-where (in the working
+   directory of another buffer/project). It can take some work to find my way
+   back to where I was. Not with the Dashboard.
+
+   Since the dashboard cannot be killed, and it remembers the working directory
+   of the last open buffer, ~M-x find-file~ will work from the directory I
+   expect.
 
 ** Module Flags
 This module provides no flags.
 
 * Prerequisites
-This module only requires that ~all-the-icons~'s icon fonts are installed. Use ~M-x all-the-icons-install-fonts~ to do so.
+This module only requires that ~all-the-icons~'s icon fonts are installed.
+
+It should've been installed when you first installed Doom, but ~M-x
+all-the-icons-install-fonts~ will install them again.
+
+* Configuration
+** A custom banner
+To use a custom image as your banner, change ~fancy-splash-image~:
+
+#+BEGIN_SRC elisp
+(setq fancy-splash-image "~/my/banners/image.png")
+#+END_SRC
+
+#+begin_quote
+Doom will fall back to its ASCII banner in Terminal Emacs. To replace the ASCII
+banner, replace the ~doom-dashboard-widget-banner~ function in
+~+doom-dashboard-functions~ with a function that inserts your new banner into
+the current file.
+#+end_quote
+
+** Adding text to the dashboard
+Doom's dashboard iterates over ~+doom-dashboard-functions~ when it is told to
+redraw. Add your own functions to operate on the buffer and potentially add
+whatever you like to Doom's splash screen.
+
+#+begin_quote
+Keep in mind that inserting text from expensive sources, e.g. your org agenda,
+will negate most of Doom's startup benefits.
+#+end_quote