[[https://www.gnu.org/licenses/gpl-3.0][https://img.shields.io/badge/License-GPL%20v3-blue.svg]]
[[https://jcs-emacs.github.io/jcs-elpa/#/dashboard][https://raw.githubusercontent.com/jcs-emacs/badges/master/elpa/v/dashboard.svg]]
[[https://melpa.org/#/dashboard][https://melpa.org/packages/dashboard-badge.svg]]
[[https://stable.melpa.org/#/dashboard][https://stable.melpa.org/packages/dashboard-badge.svg]]

* Emacs Dashboard

[[https://github.com/emacs-dashboard/emacs-dashboard/actions/workflows/test.yml][https://github.com/emacs-dashboard/emacs-dashboard/workflows/CI/badge.svg]]
[[https://github.com/emacs-dashboard/emacs-dashboard/actions/workflows/activate.yml][https://github.com/emacs-dashboard/emacs-dashboard/workflows/Activate/badge.svg]]

An extensible emacs startup screen showing you what's most important.

* Features
  1. Displays an awesome Emacs banner!
  2. Recent files
  3. Bookmarks list
  4. Recent projects list (Depends on `projectile` or `project.el` package)
  5. Org mode agenda
  6. Register list
  7. Supports both [[https://github.com/domtronn/all-the-icons.el][all-the-icons]] and [[https://github.com/rainstormstudio/nerd-icons.el][nerd-icons]]

* Screenshot

[[./etc/screenshot.png]]

* Dependencies
You will need the following packages which are all available on Melpa:

1. (optional) page-break-lines - [[https://github.com/purcell/page-break-lines]]
2. (optional) projectile - [[https://github.com/bbatsov/projectile]]
3. (optional) all-the-icons - [[https://github.com/domtronn/all-the-icons.el]]
4. (optional) nerd-icons - [[https://github.com/rainstormstudio/nerd-icons.el]]

* Usage

#+BEGIN_SRC shell
M-x package-install RET dashboard
#+END_SRC

** Open the Dashboard
You can set up the dashboard to open automatically at startup using =dashboard-setup-startup-hook=:
 #+BEGIN_SRC elisp
(require 'dashboard)
(dashboard-setup-startup-hook)
;; Or if you use use-package
(use-package dashboard
  :ensure t
  :config
  (dashboard-setup-startup-hook))
 #+END_SRC

Alternatively, if you don't want the dashboard to open by default, you can use the interactive function =dashboard-open= to open it when you do want it.

By default, the dashboard will show three lists, recent files and bookmarks and org-agenda items.

The widget “projects”, which shows a list of recent projects, is not enabled
by default since it depends on packages that might not be available.  To
activate the widget, set the variable =dashboard-projects-backend= to either
='projectile= (projectile, available from melpa) or ='project-el= (project.el,
available from GNU elpa), then add an entry like
=(projects . 5)= to the variable =dashboard-items=.

The function =dashboard-refresh-buffer= (an alias for =dashboard-open=) can be used to visit and refresh the dashboard.

** Emacs Daemon

In addition to the above, configure =initial-buffer-choice= to show
Dashboard in frames created with =emacsclient -c= as follows:

#+BEGIN_SRC elisp
(setq initial-buffer-choice (lambda () (get-buffer-create "*dashboard*")))
#+END_SRC

* Configuration

To update the banner or banner title

#+BEGIN_SRC elisp
;; Set the title
(setq dashboard-banner-logo-title "Welcome to Emacs Dashboard")
;; Set the banner
(setq dashboard-startup-banner [VALUE])
;; Value can be
;; - nil to display no banner
;; - 'official which displays the official emacs logo
;; - 'logo which displays an alternative emacs logo
;; - 1, 2 or 3 which displays one of the text banners
;; - "path/to/your/image.gif", "path/to/your/image.png" or "path/to/your/text.txt" which displays whatever gif/image/text you would prefer
;; - a cons of '("path/to/your/image.png" . "path/to/your/text.txt")

;; Content is not centered by default. To center, set
(setq dashboard-center-content t)

;; To disable shortcut "jump" indicators for each section, set
(setq dashboard-show-shortcuts nil)
#+END_SRC

To customize which widgets are displayed, you can use the following snippet
#+BEGIN_SRC elisp
(setq dashboard-items '((recents  . 5)
                        (bookmarks . 5)
                        (projects . 5)
                        (agenda . 5)
                        (registers . 5)))
 #+END_SRC
This will add the recent files, bookmarks, projects, org-agenda and registers widgets to your dashboard each displaying 5 items.

To add your own custom widget is pretty easy, define your widget's callback function and add it to `dashboard-items` as such:
#+BEGIN_SRC elisp
(defun dashboard-insert-custom (list-size)
  (insert "Custom text"))
(add-to-list 'dashboard-item-generators  '(custom . dashboard-insert-custom))
(add-to-list 'dashboard-items '(custom) t)
 #+END_SRC

To add an icon to a custom widget, insert it with `dashboard-insert-heading` in your custom function.  In this example, there is an icon but no shortcut.
#+BEGIN_SRC elisp
(defun dashboard-insert-custom (list-size)
  (dashboard-insert-heading "News:"
                            nil
                            (all-the-icons-faicon "newspaper-o"
                                                  :height 1.2
                                                  :v-adjust 0.0
                                                  :face 'dashboard-heading))
  (insert "\n")
  (insert "    Custom text"))
 #+END_SRC

To modify the widget heading name:
#+BEGIN_SRC elisp
  (setq dashboard-item-names '(("Recent Files:" . "Recently opened files:")
                               ("Agenda for today:" . "Today's agenda:")
                               ("Agenda for the coming week:" . "Agenda:"))
#+END_SRC

To use ~all-the-icons~ package:
#+BEGIN_SRC emacs-lisp
  (setq dashboard-icon-type 'all-the-icons) ;; use `all-the-icons' package
#+END_SRC

To use ~nerd-icons~ package:
#+BEGIN_SRC emacs-lisp
  (setq dashboard-display-icons-p t) ;; display icons on both GUI and terminal
  (setq dashboard-icon-type 'nerd-icons) ;; use `nerd-icons' package
#+END_SRC

To add icons to the widget headings and their items:
#+BEGIN_SRC elisp
  (setq dashboard-set-heading-icons t)
  (setq dashboard-set-file-icons t)
#+END_SRC

To modify heading icons with another icon from all-the-icons octicons:
#+BEGIN_SRC elisp
  (dashboard-modify-heading-icons '((recents . "file-text")
                                    (bookmarks . "book")))
#+END_SRC

To modify heading icons with another icon from nerd-icons octicons:
#+BEGIN_SRC emacs-lisp
  (dashboard-modify-heading-icons '((recents . "nf-oct-file_text")
                                    (bookmarks . "nf-oct-book")))
#+END_SRC

To show navigator below the banner:
#+BEGIN_SRC emacs-lisp
(setq dashboard-set-navigator t)
#+END_SRC

To customize the buttons of the navigator like this:
#+BEGIN_SRC emacs-lisp
;; Format: "(icon title help action face prefix suffix)"
(setq dashboard-navigator-buttons
      `(;; line1
        ((,(all-the-icons-octicon "mark-github" :height 1.1 :v-adjust 0.0)
         "Homepage"
         "Browse homepage"
         (lambda (&rest _) (browse-url "homepage")))
        ("★" "Star" "Show stars" (lambda (&rest _) (show-stars)) warning)
        ("?" "" "?/h" #'show-help nil "<" ">"))
         ;; line 2
        ((,(all-the-icons-faicon "linkedin" :height 1.1 :v-adjust 0.0)
          "Linkedin"
          ""
          (lambda (&rest _) (browse-url "homepage")))
         ("⚑" nil "Show flags" (lambda (&rest _) (message "flag")) error))))
#+END_SRC

To show info about the packages loaded and the init time:
#+BEGIN_SRC elisp
(setq dashboard-set-init-info t)
#+END_SRC

Also, the message can be customized like this:
#+BEGIN_SRC elisp
(setq dashboard-init-info "This is an init message!")
#+END_SRC

A randomly selected footnote will be displayed. To disable it:
#+BEGIN_SRC elisp
(setq dashboard-set-footer nil)
#+END_SRC

To customize it and customize its icon;

#+BEGIN_SRC elisp
(setq dashboard-footer-messages '("Dashboard is pretty cool!"))
(setq dashboard-footer-icon (all-the-icons-octicon "dashboard"
                                                   :height 1.1
                                                   :v-adjust -0.05
                                                   :face 'font-lock-keyword-face))
#+END_SRC

To use it with [[https://github.com/ericdanan/counsel-projectile][counsel-projectile]] or [[https://github.com/bbatsov/persp-projectile][persp-projectile]]

#+begin_src elisp
(setq dashboard-projects-switch-function 'counsel-projectile-switch-project-by-name)
#+end_src

Or

#+begin_src elisp
(setq dashboard-projects-switch-function 'projectile-persp-switch-project)
#+end_src

** Org mode’s agenda

   To display today’s agenda items on the dashboard, add ~agenda~ to ~dashboard-items~:

#+BEGIN_SRC elisp
(add-to-list 'dashboard-items '(agenda) t)
#+END_SRC

To show agenda for the upcoming seven days set the variable ~dashboard-week-agenda~ to ~t~.
#+BEGIN_SRC elisp
(setq dashboard-week-agenda t)
#+END_SRC

By default org-agenda entries are filter by time, only showing those
task with ~DEADLINE~, ~SCHEDULE-TIME~ or ~TIMESTAMP~ . To show all agenda entries
(except ~DONE~)

#+begin_src elisp
(setq dashboard-filter-agenda-entry 'dashboard-no-filter-agenda)
#+end_src

To have an extra filter, ~MATCH~ parameter is exposed as
~dashboard-match-agenda-entry~ variable, by default is ~nil~
#+begin_quote
‘MATCH’ is a tags/property/TODO match. Org iterates only matched
headlines. Org iterates over all headlines when MATCH is nil or t.
#+end_quote

See [[https://orgmode.org/manual/Using-the-Mapping-API.html][Org Manual]] for more information.

Once the agenda appears in the dashboard, ~org-agenda-files~ stay
open. With ~(setq dashboard-agenda-release-buffers t)~ the org files
are close. Note that this could slow down the dashboard buffer refreshment.

*** Agenda sort

Agenda is now sorted with ~dashboard-agenda-sort-strategy~ following
the idea of [[https://orgmode.org/worg/doc.html#org-agenda-sorting-strategy][org-agenda-sorting-strategy]]. Suported strategies are
~priority-up~, ~priority-down~, ~time-up~, ~time-down~, ~todo-state-up~ and ~todo-state-down~

*** Agenda format

To personalize the aspect of each entry, there is
~dashboard-agenda-prefix-format~ which initial value is
~" %i %-12:c %-10s "~ where ~%i~ is the icon category of the item (see
[[https://orgmode.org/worg/doc.html#org-agenda-category-icon-alist][org-agenda-category-icon-alist]]), ~%-12:c~ gives the category a 12
chars wide field and append a colon to the category. A similar padding
but for a 10 wide field is ~%-10s~ that is for the scheduling or
deadline information. For more information see [[https://orgmode.org/worg/doc.html#org-agenda-prefix-format][org-agenda-prefix-format]].

Deadline or Scheduling time will be formatted using
~dashboard-agenda-time-string-format~ and the keywords (TODO, DONE)
respect [[https://orgmode.org/worg/doc.html#org-agenda-todo-keyword-format][org-agenda-todo-keyword-format]].

*** Agenda tags

To customize the tags format there is a variable
~dashboard-agenda-tags-format~. This variable could be any function that
receives the tags directly from ~org-get-tags~. By default
~dashboard-agenda-tags-format~ is set to ~identity~. To hide the
tags set the variable to ~ignore~: ~(setq dashboard-agenda-tags-format 'ignore)~
or to ~nil~.

** Faces

It is possible to customize Dashboard's appearance using the following faces:

- ~dashboard-banner-logo-title~ ::
     Highlights the banner title.
- ~dashboard-text-banner~ ::
     Highlights text banners.
- ~dashboard-heading~ ::
     Highlights widget headings.
- ~dashboard-items-face~ ::
     Highlights widget items.

* Shortcuts

You can use any of the following shortcuts inside Dashboard

|----------------------------+------------------|
| Shortcut                   | Function         |
|----------------------------+------------------|
| Tab Or C-i                 | Next Item        |
| Shift-Tab                  | Previous Item    |
| Return / Mouse Click / C-m | Open             |
| r                          | Recent files     |
| m                          | Bookmarks        |
| p                          | Projects         |
| a                          | Org-Mode Agenda  |
| e                          | Registers        |
| g                          | Refresh contents |
| {                          | Previous section |
| }                          | Next section     |
|----------------------------+------------------|

* Wish List
  1. [X] Center content
  2. [X] More banner options
  3. [X] Customizing the list of widgets to display
  4. [X] Integrate Org-mode's agenda
  5. [ ] Listing Perspectives

* Contributions

To contribute your changes to this package, please do the following:

1. Fork the repo
2. Clone a local copy
3. Make your changes
4. Push and create your PR

When working on this package, it's typical to uninstall dashboard,
develop your changes and then install this as "development version".

This is accomplished with the following steps:

#+BEGIN_SRC shell
# In emacs:
M-x package-delete dashboard-<version> RET
#+END_SRC

#+BEGIN_SRC shell
make package
make install
#+END_SRC

** Prerequisites

  * [[https://github.com/emacs-eask/cli][Eask]]