Dotfiles

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

• 100% Literate

• 100% Immutable

• 100% Reproducible

Init

This section controls initialization of the system, everything is available from a top-down perspective at this stage in the configuration.

Hosts

Here's a complete list of all of the options configurable for each host, and their default values. All variables prefixed with dotfiles/. If you need to make configurations to another variable, consider creating a new option.

Name	Description
dotfiles/font	Unified system font family
dotfiles/font-size	System wide base font size
dotfiles/browser	Browser to open URL links
dotfiles/language	Dictionary language to load
dotfiles/modules-p	Immutable list of all available modules
dotfiles/modules	Enabled custom modules
dotfiles/home	Original value of `user-emacs-directory'
dotfiles/cache	Redirection target of `user-emacs-directory
dotfiles/idle	Delay time before offering completions
dotfiles/leader-key	All powerful keybinding prefix for custom actions
dotfiles/leader-key-global	Like the leader-key, but EVERYWHERE!
dotfiles/projects	Location of source code projects
dotfiles/passwords	Location of the system password store
dotfiles/public-key	Public GPG key to encrypt files for

Override any of the available options configurations in a host file. Here's some examples to get started:

• Termux

• Raspberry

• Acernitro

• Virtualbox

(defvar dotfiles/font "Fira Code")
(defvar dotfiles/font-size 96)
(defvar dotfiles/browser (getenv "BROWSER"))
(defvar dotfiles/language (getenv "LANG"))
(defconst dotfiles/modules-p '(core editor email desktop writing projects interface))
(defvar dotfiles/modules dotfiles/modules-p)
(defvar dotfiles/home user-emacs-directory)
(defvar dotfiles/cache (expand-file-name "~/.cache/emacs"))
(defvar dotfiles/idle 0.0)
(defvar dotfiles/leader-key "SPC")
(defvar dotfiles/leader-key-global (concat "C-" dotfiles/leader-key))
(defvar dotfiles/projects (expand-file-name "~/.local/source/"))
(defvar dotfiles/passwords (expand-file-name "~/.password-store/"))
(defvar dotfiles/public-key "37AB1CB72B741E478CA026D43025DCBD46F81C0F")

Begin the process by loading any host specific overrides. The host configuration tangles, and loads (if it exist) using the systems name.

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

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. Here are all of the available modules, also listed in the variable dotfiles/modules-p.

• Core

• Editor

• Email

• Desktop

By default all of the modules will load, override the variable dotfiles/modules in a host configuration to override this.

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

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*")))