An extensible emacs dashboard
Branch: master
Clone or download
Latest commit 09d6f20 Feb 22, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Fix bug introduced by lint fixes Feb 23, 2019
.emacs Solve lint issues Feb 23, 2019
banners Custom banner support. Added default image banner Dec 30, 2016
.dir-locals.el Solve lint issues Feb 23, 2019
.gitignore Fix bug introduced by lint fixes Feb 23, 2019
Cask Use cask Apr 8, 2017
Makefile Solve lint issues Feb 23, 2019
README.org Remove note Feb 23, 2019
dashboard-widgets.el Remove note Feb 23, 2019
dashboard.el Solve lint issues Feb 23, 2019
screenshot.png Update screenshot Dec 30, 2016

README.org

Emacs Dashboard

https://circleci.com/gh/emacs-dashboard/emacs-dashboard/tree/master.svg?style=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 projectile projects list (Depends on `projectile` package)
  5. Org mode agenda
  6. Register list

Screenshot

./screenshot.png

Dependencies

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

  1. page-break-lines - https://github.com/purcell/page-break-lines
  2. (optional) projectile - https://github.com/bbatsov/projectile

Usage

M-x package-install RET dashboard
(require 'dashboard)
(dashboard-setup-startup-hook)
;; Or if you use use-package
(use-package dashboard
  :ensure t
  :config
  (dashboard-setup-startup-hook))

By default, this will show three lists, recent files and bookmarks and org-agenda items. One more widget is implemented by Dashboard but it’s made optional because of it’s dependency on a third party application, which is `projects` which shows you the list of known projectile projects.

Emacs Daemon

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

(setq initial-buffer-choice (lambda () (get-buffer "*dashboard*")))

Configuration

To update the banner or banner title

;; 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
;; 1, 2 or 3 which displays one of the text banners
;; "path/to/your/image.png" which displays whatever image you would prefer

To customize which widgets are displayed, you can use the following snippet

(setq dashboard-items '((recents  . 5)
                        (bookmarks . 5)
                        (projects . 5)
                        (agenda . 5)
                        (registers . 5)))

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:

(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)

Org mode’s agenda

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

(add-to-list 'dashboard-items '(agenda) t)

To show agenda for the upcoming seven days set the variable show-week-agenda-p to t.

(setq show-week-agenda-p t)

Note that setting list-size for the agenda list is intentionally ignored; all agenda items for the current day will be displayed.

Faces

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

dashboard-banner-logo-title-face
Highlights the banner title.
dashboard-heading-face
Highlights widget headings.
widget-button
Highlights widget items.

Shortcuts

You can use any of the following shortcuts inside Dashboard

ShortcutFunction
Tab Or C-iNext Item
Shift-TabPrevious Item
Return / Mouse Click / C-mOpen
rRecent files
mBookmarks
pProjects
aOrg-Mode Agenda
eRegisters
gRefresh 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:

# In emacs:
M-x package-delete dashboard-<version> RET
make build
make install

Prerequisites