doomemacs/modules/ui/doom-dashboard/README.org

#+title:    :ui doom-dashboard
#+subtitle: Welcome to your doom
#+created:  February 20, 2017
#+since:    2.0.0

* Description :unfold:
This module adds a minimalistic, Atom-inspired dashboard to Emacs.

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.

** Maintainers
- [[doom-user:][@hlissner]]

[[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
/This module has no flags./

** Packages
/This module doesn't install any packages./

** Hacks
/No hacks documented for this module./

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

This module only requires that ~nerd-icons~'s icon fonts are installed, which
should've been installed when you ran ~$ doom install~. Otherwise, use ~M-x
nerd-icons-install-fonts~ to install them.

* Usage
Once this module is enabled, the dashboard will present itself after opening a
fresh instance of Emacs, or after killing all real buffers.

You can forcibly open the dashboard with ~M-x +doom-dashboard/open~.

* TODO Configuration
#+begin_quote
 󱌣 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** A custom banner
To use a custom image as your banner, change ~fancy-splash-image~:
#+begin_src emacs-lisp
(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

** Customizing Faces
Doom's dashboard defaults to inheriting faces set by the current theme. If you
wish to customize it independently of the theme (or just inherit a different
color from the theme) you can make use of ~custom-set-faces!~ or
~custom-theme-set-faces!~:
#+begin_src emacs-lisp
(custom-set-faces!
  '(doom-dashboard-banner :foreground "red" :background "#000000" :weight bold)
  '(doom-dashboard-footer :inherit font-lock-constant-face)
  '(doom-dashboard-footer-icon :inherit nerd-icons-red)
  '(doom-dashboard-loaded :inherit font-lock-warning-face)
  '(doom-dashboard-menu-desc :inherit font-lock-string-face)
  '(doom-dashboard-menu-title :inherit font-lock-function-name-face))
#+end_src

or for a per-theme setting
#+begin_src emacs-lisp
(custom-theme-set-faces! 'doom-tomorrow-night
  '(doom-dashboard-banner :foreground "red" :background "#000000" :weight bold)
  '(doom-dashboard-footer :inherit font-lock-constant-face)
  '(doom-dashboard-footer-icon :inherit nerd-icons-red)
  '(doom-dashboard-loaded :inherit font-lock-warning-face)
  '(doom-dashboard-menu-desc :inherit font-lock-string-face)
  '(doom-dashboard-menu-title :inherit font-lock-function-name-face))
#+end_src

* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 󱌣 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote