welkomscherm.el

welkomscherm is Dutch for welcome screen.

welkomscherm.el is a small, calm, extensible welcome screen / dashboard for Emacs: a centred handful of lines, the links you actually use, and nothing that gets in your way. It greets you in a graphical frame and in a plain terminal alike, on any Emacs from 25.1 upwards, and it asks nothing of you that Emacs does not already provide.

Extensible and configurable to your liking and following and respecting your themes out of the box and with customizable faces.

One screen, two themes, every section: the demo alternates between the default view and one with separators, recent files and system details enabled, in a dark and a light theme. The frames are drawn from the package's own buffer output — see Showcase and screenshots for how, and for more pictures.

Every editor has a welcome screen; most of them try to be a cockpit. That is wonderful when you want a cockpit, and tiring when you only want to feel at home.

welkomscherm makes one promise: *a small, legible, beautifully centred screen that you can read in a second and trust to keep working for the next fifty years.* Concretely, that promise is kept by four choices.

No external libraries.

The whole package runs on Emacs built-ins alone. There is nothing to install alongside it and nothing to break when another package changes. The section separators are drawn by welkomscherm itself and re-flow with the window, so there is not even a rendering library to miss.

Tiny and auditable.

The entire package is a single file of a few hundred lines. You can read all of it on a coffee break, and you will understand all of it.

Composable sections.

Every block of the screen is a self-contained unit with its own heading, its own visibility rule and its own body. Adding, removing or reordering a section means editing one list — the list welkomscherm/sections — and nothing else.

One screen, two worlds.

The same buffer renders identically in GUI Emacs and in terminal Emacs, local or over SSH, because it is plain text and ordinary Emacs buttons rather than images and widgets.

A welcome screen, not a cockpit.

Title, bookmarks, work links, action buttons, optional recent files, optional system details. Nothing else asks for your attention.

Composable sections.

Add, remove or reorder blocks of the screen by editing welkomscherm/sections. A section can be one of the built-ins, a record you build with welkomscherm/make-section, or a plain function of no arguments.

Self-drawn separators.

Opt-in horizontal rules that follow the centring axis of your text, re-flow on resize, and need no page-break-lines or any other package. See welkomscherm/use-separator.

Clickable everything.

Bookmarks and actions are ordinary Emacs buttons, so mouse-1, TAB and RET all work, in a GUI frame and in a terminal.

GUI and TUI parity.

No images, no widgets, no conditional code paths: the same screen on a laptop, a workstation, or a server console over SSH.

Opt-in extras.

Recent files (from the built-in recentf) and system details are one flag away, and stay out of the way until you ask for them.

Startup honesty.

A small line tells you how long Emacs took to start, handy while tuning your configuration and easy to switch off afterwards.

Your private and work lives apart.

Separate bookmark lists for personal and work links, each arranged in rows, the way you would arrange a shelf.

Quiet by default.

The buffer is read-only, a little extra line spacing keeps it airy (user customizable via welkomscherm/line-spacing), and point is left on the first line so you always see it from the top.

Free software, all the way.

GPL-3.0-or-later for the code, FDL-1.3+ for the docs. No telemetry, no network, no surprises.

Four routes to the same 1.2.4, from the most automated to the most manual. They all build the tag this README documents.

git clone https://codeberg.org/jjba23/guix-jointhefreeworld.git
guix install -L ./guix-jointhefreeworld emacs-welkomscherm

nix build github:jjba23/nix-jointhefreeworld#emacs-welkomscherm

podman build -t welkomscherm-el .   # docker build -t welkomscherm-el . also works
podman run --rm -it welkomscherm-el

Under a minute, start to finish:

1. Put welkomscherm on your load-path and require it (see Installation).

2. Point it at a directory or file you open all day:

     (require 'welkomscherm)
     (setq welkomscherm/bookmarks-list
           '((("org" . "~/org/") ("notes" . "~/notes.org"))))

3. Run M-x welkomscherm.

That is the whole tour. Everything below is refinement: what the screen shows, how it is built, and how to make it yours.

If you want the welcome screen to be your initial buffer whenever you start a new Emacs (a GUI frame or a terminal one), add this to your Emacs configuration:

  (setq initial-buffer-choice
        (lambda () (welkomscherm) (get-buffer welkomscherm/buffer-name)))

Note that if using use-package it's recommendable to apply this setting in your (use-package emacs) declaration.

Feel free to dive a little into the source code and explore all the configuration options: every option is documented in its own docstring. Out of the box, welkomscherm shows its top title, then your work and personal bookmarks, your action buttons, and how long startup took.

Every option below belongs to the welkomscherm customization group and can be set with setopt, with setq on older Emacsen, or through M-x customize-group RET welkomscherm.

  (setopt welkomscherm/show-recent-files t
          welkomscherm/recent-files-limit 5)

Everything on the screen is a section. A section is a small record, built with welkomscherm/make-section, that knows three things:

• its name — the heading drawn above it. It can be a plain string, a function returning a string (so the heading follows customization made later), or nil for a section with no heading at all;
• its render function — a function of no arguments that grows the buffer;
• its condition — a function of no arguments; when it returns non-nil the section is shown, otherwise it is skipped entirely. nil means "always show".

The shared framing — the blank line, the optional separator and the heading — is drawn for you by welkomscherm/render-section, so a section body only ever draws its own content. That is what makes sections independent: to add, remove or reorder one, you never touch the rendering code.

The screen itself is simply the list welkomscherm/sections, rendered in order:

  welkomscherm/sections
  ;; => (welkomscherm/top-title welkomscherm/work welkomscherm/bookmarks
  ;;     welkomscherm/recent-files-section welkomscherm/actions
  ;;     welkomscherm/system-details welkomscherm/init-time)

Reorder that list to reorder your home screen; drop an element to retire a section; add your own to make the screen truly yours. A section can even be a plain function of no arguments, if that is all you need:

  (setopt welkomscherm/sections
          (list welkomscherm/top-title
                ;; A section of your own, built as a record.
                (welkomscherm/make-section
                 :name "Today"
                 :condition (lambda () (bound-and-true-p org-agenda-files))
                 :render (lambda () (welkomscherm/insert-muted "Make it a good one.")))
                ;; Or just a bare function.
                (lambda () (welkomscherm/insert-muted "and a warm cup of coffee"))
                welkomscherm/bookmarks
                welkomscherm/actions))

  (welkomscherm/make-section
   :name "Capture"
   :render (lambda ()
             (welkomscherm/render-action-rows
              (list (list (cons "note" (lambda (btn) (find-file "~/org/inbox.org")))
                          (cons "task" (lambda (btn) (find-file "~/org/tasks.org"))))))))

welkomscherm.el allows you to run code arbitrarily both before it renders, as well as after. You should feel free to customize this to your liking.

On the technical side, this means two hooks are made available, welkomscherm/pre-render-hook and welkomscherm/post-render-hook.

Find here an example where we adjust the fill-column in the welkomscherm buffer so that the dashboard gets centered properly according to the size of the frame.

By default, without this, centering is based on your default fill-column (likely 70 char) due to (center-line).

  (add-hook 'welkomscherm/pre-render-hook
            (lambda () (setq-local fill-column (frame-parameter nil 'width))))

Find here an example of running arbitrary code after rendering:

  (add-hook 'welkomscherm/post-render-hook
            (lambda () (message "welkomscherm rendered successfully")))

The Emacs dashboard space is friendly and varied; each of these packages is a good answer to a slightly different question. Read this table as a map rather than a scoreboard: any of them may be the right home for you.

A few notes to keep the comparison honest (all read from the projects' repositories):

• emacs-dashboard is the richest of the group and the closest thing to a batteries-included cockpit; it is also the largest, with roughly 2,400 lines across dashboard.el and dashboard-widgets.el. Its page-break-lines, projectile and icon dependencies are optional, not required.
• enlight is deliberately the opposite: a small framework (330 lines) where you supply the content as a string. Its only external dependency is ~compat.
• welcome.el is a compact welcome buffer (277 lines) built around a command menu, and needs ~nerd-icons for its icons.
• minimal-dashboard.el narrows the idea down to an image and a line of text (~337 lines).

Against all of these, welkomscherm's distinguishing choices are its zero external dependencies, its section abstraction — every block is a reusable unit you can reorder or share — and its strict equivalence between GUI and TUI. When the package is measured against Emacs's image-display limits, this is what lets the very same screen greet you on a laptop, a workstation and a server console without a single conditional.

The project ships with an ERT suite in test/welkomscherm-test.el and a Maak file. With maak installed, a single command runs the whole quality gate from a clean tree.

maak on its own runs check, which:

1. byte-compiles the package and its test suite with warnings turned into errors;
2. enforces checkdoc through test/welkomscherm-checkdoc.el, which turns style findings into a non-zero exit;
3. runs the ERT suite.

Other tasks: maak compile, maak test, maak lint, maak clean, maak repl (an Emacs with the package loaded, ready for hacking) and maak tasks (to list them all).

If you prefer plain Emacs, the suite runs on its own too:

  emacs -Q --batch -L . -L test -l test/welkomscherm-test.el \
        -f ert-run-tests-batch-and-exit

The package itself needs no external library at all. Even the horizontal rules that separate sections are drawn by welkomscherm itself, with no library: see welkomscherm/use-separator and welkomscherm/separator.

Default view, both themes:

Everything on, both themes:

These pictures are generated from the real thing, not mocked up: screenshots/capture.el renders the package in a batch Emacs and dumps the buffer — text, styling runs and all — and screenshots/render.py paints that output with the Modus themes' own palette. (The mode line is drawn by the renderer, and the startup-time section is left out, because a batch render has no meaningful startup time to report.) Regenerate them with Emacs, and with Python 3 and Pillow:

  emacs -Q --batch -L . -l screenshots/capture.el screenshots/out
  python3 screenshots/render.py

And here are two screenshots of the real thing in its natural habitat, taken from a live Emacs session:

Contributing to free software is a uniquely beautiful act because it embodies principles of generosity, collaboration, and empowerment.

We welcome everyone to feel invited to the welkomscherm.el project, and encourage active contribution in all forms, to improve it and/or suggest improvements, brainstorm with me, make it more modular/flexible, etc, feel free to contact me <jjbigorra@gmail.com> to chat, discuss or report feedback.

You do not need to write code to help. Any of these counts:

Report a bug

a sentence, an Emacs version and, if you can, the contents of the *welkomscherm* buffer is plenty.

Suggest a section

send the welkomscherm/make-section form you wish existed; it may land in the defaults.

Improve the words

this README, the docstrings and the comments in the source all count as code here, and are just as worth polishing.

Send a patch

run maak first — it byte-compiles with warnings as errors, enforces checkdoc and runs the tests — then open a pull request, or mail the patch if you prefer.

Spread the word

tell someone who has been meaning to try Emacs.

Find here the Backlog and Kanban boards for my Emacs packages: https://lucidplan.jointhefreeworld.org/tickets/emacs-pkg

If you like my work, please support me by buying me a cup of coffee ☕ so I can continue with a lot of motivation.

This project adheres to the jointhefreeworld code of conduct. Find it here:

https://jointhefreeworld.org/blog/articles/personal/jointhefreeworld-code-of-conduct/index.html

In summary, we foster an inclusive, respectful, and cooperative environment for all contributors and users of this free software project. Inspired by the ideals of the GNU Project, we strive to uphold freedom, equality, and community as guiding principles. We believe that collaboration in a community of mutual respect is essential to creating excellent free software.

welkomscherm.el and all of its source code are free software, licensed under the GNU General Public License v3 (or newer at your convenience).

https://www.gnu.org/licenses/gpl-3.0.html

The documentation and examples, including this document, which are provided with welkomscherm.el, are all licensed under the GNU Free Documentation License v1.3 (or newer at your convenience).

https://www.gnu.org/licenses/fdl-1.3.html