An extensible emacs dashboard
GPL-3.0 License
[[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]]
[[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.
projectile
or project.el
package)[[./etc/screenshot.png]]
#+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) #+END_SRC
Or with use-package: #+BEGIN_SRC elisp ;; use-package with package.el: (use-package dashboard :ensure t :config (dashboard-setup-startup-hook)) #+END_SRC
#+BEGIN_SRC elisp ;; use-package with Elpaca: (use-package dashboard :elpaca t :config (add-hook 'elpaca-after-init-hook #'dashboard-insert-startupify-lists) (add-hook 'elpaca-after-init-hook #'dashboard-initialize) (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-buffer-name))) #+END_SRC
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: ;; - 'official which displays the official emacs logo. ;; - 'logo which displays an alternative emacs logo. ;; - an integer which displays one of the text banners ;; (see dashboard-banners-directory files). ;; - a string that specifies a path for a custom banner ;; currently supported types are gif/image/text/xbm. ;; - a cons of 2 strings which specifies the path of an image to use ;; and other path of a text file to use if image isn't supported. ;; ("path/to/image/file/image.png" . "path/to/text/file/text.txt"). ;; - a list that can display an random banner, ;; supported values are: string (filepath), 'official, 'logo and integers.
;; Content is not centered by default. To center, set (setq dashboard-center-content t) ;; vertically center content (setq dashboard-vertically-center-content t)
;; To disable shortcut "jump" indicators for each section, set (setq dashboard-show-shortcuts nil) #+END_SRC
To customize which items 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 customize which widgets to display in order (example: Banner, footer message ...): #+begin_src emacs-lisp (setq dashboard-startupify-list '(dashboard-insert-banner dashboard-insert-newline dashboard-insert-banner-title dashboard-insert-newline dashboard-insert-navigator dashboard-insert-newline dashboard-insert-init-info dashboard-insert-items dashboard-insert-newline dashboard-insert-footer)) #+end_src See dashboard-startupify-list for all the widgets avalaibles.
To enable cycle navigation between each section: #+begin_src emacs-lisp (setq dashboard-navigation-cycle t) #+end_src
To customize string format in shortcuts: #+begin_src emacs-lisp (setq dashboard-heading-shorcut-format " [%s]") #+end_src
To customize item shortcuts: #+BEGIN_SRC elisp (setq dashboard-item-shortcuts '((recents . "r") (bookmarks . "m") (projects . "p") (agenda . "a") (registers . "e"))) #+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 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 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.
** FAQ
Check out our [[./docs/FAQ.org][Frequently Asked Questions]].
** Faces
It is possible to customize Dashboard's appearance using the following faces:
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 | |----------------------------+------------------|
To contribute your changes to this package, please do the following:
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
M-x package-delete dashboard- RET #+END_SRC
#+BEGIN_SRC shell make package make install #+END_SRC
** Prerequisites