[[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/dashboard/actions/workflows/test.yml][https://github.com/emacs-dashboard/dashboard/workflows/CI/badge.svg]] [[https://github.com/emacs-dashboard/dashboard/actions/workflows/activate.yml][https://github.com/emacs-dashboard/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. [[https://github.com/purcell/page-break-lines][page-break-lines]] (optional)
2. [[https://github.com/bbatsov/projectile][projectile]] (optional)
3. [[https://github.com/domtronn/all-the-icons.el][all-the-icons]] (optional)
4. [[https://github.com/rainstormstudio/nerd-icons.el][nerd-icons]] (optional)

• 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) #+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 'dashboard-open) #+END_SRC

[[https://github.com/domtronn/all-the-icons.el][all-the-icons]] and [[https://github.com/rainstormstudio/nerd-icons.el][nerd-icons]] may require a refresh in order to be displayed correctly:

#+BEGIN_SRC elisp (add-hook 'server-after-make-frame-hook 'dashboard-open) #+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: ;; - 'official which displays the official emacs logo. ;; - 'logo which displays an alternative emacs logo PNG or braille. ;; - 'logo-ansi-truecolor which displays an alternative emacs logo ;; using unicode block characters and ANSI escape sequences. ;; - 'logo-ansi-256color which displays an alternative emacs logo ;; using unicode block characters and ANSI escape sequences. ;; - 'logo-braille which displays an alternative emacs logo ;; using unicode braille characters. ;; - 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. ;; (cons "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 modify the icon height or vertical adjust: #+BEGIN_SRC emacs-lisp (setq dashboard-icon-file-height 1.75) (setq dashboard-icon-file-v-adjust -0.125) (setq dashboard-heading-icon-height 1.75) (setq dashboard-heading-icon-v-adjust -0.125) #+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

Please check the [[./docs/variables-and-functions.org][complete list of variables and functions]]. ** 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 filtered 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:

• 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 | |----------------------------+------------------|

Section shortcuts (i.e. bookmarks, projects, agenda, registers) could be customized in the dashboard-items-shortcut variable. These shortcuts would cycle the section forward, and the uppercase of the shortcut would cycle the section backward. For example, the m key would go to the bookmarks section, and when pressed again, it would go to the next bookmark item and so on until it reached the end of the section, then would go back to the first bookmark item. And key M would do the same but backwards.

• Wish List

1. Center content
2. More banner options
3. Customizing the list of widgets to display
4. 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- RET #+END_SRC

#+BEGIN_SRC shell make package make install #+END_SRC

Or, you can use [[https://github.com/emacs-eask/cli][Eask]] to set up the development environment, so there's no need to delete your local dashboard.

Install all dependencies and development dependencies:

#+BEGIN_SRC shell eask install-deps --dev #+END_SRC

To test the package's installation:

#+BEGIN_SRC shell eask package eask install #+END_SRC

To test compilation:

#+BEGIN_SRC shell eask compile #+END_SRC

🪧 The following steps are optional, but we recommend you follow these lint results!

The built-in checkdoc linter:

#+BEGIN_SRC shell eask lint checkdoc #+END_SRC

The standard package linter:

#+BEGIN_SRC shell eask lint package #+END_SRC

/📝 P.S. For more information, find the Eask manual at https://emacs-eask.github.io/.