dotfiles/README.org

Dotfiles

Immutable GNU Emacs dotfiles. Built for Life, Liberty, and the Open Road.

• 100% Literate

• 100% Immutable

• 100% Reproducible

Init

Although later versions of Emacs introduce early-init.el, it's not used in this configuration for two reasons:

• It's not required due to the modularity

• Maintaining support for older versions

Assuming you have completed all of the following tasks prior to proceeding further:

1. Imported the secrets

2. Initialized the passwords

3. Defined the host file

4. Created all required symbolic links

Launch emacs: emacs -mm --debug-init

Options

Here's a complete list of all of the options configurable for each host, and their default values. If a host configuration does not exist, the default values will remain.

Configure the system font with a single font-family and define the size, of which variations to the font size are relative to this value.

(defvar dotfiles/font
  "Fira Code"
  "Unified system font family, used on all font faces.")

(defvar dotfiles/font-size
  96
  "Unified font size, of which all variations are relative to.")

Used by the desktop module to find the appropriate browser.

(defvar dotfiles/browser
  (getenv "BROWSER")
  "The default browser used by the system.")

Used by the writing module to determine the system language.

(defvar dotfiles/language
  (getenv "LANG")
  "The default system language.")

All of the available modules defined in the dotfiles/modules-available constant.

(defconst dotfiles/modules-available
  '(core editor desktop writing projects interface)
  "All of the available modules for hosts to load.")

Add the modules you want to initialize to the dotfiles/modules variable.

(defvar dotfiles/modules
  dotfiles/modules-available
  "Enabled modules, modify this in your host configuration.")

Specify the emacs home, and the cache directory.

(defvar dotfiles/home
  user-emacs-directory
  "Original value of `user-emacs-directory'.")

Used to seperate the immutable configuration from the stateful package files.

(defvar dotfiles/cache
  (expand-file-name "~/.cache/emacs")
  "Where `user-emacs-directory' redirects to.")

Functionality like completion and hints delayed to avoid popups for common manuevers.

(defvar dotfiles/idle
  0.0
  "Length of time to wait before offering completions.")

Required for the all powerful leader key.

(defvar dotfiles/leader-key
  "SPC"
  "Custom leader key for custom actions.")

The desktop module requires the global leader key set.

(defvar dotfiles/leader-key-global
  (concat "C-" dotfiles/leader-key)
  "Global leader key available everywhere.")

Define where the source repositories exist on disk, for integration with the projects module.

(defvar dotfiles/projects
  (expand-file-name "~/.local/source/")
  "Location where source code projects exist on disk.")

Where the password store exists on disk.

(defvar dotfiles/passwords
  (expand-file-name "~/.password-store/")
  "Directory containing the password store.")

Configure the public GPG key that Emacs will encrypt files to.

(defvar dotfiles/public-key
  "37AB1CB72B741E478CA026D43025DCBD46F81C0F"
  "Public PGP key that Emacs will encrypt files to.")

Startup

The host configuration loads (if it exist) using the systems name.

(let ((host-file (concat dotfiles/home "/hosts/" system-name ".el")))
  (when (file-exists-p host-file)
    (load-file host-file)))

Load all of the enabled modules:

(dolist (m dotfiles/modules)
  (let ((mod-file (concat dotfiles/home "/modules/" (symbol-name m) ".el")))
    (when (file-exists-p mod-file)
      (load-file mod-file))))

Hosts

Each host system that runs Emacs has a file defined in the hosts/ sub directory, following the pattern of $HOSTNAME.el. All of the configurations definitions are in this file. Modules will read these values during initialization.

Virtualbox

The first configuration, built using the Ubuntu 20.04 LTS server edition.

• Set the browser manually

• Set the language to Canadian english

(setq dotfiles/browser "firefox"
      dotfiles/language "en_CA")

Acernitro

The first machine with real hardware to deploy this configuration to. It's an Acer Nitro AN-515 with the NVIDIA / Intel hybrid graphics card. Due to the issues I encountered with this hardware setup, I again opted to install Ubuntu 20.04, and stripped away the components I don't need.

• Set the browser manually

• Set the language to Canadian english

• Increase font size for high DPI screen

Configure the browser.

(setq dotfiles/browser "firefox"
      dotfiles/language "en_CA"
      dotfiles/font-size 132)

Raspberry

Raspberry Pi 400 personal computer, and a small fleet of Zero, Zero WH, 4, and 4Bs.

• Set the browser manually

• Set the language to Canadian english

• Increase font size for small screens

(setq dotfiles/browser "chromium-browser"
      dotfiles/language "en_CA"
      dotfiles/font-size 132)

Termux

Android devices do not use the Linux host names, so setting a custom hostname is pointless as it just changes the value of kernel.hostname and have no impact on the running system. It's recommended to leave the hostname as localhost in Termux. While this raises an issue with my host definition system, it's no more of an issue than the raspberry namespace.

• Increase font size for small screen

(setq dotfiles/font-size 132)

Modules

Breaking down the project into logical units or chapters to keep the code more maintainable and organized. This is also a fundamental requirement to achieve the goal of modularity. Incorporating just the core module on a build server to build literate programming projects is just one example.

Core

Minimal configuration to make Emacs usable for my own personal workflow. This does little in the ways of improving the visuals, only removing what's included by default and not required. Read more about my technique in my post Immutable Emacs.

Startup

Emacs creates a lot of files relative to user-emacs-directory, these files are not part of this immutable configuration and do not belong in the emacs directory. How can we solve this issue? Shortly after initialization, before most packages load, we change the value to dotfiles/cache. I elaborate more on the technique in my post Immutable Emacs.

(setq user-emacs-directory dotfiles/cache)

Because this project uses version-control, we can disable more unwanted features:

• Lock files

• Backup files

(setq create-lockfiles nil
      make-backup-files nil)

Packages

Download and install packages using straight.el, a functional package manager that integrates with use-package, giving us more control over sourcing our packages.

• Use the development branch

• Integrate with use-package

Apply the configurations prior to bootstrapping the package manager, by setting (writing) to the variables that straight will ultimately read from.

(setq straight-repository-branch "develop"
      straight-use-package-by-default t)

Bootstrap the package manager, downloading, installing, or configuring depending on the state of the configuration. All packages build from source, pinned to specific git commit hashes.

(defvar bootstrap-version)
(let ((bootstrap-file
       (expand-file-name "straight/repos/straight.el/bootstrap.el" user-emacs-directory))
      (bootstrap-version 5))
  (unless (file-exists-p bootstrap-file)
    (with-current-buffer
        (url-retrieve-synchronously
         "https://raw.githubusercontent.com/raxod502/straight.el/develop/install.el"
         'silent 'inhibit-cookies)
      (goto-char (point-max))
      (eval-print-last-sexp)))
  (load bootstrap-file nil 'nomessage))

Complete the integration with use-package by installing it with straight.

(straight-use-package 'use-package)

Cleanup

Despite having our stateful and immutable configurations seperate, it's good practice to make efforts to reduce the trash created by Emacs. Install no-littering to reduce the files created by Emacs.

(use-package no-littering)

Emacs' default user interface is horrendous, let's do something about that.

(setq inhibit-startup-message t
      initial-scratch-message "")

(global-prettify-symbols-mode)

(when (fboundp 'tooltip-mode)
  (tooltip-mode -1))
(when (fboundp 'tool-bar-mode)
  (tool-bar-mode -1))
(when (fboundp 'menu-bar-mode)
  (menu-bar-mode -1))
(when (fboundp 'scroll-bar-mode)
  (scroll-bar-mode -1))

Emacs has a long history of running on machines without gigabytes of available memory, let it realize its full potential! Just kidding, it just smashes CPU0.

(setq gc-cons-treshold most-positive-fixnum
      gnutls-min-prime-bits 4096)

Babel

Organize your plain life in plain text

Org-mode is one of the hallmark features of Emacs, and provides the basis for my Literate Programming platform. It's essentially a markdown language with rich features for project management, scheduling, development, and writing. It's hard to convey everything within its capabilities.

• Babel languages

• Structure templates

(use-package org
  :hook (org-mode . (lambda ()
          (org-indent-mode)
          (visual-line-mode 1)
          (variable-pitch-mode 1)))
  :custom (org-ellipsis " ▾")
          (org-log-done 'time)
          (org-log-into-drawer t)
          (org-return-follows-link t)
          (org-image-actual-width nil)
          (org-directory dotfiles/home)
          (org-src-fontify-natively t)
          (org-src-tab-acts-natively t)
          (org-src-preserve-indentation t)
          (org-confirm-babel-evaluate nil)
          (org-todo-keywords '((sequence "TODO" "START" "WAIT" "DONE")))
  :config (require 'org-tempo)
          (add-to-list 'org-structure-template-alist '("s" . "src"))
          (add-to-list 'org-structure-template-alist '("q" . "quote"))
          (add-to-list 'org-structure-template-alist '("e" . "example"))
          (add-to-list 'org-structure-template-alist '("sh" . "src shell"))
          (add-to-list 'org-structure-template-alist '("el" . "src emacs-lisp"))
          (org-babel-do-load-languages 'org-babel-load-languages '((shell . t)
                                                                   (emacs-lisp . t))))

Build all of the org files within a given directory.

(defun dotfiles/tangle (dir)
  "Recursively tangle the Org files within a directory."
  (let ((org-files (directory-files-recursively dir "org")))
    (dolist (f org-files)
      (org-babel-tangle-file f))))

Editor

This section contains configuration for improving the editor experience within Emacs.

Keys

Make the ESC key quit (most) prompts, instead of the default C-g.

(global-set-key (kbd "<escape>") 'keyboard-escape-quit)

Download which-key, a package that displays the current incomplete keybinding input in a mini-buffer, showing available completion options.

(use-package which-key
  :diminish which-key-mode
  :custom (which-key-idle-delay dotfiles/idle)
  :config (which-key-mode))

Turn Emacs into Vim with evil-mode, the extensible VI layer for Emacs.

(use-package evil
  :custom (evil-want-integration t)  ;; Required for `evil-collection'.
          (evil-want-keybinding nil) ;; Same as above
  :config (evil-mode 1))

Unfortunately the default keybindings are lacking, but there is a community curated package evil-collection, which does a much better job implementing keybindings you would expect to find.

(use-package evil-collection
  :after evil
  :config (evil-collection-init))

Surround text with functions, quotations, and any other symbols using the evil-surround package.

(use-package evil-surround
  :after evil
  :config (global-evil-surround-mode 1))

Toggle block comments using evil-nerd-commentor and M-;.

(use-package evil-nerd-commenter
  :after evil
  :bind ("M-;" . evilnc-comment-or-uncomment-lines))

Implement the leader key using general.el, letting us easily configure prefixed keybindings in a much cleaner manner than the default methods.

(use-package general
  :after evil
  :config
  (general-create-definer dotfiles/leader
    :states '(normal motion)
    :keymaps 'override
    :prefix dotfiles/leader-key
    :global-prefix dotfiles/leader-key-global))

Use hydra for transient keybindings sharing a common prefix.

(use-package hydra
  :defer t)

Help

Use the built-in describe-* functionality of Emacs to quickly access documentation for packages, variables, and functions. Run helper functions with SPC h.

• Packages p

• Variables v

• Functions f

(dotfiles/leader
  "h" '(:ignore t :which-key "Help")
  "hp" '(describe-package :which-key "Package")
  "hv" '(describe-variable :which-key "Variable")
  "hf" '(describe-function :which-key "Function"))

Files

For file navigation I use dired, included with Emacs by default. Dired feels more modern with prioritized icon fonts using all-the-icons. This makes navigation and visually parsing directories much faster, given that file types are quickly identified by their corresponding icons.

(use-package all-the-icons)

Integration with dired comes from the all-the-icons-dired package.

(use-package all-the-icons-dired
  :hook (dired-mode . all-the-icons-dired-mode))

When opening dired, I don't want to have to press RET twice to navigate to the current directory. Avoid this with dired-jump, included in the dired-x package shipped with dired and Emacs.

(require 'dired-x)

By default dired will create a new buffer everytime you press RET over a directory. This leads to unwanted dired buffers needing closure. Avoid this behaviour with dired-single, reusing the same dired buffer.

• Move up a directory with h

• Open a single buffer with l

(use-package dired-single
  :config (evil-collection-define-key 'normal 'dired-mode-map
            "h" 'dired-single-up-directory
            "l" 'dired-single-buffer))

Open a dired buffer with SPC d.

(dotfiles/leader
  "d" '(dired-jump :which-key "Dired"))

Shell

While not a traditional terminal emulator, eshell provides me with all of the functionality I expect and require from one. Some users may be wanting more, I would recommend they look into vterm included in the destkop module. Configure the infamous lambda prompt using eshell-prompt-extras package.

(use-package eshell-prompt-extras
  :custom (eshell-highlight-prompt nil)
          (eshell-prefer-lisp-functions nil)
	        (eshell-prompt-function 'epe-theme-lambda))

Open an eshell buffer with SPC e.

(dotfiles/leader
  "e" '(eshell :which-key "Shell"))

Source

Another hallmark feature is Magit, a complete git porcelain within Emacs.

(use-package magit
  :commands magit-status
  :custom (magit-display-buffer-function
           #'magit-display-buffer-same-window-except-diff-v1))

Work directly with github issues / pull requests using Forge.

• Requires a valid $GITHUB_TOKEN

(use-package forge
  :after magit)

Open the status page for the current repository with SPC g.

(dotfiles/leader
  "g" '(magit-status :which-key "Magit"))

Windows

Window management with SPC w.

• Swap with w

• Close with c

• Motions with h,j,k,l

• Split with s + <MOTION>

(dotfiles/leader
  "w" '(:ignore t :which-key "Window")
  "ww" '(window-swap-states :which-key "Swap")
  "wc" '(delete-window :which-key "Close")
  "wh" '(windmove-left :which-key "Left")
  "wj" '(windmove-down :which-key "Down")
  "wk" '(windmove-up :which-key "Up")
  "wl" '(windmove-right :which-key "Right")
  "ws" '(:ignore t :which-key "Split")
  "wsj" '(split-window-below :which-key "Down")
  "wsl" '(split-window-right :which-key "Right"))

Shortcuts

Implement shortcut bindings, cherry picked from Doom emacs.

• Close buffers with SPC c

• Find files with SPC . (period)

(dotfiles/leader
  "." '(find-file :which-key "Files")
  "c" '(kill-buffer-and-window :which-key "Close"))

Quit emacs with SPC q.

• Saving q

• Without w

• Frame (daemon) f

(dotfiles/leader
  "q" '(:ignore t :which-key "Quit")
  "qq" '(save-buffers-kill-emacs :which-key "Save")
  "qw" '(kill-emacs :which-key "Now")
  "qf" '(delete-frame :which-key "Frame"))

Place runtime tweaks behind SPC t.

(dotfiles/leader
  "t" '(:ignore t :which-key "Tweaks"))

Desktop

I use Emacs as a Desktop Environment with the exwm package. It allows Emacs to function as a complete tiling window manager for X11. My workflow includes launching the window manager with xinitrc, without the use of a display manager, controlling everything within Emacs.

exec dbus-launch --exit-with-session emacs -mm --debug-init

Email

Plain text email delivered via mu, mu4e and mbsync. I run my own email server, so your configuration may differ from mine. This is the mbsyncrc file I use to synchronize my local mail with my server.

IMAPStore xyz-remote
Host mail.chrishayward.xyz
User chris@chrishayward.xyz
PassCmd "pass chrishayward.xyz/chris"
SSLType IMAPS

MaildirStore xyz-local
Path ~/.cache/mail/
Inbox ~/.cache/mail/inbox
SubFolders Verbatim

Channel xyz
Master :xyz-remote:
Slave :xyz-local:
Patterns * !Archives
Create Both
Expunge Both
SyncState *

The system typically expects to find this file at $HOME/.mbsyncrc, but you may also specify a custom path if launching the command using arguments. I chose to symlink the default location to my repository.

mbsync -a
mu index --maildir="~/.cache/mail"

Once the mail's synchronized, and has indexed with mu, it's time to install the required packages for Emacs.

• Update every 5 minutes

• Scale text for all devices

• Sign outbound mail with GPG key

• Configure mail account(s)

(use-package mu4e
  :load-path "/usr/share/emacs/site-lisp/mu4e"
  :custom (mu4e-maildir "~/.cache/mail")
          (mu4e-update-interval (* 5 60))
          (mu4e-get-mail-command "mbsync -a")
          (mu4e-compose-format-flowed t)
          (mu4e-change-filenames-when-moving t)
          (message-send-mail-function 'smtpmail-send-it)  
          (mml-secure-openpgp-signers '("37AB1CB72B741E478CA026D43025DCBD46F81C0F"))
          (mu4e-compose-signature (concat "Chris Hayward\n"
                                          "https://chrishayward.xyz\n"))
  :config
  (add-hook 'message-send-hook 'mml-secure-message-sign-pgpmime)
  (setq mu4e-contexts
    (list
      ;; Main
      ;; chris@chrishayward.xyz
      (make-mu4e-context
        :name "Main"
        :match-func
          (lambda (msg)
            (when msg 
              (string-prefix-p "/Main" (mu4e-message-field msg :maildir))))
        :vars
          '((user-full-name . "Christopher James Hayward")
            (user-mail-address . "chris@chrishayward.xyz")
            (smtpmail-smtp-server . "mail.chrishayward.xyz")
            (smtpmail-smtp-service . 587)
            (smtpmail-stream-type . starttls))))))

Use mu4e-alert to give us desktop notifications about incoming mail.

(use-package mu4e-alert
  :after mu4e
  :custom (mu4e-alert-set-default-style 'libnotify)
  :config (mu4e-alert-enable-notifications)
          (mu4e-alert-enable-mode-line-display))

Create a keybinding to open the mail dashboard with SPC m.

(dotfiles/leader
  "m" '(mu4e :which-key "Mail"))

Browser

Write out the $BROWSER environment variable.

(setenv "BROWSER" dotfiles/browser)

Startup

Ensure that /.local/bin is added to the path.

PATH=$PATH:~/.local/bin
export PATH

When launching into a session, if the display server is not running then startx executes to run the window manager.

if [ -z "${DISPLAY}" ] && [ "${XDG_VTNR}" -eq 1 ]; then
    exec startx
fi

Methods

Define a method to run an external process, allowing us to launch any application on a new process without interferring with Emacs.

(defun dotfiles/run (command)
  "Run an external process."
  (interactive (list (read-shell-command "λ ")))
  (start-process-shell-command command nil command))

Apply methods to the current call process to avoid issues with hooks.

(defun dotfiles/run-in-background (command)
  (let ((command-parts (split-string command "[ ]+")))
    (apply #'call-process `(,(car command-parts) nil 0 nil ,@(cdr command-parts)))))

Place keybindings for executing shell commands behind SPC x.

• Run shell commands with x

• Run async shell commands with z

(dotfiles/leader
  "x" '(:ignore t :which-key "Run")
  "xx" '(dotfiles/run :which-key "Run")
  "xz" '(async-shell-command :which-key "Async"))

Displays

When the window manager first launches the init-hook executes, allowing us to define some custom logic.

• Display time and date

• Display battery info (if available)

In my personal configuration, I do not want the battery or time displayed within Emacs when it's not running as desktop environment because that information is typically already available.

(defun dotfiles/init-hook ()
  (exwm-workspace-switch-create 1)
  (setq display-time-and-date t)
  (display-battery-mode 1)
  (display-time-mode 1))

Using autorandr with pre configured profiles, switching screens (AKA hot plugging) is also handled through a hook.

(defun dotfiles/update-display ()
  "Update the displays by forcing a change through autorandr."
  (dotfiles/run-in-background "autorandr --change --force"))

Configuration

Connect our custom hooks and configure the input keys, a custom layer for key capture layers.

• Enable randr support

• Pass through to Emacs

  • M-x to Emacs

  • C-g to Emacs

  • C-SPC to Emacs

• Bindings with S (Super / Win)

  • Reset S-r

  • Launch S-&

  • Workspace S-[1..9]

(use-package exwm
  :custom (exwm-workspace-show-all-buffers t)
          (exwm-input-prefix-keys
            '(?\M-x
              ?\C-c
              ?\C-g
              ?\C-\ ))
          (exwm-input-global-keys
            `(([?\s-r] . exwm-reset)
              ,@(mapcar (lambda (i)
                          `(,(kbd (format "s-%d" i)) .
                          (lambda ()
                          (interactive)
                          (exwm-workspace-switch-create ,i))))
                          (number-sequence 1 9))))
  :config (require 'exwm-randr)
          (exwm-randr-enable)
          (add-hook 'exwm-init-hook #'dotfiles/init-hook)
          (add-hook 'exwm-randr-screen-change-hook #'dotfiles/update-display)
          (dotfiles/update-display)
          (exwm-enable))

Writing

I am using org-mode extensively for writing projects for different purposes. Most of the improvements are done in the Core module for the Literate programming configuration. Encrypt files using symmetric key encryption via PGP. This enables my workflow of storing my personal notes anywhere. Emacs can cache the gpg password if you trust your session.

(setq epa-file-select-keys 2
      epa-file-cache-passphrase-for-symmetric-encryption t
      epa-file-encrypt-to dotfiles/public-key)

Download and install org-superstar-mode for making headline stars more super.

(use-package org-superstar
  :after org
  :hook (org-mode . org-superstar-mode))

Roam

Download and install org-roam, a plain text knowledge management system for Emacs.

(use-package org-roam
  :hook (after-init . org-roam-mode)
  :custom (org-roam-directory org-directory)
          (org-roam-encrypt-files t)
          (org-roam-capture-templates '())
          (org-roam-dailies-capture-templates
          '(("d" "Default" entry (function org-roam-capture--get-point)
             "* %?"
             :file-name "docs/daily/%<%Y-%m-%d>"
             :head
"
,#+TITLE: %<%Y-%m-%d>
,#+AUTHOR: Christopher James Hayward
"))))

Place keybindings behind SPC r.

• Find with f

• Toggle buffer with b

• Dailies with d

  • Arbitrary date with d

  • Today with t

  • Tomorrow with m

  • Yesterday with y

(dotfiles/leader
  "r" '(:ignore t :which-key "Roam")
  "rf" '(org-roam-find-file :which-key "Find")
  "rb" '(org-roam-buffer-toggle-display :which-key "Buffer")
  "rd" '(:ignore t :which-key "Dailies")
  "rdd" '(org-roam-dailies-find-date :which-key "Date")
  "rdt" '(org-roam-dailies-find-today :which-key "Today")
  "rdm" '(org-roam-dailies-find-tomorrow :which-key "Tomorrow")
  "rdy" '(org-roam-dailies-find-yesterday :which-key "Yesterday"))

Visualize the org-roam database with the server, available when the editor is running at http://localhost:8080

(use-package org-roam-server
  :hook (org-roam-mode . org-roam-server-mode))

Hugo

I use Hugo for my personal website, which I write in org-mode before compiling to hugo-markdown. ox-hugo, configured for one-post-per-file is my technique for managing my content.

(use-package ox-hugo 
  :after ox)

Posts

Add a capture template for creating new blog posts.

(with-eval-after-load 'org-roam
  (add-to-list 'org-roam-capture-templates
               '("p" "Post" plain (function org-roam-capture--get-point)
                 "%?"
                 :file-name "docs/posts/${slug}"
                 :unnarrowed t
                 :head
"
,#+TITLE: ${title}
,#+AUTHOR: Christopher James Hayward
,#+DATE: %<%Y-%m-%d>

,#+EXPORT_FILE_NAME: ${slug}
,#+ROAM_KEY: https://chrishayward.xyz/posts/${slug}/

,#+HUGO_BASE_DIR: ../
,#+HUGO_AUTO_SET_LASTMOD: t
,#+HUGO_SECTION: posts
,#+HUGO_DRAFT: true
")))

Notes

Add a capture template for creating blog posts and notes on other peoples content / published works.

(with-eval-after-load 'org-roam
  (add-to-list 'org-roam-capture-templates
               '("n" "Notes" plain (function org-roam-capture--get-point)
                  "%?"
                  :file-name "docs/notes/${slug}"
                  :unnarrowed t
                  :head
"
,#+TITLE: ${title}
,#+AUTHOR: Christopher James Hayward

,#+EXPORT_FILE_NAME: ${slug}
,#+ROAM_KEY: https://chrishayward.xyz/notes/${slug}/

,#+HUGO_BASE_DIR: ../
,#+HUGO_AUTO_SET_LASTMOD: t
,#+HUGO_SECTION: notes
,#+HUGO_DRAFT: true
")))

Slides

Produce high quality presentations that work anywhere with HTML/JS and the reveal.js package. ox-reveal, configured to use a cdn allows us to produce ones that are not dependent on a local version of reveal.js.

(use-package ox-reveal
  :after ox
  :custom (org-reveal-root "https://cdn.jsdelivr.net/npm/reveal.js"))

Create a capture template for creating slides quickly, with our desired configuration.

(with-eval-after-load 'org-roam
  (add-to-list 'org-roam-capture-templates
               '("s" "Slides" plain (function org-roam-capture--get-point)
                 "%?"
                 :file-name "docs/slides/${slug}"
                 :unnarrowed t
                 :head
"
,#+TITLE: ${title}
,#+AUTHOR: Christopher James Hayward
,#+EMAIL: chris@chrishayward.xyz

,#+REVEAL_ROOT: https://cdn.jsdelivr.net/npm/reveal.js
,#+REVEAL_THEME: serif

,#+EXPORT_FILE_NAME: ${slug}

,#+OPTIONS: reveal_title_slide:nil
,#+OPTIONS: num:nil toc:nil todo:nil tasks:nil tags:nil
,#+OPTIONS: skip:nil author:nil email:nil creator:nil timestamp:nil
")))

Agenda

Override org-agenda-file-regexp to include .org.gpg files.

(unless (string-match-p "\\.gpg" org-agenda-file-regexp)
  (setq org-agenda-file-regexp
        (replace-regexp-in-string "\\\\\\.org" "\\\\.org\\\\(\\\\.gpg\\\\)?"
                                  org-agenda-file-regexp)))

Create a capture template for courses.

(with-eval-after-load 'org-roam
  (add-to-list 'org-roam-capture-templates
               '("c" "Course" plain (function org-roam-capture--get-point)
               "%?"
               :file-name "docs/courses/${slug}"
               :unnarrowed t
               :head
"
,#+TITLE: ${title}
,#+SUBTITLE:
,#+AUTHOR: Christopher James Hayward
,#+EMAIL: chris@chrishayward.xyz

,#+OPTIONS: num:nil toc:nil todo:nil tasks:nil tags:nil
,#+OPTIONS: skip:nil author:nil email:nil creator:nil timestamp:nil
")))

Configure agenda sources.

(setq org-agenda-files '("~/.emacs.d/docs/"
                         "~/.emacs.d/docs/courses/"
                         "~/.emacs.d/docs/daily/"))

Open an agenda buffer with SPC a.

(dotfiles/leader
  "a" '(org-agenda :which-key "Agenda"))

Images

Capture screenshots with screenshot.el.

(use-package screenshot
  :commands (screenshot))

Create screencasts with one-frame-per-action GIF recording via emacs-gif-screencast.

• Pause / Resume

• High Quality

• Optimized

It requires the installation of scrot, gifsicle, and convert from the ImageMagick library.

(use-package gif-screencast
  :commands (gif-screencast-start-or-stop gif-screencast-toggle-pause)
  :custom (gif-screencast-output-directory (concat dotfiles/home "docs/images/")))

Place keybindings behind SPC s.

• Screenshot with s

• Screencast with c

(dotfiles/leader
  "s" '(:ignore t :which-key "Screen")
  "ss" '(screenshot :which-key "Screenshot")
  "sc" '(gif-screencast-start-or-stop :which-key "Screencast"))

Grammar

I use writegood-mode to find common writing problems such as cliches and poor wording. Grammarly for the peons!

(use-package writegood-mode
  :after org
  :config (writegood-mode))

Toggle writegood mode with SPC t w.

(dotfiles/leader
  "tw" '(writegood-mode :which-key "Grammar"))

Spelling

Use the built in ispell package to add spell checking features to buffers.

(use-package ispell
  :after org
  :custom (ispell-dictionary dotfiles/lang))

Toggle highlighting within buffers with SPC t s.

(dotfiles/leader
  "ts" '(flyspell-buffer :which-key "Spelling"))

Projects

An IDE like experience (or better) can be achieved in Emacs using two Microsoft open source initiatives.

• Language Server Protocol

• Debug Adapter Protocol

Add support for language servers with lsp-mode.

(use-package lsp-mode
  :commands (lsp lsp-deferred)
  :custom (lsp-idle-delay (* 5 dotfiles/idle)))

lsp-ui provides UI improvements for lsp-mode.

(use-package lsp-ui
  :after lsp
  :custom (lsp-ui-doc-position 'at-point)
          (lsp-ui-doc-delay 0.500))

Dap-mode adds support for the debug adapter protocol to Emacs.

(use-package dap-mode
  :commands (dap-debug))

Containers

Use docker for running containers. Download and install https://github.com/Silex/docker.el, allowing us to manage containers within Emacs.

(use-package docker
  :commands (docker))

Open the management screen with SPC k.

(dotfiles/leader
  "k" '(docker :which-key "Docker"))

Management

Configure projectile, a project interaction library for Emacs. It provides a nice set of features for operating on a project level without introducing external dependencies.

(use-package projectile
  :custom (projectile-project-search-path '("~/.local/source"))
  :config (projectile-mode))

Completion

Text completion framework via company aka Complete Anything.

http://company-mode.github.io/

• Integrate with lsp-mode

(use-package company
  :after lsp)

(use-package company-lsp
  :after (lsp company)
  :custom (company-backend 'company-lsp))

Passwords

Pass makes managing passwords extremely easy, encrypring them in a file structure and providing easy commands for generating, modify, and copying passwords. password-store.el provides a wrapper for the functionality within Emacs.

(use-package password-store
  :custom (password-store-dir dotfiles/passwords))

Configure keybindings behind SPC p.

• Copy with p

• Rename with r

• Generate with g

(dotfiles/leader
  "p" '(:ignore t :which-key "Passwords")
  "pp" '(password-store-copy :which-key "Copy")
  "pr" '(password-store-rename :which-key "Rename")
  "pg" '(password-store-generate :which-key "Generate"))

Languages

Support for individual languages are implemented here.

Go

Install the gopls language server.

GO111MODULE=on go get golang.org/x/tools/gopls@latest

Set the GOPATH environment variable prior to loading, this allows us to change the default value of $HOME/go to $HOME/.go.

(setenv "GOPATH" (concat (getenv "HOME") "/.go/"))

Additionally, include the bin subdirectory of the $GOPATH in the $PATH variable, adding compiled golang programs.

(setenv "PATH" (concat (getenv "GOPATH") "bin:" (getenv "PATH")))

Finally we can include the go-mode package, integrating it with lsp.

(use-package go-mode
  :hook (go-mode . lsp)
  :custom (lsp-go-gopls-server-path "~/.go/bin/gopls"))

Apply some custom behaviour before saving:

• Format buffer

• Organize imports

(defun dotfiles/go-hook ()
  (add-hook 'before-save-hook #'lsp-format-buffer t t)
  (add-hook 'before-save-hook #'lsp-organize-imports t t))

(add-hook 'go-mode-hook #'dotfiles/go-hook)

Add a golang source code block structure template with <go:

(add-to-list 'org-structure-template-alist '("go" . "src go"))

HTTP

Instead of the popular restclient package, I use ob-http as a lightweight alternative.

(use-package ob-http
  :after org
  :config (org-babel-do-load-languages
            'org-babel-load-languages
            '((http . t))))

C/C++

Add support for C/C++ languages.

• Configure the ccls language server

• Load babel language modules for C/C++

• Create a new structure templates for C/C++

  • <cc for C

  • <cpp for C++

(use-package ccls
  :hook ((c-mode c++-mode objc-mode cuda-mode) .
         (lambda ()
           (require 'ccls)
           (lsp-deferred)))
  :config (add-to-list 'org-structure-template-alist '("cc" . "src C"))
          (add-to-list 'org-structure-template-alist '("cpp" . "src C++"))
          (org-babel-do-load-languages 'org-babel-load-languages '((C . t))))

Python

Install the pyls language server.

pip3 install --user "python-language-server[all]"

Python-mode is an Emacs built in mode.

• Load the babel language module for Python

• Add a python source code block structure template with <py

(use-package python-mode
  :hook (python-mode . lsp-deferred)
  :config (require 'dap-python)
          (add-to-list 'org-src-lang-modes '("python" . python))
          (add-to-list 'org-structure-template-alist '("py" . "src python"))
          (org-babel-do-load-languages 'org-babel-load-languages '((python . t)))
  :custom (python-shell-interpreter "python3") ;; Required if "python" is not python 3.
          (dap-python-executable "python3")    ;; Same as above.
          (dap-python-debugger 'debugpy))

PlantUML

Download and install PlantUML, a text-based markup language for creating UML diagrams.

• Load the babel language module for PlantUML

• Create a structure template with <pl

(use-package plantuml-mode
  :after org
  :custom (plantuml-default-exec-mode 'jar)
          (plantuml-jar-path "~/.local/bin/plantuml.jar")
          (org-plantuml-jar-path (expand-file-name "~/.local/bin/plantuml.jar"))
          (org-startup-with-inline-images t)
  :config (add-to-list 'org-src-lang-modes '("plantuml" . plantuml))
          (add-to-list 'org-structure-template-alist '("pl" . "src plantuml"))
          (org-babel-do-load-languages 'org-babel-load-languages '((plantuml . t))))

Toggle inline images with SPC t i.

(dotfiles/leader
  "ti" '(org-toggle-inline-images :which-key "Images"))

Interface

Bring Emacs out of the eighties

Ivy

Download and configure ivy, a powerful selection menu for Emacs.

(use-package ivy
  :diminish
  :config (ivy-mode 1))

Counsel is a customized set of commands to replace built in completion buffers.

(use-package counsel
  :after ivy
  :custom (counsel-linux-app-format-function #'counsel-linux-app-format-function-name-only)
  :config (counsel-mode 1))

Switch buffers with SPC , (comma).

(dotfiles/leader
  "," '(counsel-switch-buffer :which-key "Buffers"))

Provide more information about each item with ivy-rich.

(use-package ivy-rich
  :after counsel
  :init (ivy-rich-mode 1))

Fonts

Write out to all 3 of Emacs' default font faces.

(set-face-attribute 'default nil :font dotfiles/font :height dotfiles/font-size)
(set-face-attribute 'fixed-pitch nil :font dotfiles/font :height dotfiles/font-size)
(set-face-attribute 'variable-pitch nil :font dotfiles/font :height dotfiles/font-size)

Define a transient keybinding for scaling the text.

(defhydra hydra-text-scale (:timeout 4)
  "Scale"
  ("j" text-scale-increase "Increase")
  ("k" text-scale-decrease "Decrease")
  ("f" nil "Finished" :exit t))

Increase the font size in buffers with SPC t f.

• Increase j

• Decrease k

• Finish f

(dotfiles/leader
  "tf" '(hydra-text-scale/body :which-key "Font"))

Lines

Relative line numbers are important when using VI emulation keys. You can prefix most commands with a number, allowing you to jump up / down by a line count.

  5:
  4:
  3:
  2:
  1:
156: << CURRENT LINE >>
  1:
  2:
  3:
  4:
  5:

https://github.com/emacsmirror/linum-relative

• Integrate with display-line-numbers-mode for performance

(use-package linum-relative
  :commands (linum-relative-global-mode)
  :custom (linum-relative-backend 'display-line-numbers-mode))

Add line numbers to the toggles behind SPC t l.

(dotfiles/leader
  "tl" '(linum-relative-global-mode :which-key "Lines"))

https://github.com/Fanael/rainbow-delimiters

• Colourize nested parenthesis

(use-package rainbow-delimiters
  :hook (prog-mode . rainbow-delimiters-mode))

Themes

Cherry pick a few modules from doom-emacs. High quality and modern colour themes are provided in the doom-themes package.

(use-package doom-themes
  :init (load-theme 'doom-moonlight t))

doom-modeline provides an elegant status bar / modeline.

(use-package doom-modeline
  :custom (doom-modeline-height 16)
  :config (doom-modeline-mode 1))

Load a theme with SPC t t.

(dotfiles/leader
  "tt" '(counsel-load-theme t t :which-key "Theme"))

Pretty

Make programming buffers prettier with pretty-mode, complimentary to the built in prettify-symbols-mode.

(use-package pretty-mode
  :hook (python-mode . turn-on-pretty-mode))

Ligatures

Enable font ligatures via fira-code-mode, perform this action only when Fira Code is the current font.

(when (display-graphic-p)
  (use-package fira-code-mode
    :hook (prog-mode org-mode)))

Toggle global ligature mode with SPC t g.

(dotfiles/leader
  "tg" '(global-fira-code-mode :which-key "Ligatures"))

Dashboard

Present a dashboard when first launching Emacs. Customize the buttons of the navigator:

• Brain @ http://localhost:8080

• Homepage @ https://chrishayward.xyz

• Athabasca @ https://login.athabascau.ca/cas/login

• Bookshelf @ https://online.vitalsource.com

(use-package dashboard
  :custom (dashboard-center-content t)
          (dashboard-set-init-info t)
          (dashboard-set-file-icons t)
          (dashboard-set-heading-icons t)
          (dashboard-set-navigator t)
          (dashboard-startup-banner 'logo)
          (dashboard-projects-backend 'projectile)
          (dashboard-items '((projects . 5) (recents  . 5) (agenda . 10)))
          (dashboard-navigator-buttons `(((,(all-the-icons-fileicon "brain" :height 1.1 :v-adjust 0.0)
                                          "Brain" "Knowledge base"
                                          (lambda (&rest _) (browse-url "http://localhost:8080"))))
                                         ((,(all-the-icons-material "public" :height 1.1 :v-adjust 0.0)
                                          "Homepage" "Personal website"
                                          (lambda (&rest _) (browse-url "https://chrishayward.xyz"))))
                                         ((,(all-the-icons-faicon "university" :height 1.1 :v-adjust 0.0)
                                          "Athabasca" "Univeristy login"
                                          (lambda (&rest _) (browse-url "https://login.athabascau.ca/cas/login"))))
                                         ((,(all-the-icons-faicon "book" :height 1.1 :v-adjust 0.0)
                                          "Bookshelf" "Vitalsource bookshelf"
                                          (lambda (&rest _) (browse-url "https://online.vitalsource.com"))))))
  :config (dashboard-setup-startup-hook))

When running in daemon mode, ensure that the dashboard is the initial buffer.

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