My Emacs Configuration

This Org Mode document contains my configuration for Emacs, which is currently a work in progress. Changes made to the configuration here are automatically tangled when saved. As such, all configuration changes should be made here.

The configuration here gets placed in an early init file to prevent certain actions from occuring before getting to the main init file.

Since I am using straight.el The first thing we need to do is stop package.el from loading packages.

;; Prevent package.el from loading packages
(setq package-enable-at-startup nil)

Here, we make sure we’re starting with a minimal user interface.

;; Disable the menu bar
(menu-bar-mode -1)

;; Disable the tool bar
(tool-bar-mode -1)

;; Disable the scroll bar
(scroll-bar-mode -1)

;; Disable the splash screen
(setq inhibit-splash-screen t)

Here we specify the main Emacs configuration.

Add a note to the header to remind me not to edit that file.

;; NOTE: init.el is generated from emacs.org. Please edit that file instead!

I chose to use straight.el for my package management. I like the principles of the project, and changing package managers will help me stop simply copying other people’s configuration without trying to figure it out myself.

;; Bootstrap code needed to download and build straight.el
(defvar bootstrap-version)
(let ((bootstrap-file
       (expand-file-name "straight/repos/straight.el/bootstrap.el" user-emacs-directory))
      (bootstrap-version 6))
  (unless (file-exists-p bootstrap-file)
    (with-current-buffer
        (url-retrieve-synchronously
         "https://raw.githubusercontent.com/radian-software/straight.el/develop/install.el"
         'silent 'inhibit-cookies)
      (goto-char (point-max))
      (eval-print-last-sexp)))
  (load bootstrap-file nil 'nomessage))

;; Use straight.el for use-package expressions
(straight-use-package 'use-package)

;; Automatically install packages without needing to specify so
(setq straight-use-package-by-default t)

no-littering avoids excessive clutter in the user-emacs-directory.

;; Use no-littering to automatically set common paths to the user-emacs-directory
(use-package no-littering)

;; no-littering doesn't set this by default so we must place auto save
;; files in the same path as it uses for sessions
(setq auto-save-file-name-transforms
      `((".*" ,(no-littering-expand-var-file-name "auto-save/") t)))

;; Keep customization settings in a temporary file
(setq custom-file
      (if (boundp 'server-socket-dir)
          (expand-file-name "custom.el" server-socket-dir)
        (expand-file-name (format "emacs-custom-%s.el" (user-uid)) temporary-file-directory)))
(load custom-file t)

Here we make some general configuration tweaks to the user interface, such as transparency, line numbers, etc..

;; Use pixel wise frame size
(setq frame-resize-pixelwise t)

;; Make frame transparency overridable
(defvar jdw/frame-transparency '(97 . 97))

; Disable tooltips
(tooltip-mode -1)

; Give some breathing room
(set-fringe-mode 10)

;; Set up the visible bell
(setq visible-bell t)

;; Enable column and line number modes
(column-number-mode)
(global-display-line-numbers-mode t)

;; Set frame transparency
(set-frame-parameter (selected-frame) 'alpha jdw/frame-transparency)
(add-to-list 'default-frame-alist `(alpha . ,jdw/frame-transparency))

;; Disable line numbers for some modes
(dolist (mode '(org-mode-hook
                eshell-mode-hook))
  (add-hook mode (lambda () (display-line-numbers-mode 0))))

I am using the Fira Code fonts. Let’s set font sizes for various fonts.

NOTE: The font size will likely need to change from system to system.

;; Specify the font size
(defvar jdw/default-font-size 120)
(defvar jdw/default-variable-font-size 140)
(defvar jdw/default-variable-font-weight 'regular)

;; Set font faces
(defun jdw/set-font-faces ()

  ;; Set the default face
  (set-face-attribute 'default nil
                      :font "Fira Code Retina"
                      :height jdw/default-font-size)

  ;; Set the fixed pitch face
  (set-face-attribute 'fixed-pitch nil
                      :font "Fira Code Retina"
                      :height jdw/default-font-size)

  ;; Set the variable pitch face
  (set-face-attribute 'variable-pitch nil
                      :font "Fira Sans"
                      :height jdw/default-variable-font-size
                      :weight jdw/default-variable-font-weight)

  ;; Make commented text and keywords italics.
  ;; Your font must have an italic face available.
  (set-face-attribute 'font-lock-comment-face nil
                      :slant 'italic)
  (set-face-attribute 'font-lock-keyword-face nil
                      :slant 'italic))

;; Uncomment the following line if line spacing needs adjusting.
(setq-default line-spacing 0.12)

;; Needed if using emacsclient. Otherwise, your fonts will be smaller than expected.
(add-to-list 'default-frame-alist '(font . "Fira Code Retina-12"))

;; Changes certain keywords to symbols, such as lamda!
(setq global-prettify-symbols-mode t)

;; Call font face function differently if using daemon
(if (daemonp)
    (add-hook 'after-make-frame-functions
              (lambda (frame)
                (with-selected-frame frame
                  (jdw/set-font-faces))))
  (jdw/set-font-faces))

doom-themes is a great set of themes with a lot of variety and support for many different Emacs modes, and the screenshots can help decide without manually booting up each theme to decide.

;; Use doom-themes for color themes
(use-package doom-themes
  :config

  ;; Enable bold and italics
  (setq doom-themes-enable-bold t
        doom-themes-enable-italic t)

  ;; Load the Dracula theme
  (load-theme 'doom-gruvbox t)

  ;; Enable flashing mode-line on errors
  (doom-themes-visual-bell-config)

  ;; Corrects (and improves) org-mode's native fontification.
  (doom-themes-org-config))

doom-modeline is a very attractive and rich (yet still minimal) mode line configuration for Emacs. The default configuration is quite good but you can check out the configuration options for more things you can enable or disable.

NOTE: The first time you load your configuration on a new machine, you’ll need to run M-x all-the-icons-install-fonts so that mode line icons display correctly.

;; Use all-the-icons to view symbols in the modeline
(use-package all-the-icons)

;; Use doom-modeline for a prettier modeline
(use-package doom-modeline
  :hook (after-init . doom-modeline-mode)
  :custom ((doom-modeline-height 30)
           (doom-modeline-icon t)))

I kind of like the doom-emacs dashboard, so let’s try using out dashboard.

;; Install nerd icons
(use-package nerd-icons)

(use-package dashboard
  :ensure t
  :config
  (dashboard-setup-startup-hook)
  :custom

  ;; Set the title
  (dashboard-banner-logo-title "Welcome to Emacs Dashboard!")

  ;; Set the banner
  (dashboard-startup-banner 1)

  ;; Limit items that appear and specify what appears
  (dashboard-items '((recents  . 5)
                   (bookmarks . 5)
                   (projects . 5)
                   (agenda . 5)))

  ;; Display icons
  (dashboard-display-icons-p t)
  (dashboard-icon-type 'nerd-icons)
  (dashboard-set-heading-icons t)
  (dashboard-set-file-icons t)

)

General allows leader key binding, which I will choose as SPC.

(use-package general
  :config
  (general-evil-setup t)

  (general-create-definer jdw/leader-key-def
                          :keymaps '(normal insert visual emacs)
                          :prefix "SPC"
                          :global-prefix "C-SPC")

  (general-create-definer jdw/ctrl-c-keys
                          :prefix "C-c"))


;; Files
(jdw/leader-key-def
  "f"   '(:ignore t :which-key "files")
  "ff" 'find-file
  "fs" 'save-buffer)

;; Search
(jdw/leader-key-def 
  "s" '(:ignore t :which-key "search")
  "sb" 'consult-line
  "sr" 'query-replace)

;; Toggles
(jdw/leader-key-def
  "t"  '(:ignore t :which-key "toggles")
  "tt" '(consult-theme :which-key "choose theme"))

Evil is a vi layer for Emacs. It changes a lot of key bindings and other features to be more like vi. I rarely use vi, but I do prefer the typical key bindings.

;; Add hooks for evil
(defun jdw/evil-hook ()
  (dolist (mode '(custom-mode
                  eshell-mode
                  git-rebase-mode
                  term-mode)) 
    (add-to-list 'evil-emacs-state-modes mode)))

;; Remind me to get back to the home row of keys
(defun jdw/dont-use-arrows ()
  (interactive)
  (message "Get back on the home row!"))

;; Use vi-like undo state preservation
(use-package undo-tree
  :init
  (global-undo-tree-mode 1)
  :config
  ;; Prevent undo tree files from polluting your git repo
  (setq undo-tree-history-directory-alist '(("." . "~/.emacs.d/undo"))))

;; Use evil
(use-package evil
  :init
  (setq evil-want-integration t)
  (setq evil-want-keybinding nil)
  (setq evil-want-C-u-scroll t)
  (setq evil-want-C-i-jump nil)
  (setq evil-respect-visual-line-mode t)
  (setq evil-undo-system 'undo-tree)
  :config
  (add-hook 'evil-mode-hook 'jdw/evil-hook)
  (evil-mode 1)
  (define-key evil-insert-state-map (kbd "C-g") 'evil-normal-state)
  (define-key evil-insert-state-map (kbd "C-h") 'evil-delete-backward-char-and-join)

  ;; Use visual line motions even outside of visual-line-mode buffers
  (evil-global-set-key 'motion "j" 'evil-next-visual-line)
  (evil-global-set-key 'motion "k" 'evil-previous-visual-line)

  ;; Disable arrow keys in normal and visual modes
  (define-key evil-normal-state-map (kbd "<left>") 'jdw/dont-use-arrows)
  (define-key evil-normal-state-map (kbd "<right>") 'jdw/dont-use-arrows)
  (define-key evil-normal-state-map (kbd "<down>") 'jdw/dont-use-arrows)
  (define-key evil-normal-state-map (kbd "<up>") 'jdw/dont-use-arrows)
  (evil-global-set-key 'motion (kbd "<left>") 'jdw/dont-use-arrows)
  (evil-global-set-key 'motion (kbd "<right>") 'jdw/dont-use-arrows)
  (evil-global-set-key 'motion (kbd "<down>") 'jdw/dont-use-arrows)
  (evil-global-set-key 'motion (kbd "<up>") 'jdw/dont-use-arrows)

  ;; Set initial states
  (evil-set-initial-state 'messages-buffer-mode 'normal)
  (evil-set-initial-state 'dashboard-mode 'normal))

;; Load in additional evil keybindings
(use-package evil-collection
  :after evil
  :init
  (setq evil-collection-company-use-tng nil)  ;; Is this a bug in evil-collection?
  :custom
  (evil-collection-outline-bind-tab-p nil)
  :config
  (setq evil-collection-mode-list
        (remove 'lispy evil-collection-mode-list))
  (evil-collection-init))

Evil-Org-Mode is an extension of Evil into Org-Mode.

;; Use evil-org for evil extensions to org-mode
(use-package evil-org
  :after org
  :hook ((org-mode . evil-org-mode)
         (org-agenda-mode . evil-org-mode)
         (evil-org-mode . (lambda () (evil-org-set-key-theme
                                      '(navigation todo insert textobjects additional)))))
  :config
  (require 'evil-org-agenda)
  (evil-org-agenda-set-keys))

;; Add to leader key bindings
(jdw/leader-key-def
 "o"   '(:ignore t :which-key "org mode")
 "oi"  '(:ignore t :which-key "insert")
 "oil" '(org-insert-link :which-key "insert link")
 "on"  '(org-toggle-narrow-to-subtree :which-key "toggle narrow")
 "oa"  '(org-agenda :which-key "status")
 "ot"  '(org-todo-list :which-key "todos")
 "oc"  '(org-capture t :which-key "capture")
 "ox"  '(org-export-dispatch t :which-key "export"))

which-key is a useful UI panel that appears when you start pressing any key binding in Emacs to offer you all possible completions for the prefix. For example, if you press C-c (hold control and press the letter c), a panel will appear at the bottom of the frame displaying all of the bindings under that prefix and which command they run. This is very useful for learning the possible key bindings in the mode of your current buffer.

(use-package which-key
  :defer 0
  :diminish which-key-mode
  :config
  (which-key-mode)
  (setq which-key-idle-delay 1))

super-save automatically auto-saves changed files when certain events occur, such as buffer changes.

(use-package super-save
  :defer 1
  :diminish super-save-mode
  :config
  (super-save-mode +1)
  (setq super-save-auto-save-when-idle t))

hl-todo is a useful tool to highlight keywords like TODO or BUG.

;; Use hl-todo to highlight keywords
(use-package hl-todo
  :init
  (global-hl-todo-mode))

rainbow-delimiters is useful in programming modes because it colorizes nested parentheses and brackets according to their nesting depth. This makes it a lot easier to visually match parentheses in Emacs Lisp code without having to count them yourself.

;; Use rainbow colors for things like parentheses and brackets
(use-package rainbow-delimiters
  :hook (prog-mode . rainbow-delimiters-mode))

Rainbow Mode enables visualization of color codes like #BD93F9 in Emacs.

;; Use rainbow mode to see color codes highlighted
(use-package rainbow-mode
  :hook prog-mode org-mode)

Flycheck provides on the fly syntax checking.

(use-package flycheck
  :defer t
  :hook (lsp-mode . flycheck-mode))

Org Mode is one of the hallmark features of Emacs. It is a rich document editor, project planner, task and time tracker, blogging engine, and literate coding utility all wrapped up in one package.

The jdw/org-font-setup function configures various text faces to tweak the sizes of headings and use variable width fonts in most cases so that it looks more like we’re editing a document in org-mode. We switch back to fixed width (monospace) fonts for code blocks and tables so that they display correctly.

;; Function to call for specifying org-mode fonts
(defun jdw/org-font-setup ()

  ;; Replace list hyphen with dot
  (font-lock-add-keywords 'org-mode
                          '(("^ *\\([-]\\) "
                             (0 (prog1 () (compose-region (match-beginning 1) (match-end 1) "•"))))))

  ;; Set faces for heading levels
  (dolist (face '((org-level-1 . 1.1)
                  (org-level-2 . 1.1)
                  (org-level-3 . 1.1)
                  (org-level-4 . 1.1)
                  (org-level-5 . 1.1)
                  (org-level-6 . 1.1)
                  (org-level-7 . 1.1)
                  (org-level-8 . 1.1)))
    (set-face-attribute (car face) nil :font "Fira Sans" :weight 'regular :height (cdr face)))

  ;; Ensure that anything that should be fixed-pitch in Org files appears that way
  (set-face-attribute 'org-block nil :foreground nil :inherit 'fixed-pitch)
  (set-face-attribute 'org-table nil :inherit 'fixed-pitch)
  (set-face-attribute 'org-formula nil :inherit 'fixed-pitch)
  (set-face-attribute 'org-code nil :inherit '(shadow fixed-pitch))
  (set-face-attribute 'org-table nil :inherit '(shadow fixed-pitch))
  (set-face-attribute 'org-verbatim nil :inherit '(shadow fixed-pitch))
  (set-face-attribute 'org-special-keyword nil :inherit '(font-lock-comment-face fixed-pitch))
  (set-face-attribute 'org-meta-line nil :inherit '(font-lock-comment-face fixed-pitch))
  (set-face-attribute 'org-checkbox nil :inherit 'fixed-pitch)
  (set-face-attribute 'line-number nil :inherit 'fixed-pitch)
  (set-face-attribute 'line-number-current-line nil :inherit 'fixed-pitch)

  ;; Change LaTeX font size
  (setq org-format-latex-options (plist-put org-format-latex-options :scale 1.5)))

This section contains the basic configuration for org-mode.

;; Function for basic org-mode setup
(defun jdw/org-mode-setup ()
  (org-indent-mode)
  (variable-pitch-mode 1)
  (visual-line-mode 1))

;; Load the org package
(use-package org
  ;;:pin org
  :commands (org-capture org-agenda)
  :hook (org-mode . jdw/org-mode-setup)
  :bind (("C-c a" . org-agenda))
  :config

  ;; Hide emphasis markers on formatted text
  (setq org-hide-emphasis-markers t)

  ;; Specify elipsis symbol
  (setq org-ellipsis " ▾")

  ;; Change org-mode logging
  (setq org-agenda-start-with-log-mode t)
  (setq org-log-done 'time)
  (setq org-log-into-drawer t)

  ;; Specify files to build org-agenda
  (setq org-agenda-files
        '("~/Documents/Org/inbox.org"
          "~/Documents/Org/todo.org"))

  ;; Track habits with org-habit
  (require 'org-habit)
  (add-to-list 'org-modules 'org-habit)
  (setq org-habit-graph-column 60)

  ;; Customize todo keywords
  (setq org-todo-keywords
    '((sequence "TODO(t)" "NEXT(n)" "EVENT(e)" "|" "DONE(d!)")))

  ;; Customize tags
  (setq org-tag-alist
    '((:startgroup)
       ; Put mutually exclusive tags here
       (:endgroup)
       ("@home" . ?H)
       ("@work" . ?W)
       ("errand" . ?e)
       ("agenda" . ?a)
       ("chore" .?c)
       ("idea" . ?i)))

  ;; Place org agenda tags column
  (setq org-agenda-tags-column 0)

  ;; Only one space after a tag
  (setq org-tags-column 0)

  ;; Set up org-mode fonts
  (jdw/org-font-setup)

  ;; Evil implementiation
  (evil-define-key '(normal insert visual) org-mode-map (kbd "C-j") 'org-next-visible-heading)
  (evil-define-key '(normal insert visual) org-mode-map (kbd "C-k") 'org-previous-visible-heading)
  (evil-define-key '(normal insert visual) org-mode-map (kbd "M-j") 'org-metadown)
  (evil-define-key '(normal insert visual) org-mode-map (kbd "M-k") 'org-metaup))

org-bullets replaces the heading stars in org-mode buffers with nicer looking characters that you can control.

;; Use nicer looking bullets for org-mode
(use-package org-bullets
  :hook (org-mode . org-bullets-mode)
  :config
  (setq org-hide-leading-stars t)
  :custom
  (org-bullets-bullet-list '("◉" "○" "●" "○" "●" "○" "●")))

We use visual-fill-column to center org-mode buffers for a more pleasing writing experience as it centers the contents of the buffer horizontally to seem more like you are editing a document. This is really a matter of personal preference so you can remove the block below if you don’t like the behavior.

;; Specify visual-fill centering settings
(defun jdw/org-mode-visual-fill ()
  (setq visual-fill-column-width 120
        visual-fill-column-center-text t)
  (visual-fill-column-mode 1))

(defun jdw/dashboard-mode-visual-fill ()
  (setq visual-fill-column-width 100
        visual-fill-column-center-text t)
  (visual-fill-column-mode 1))

;; Use visual-fill-column to center org-mode buffers
(use-package visual-fill-column
  :hook ((org-mode . jdw/org-mode-visual-fill)
          (dashboard-mode . jdw/dashboard-mode-visual-fill)))

To execute or export code in org-mode code blocks, you’ll need to set up org-babel-load-languages for each language you’d like to use. This page documents all of the languages that you can use with org-babel.

;; Specify org-babel languages
(with-eval-after-load 'org
  (org-babel-do-load-languages
      'org-babel-load-languages
      '((emacs-lisp . t)
        (python . t)
        (R . t)
        (lua . t)
        (shell . t)))
  (push '("conf-unix" . conf-unix) org-src-lang-modes))

Org Mode’s structure templates feature enables you to quickly insert code blocks into your Org files in combination with org-tempo by typing < followed by the template name like el or py and then press TAB. For example, to insert an empty emacs-lisp block below, you can type <el and press TAB to expand into such a block.

You can add more src block templates below by copying one of the lines and changing the two strings at the end, the first to be the template name and the second to contain the name of the language as it is known by Org Babel.

;; Apply structure templates to quickly insert code blocks in org files
(with-eval-after-load 'org

  ;; This is needed as of Org 9.2
  (require 'org-tempo)

  ;; Specify structure templates
  (add-to-list 'org-structure-template-alist '("sh" . "src shell"))
  (add-to-list 'org-structure-template-alist '("el" . "src emacs-lisp"))
  (add-to-list 'org-structure-template-alist '("py" . "src python"))
  (add-to-list 'org-structure-template-alist '("r" . "src R"))
  (add-to-list 'org-structure-template-alist '("lua" . "src lua")))

This snippet adds a hook to org-mode buffers so that jdw/org-babel-tangle-config gets executed each time such a buffer gets saved. This function checks to see if the file being saved is in the directory ~/.dotfiles/, and if so, tangles the file to the file path specified in the header arguments for the code block to tangle.

;; Automatically tangle our Emacs.org config file when we save it
(defun jdw/org-babel-tangle-config ()

  ;; Check when the buffer file is in my dot-file directory
  (when (string-equal (file-name-directory (buffer-file-name))
                      (expand-file-name "~/.dotfiles/"))

    ;; Dynamic scoping to the rescue
    (let ((org-confirm-babel-evaluate nil))
      (org-babel-tangle))))

;; Run the function after saving
(add-hook 'org-mode-hook (lambda () (add-hook 'after-save-hook #'jdw/org-babel-tangle-config)))

Org Roam is an Org Mode extension inspired by Roam and the Zettelkasten note-taking approach. I particularly like it because it solves the problem of organizing Org files, which has completely stopped several projects or throughts in their tracks before. With this approach, you just make the file, get your thoughts out there, and then move on.

;; Set up org-roam
(use-package org-roam
  :ensure t
  :custom
  (org-roam-directory "~/Documents/Org/OrgRoam")
  :bind (("C-c n l" . org-roam-buffer-toggle)
         ("C-c n f" . org-roam-node-find)
         ("C-c n i" . org-roam-node-insert))
  :config
  (org-roam-setup))

  ;; Org-Roam keys
  (jdw/leader-key-def 
    "n" '(:ignore t :which-key "org-roam")
    "nl" '(org-roam-buffer-toggle :which-key "toggle buffer")
    "nf" '(org-roam-node-find :which-key "find node")
    "ni" '(org-roam-node-insert :which-key "insert node"))

Projectile is a project interaction library for things like finding project files and navigating through projects.

;; Enable Projectile for project interactions
(use-package projectile
  ;; Hide minor mode string in the mode-line
  :diminish projectile-mode
  :config (projectile-mode)
  :demand t
  :bind-keymap
  ("C-c p" . projectile-command-map))

Consult-Projectile incorporates Consult into Projectile.

(use-package consult-projectile
  :after projectile
  :bind (("C-M-p" . consult-projectile-find-file)))

Evil Nerd Commenter allows for commenting that acts more like I’m used to from traditional IDEs, and a bit more.

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

dap-mode is an excellent package for bringing rich debugging capabilities to Emacs via the Debug Adapter Protocol. You should check out the configuration docs to learn how to configure the debugger for your language. Also make sure to check out the documentation for the debug adapter to see what configuration parameters are available to use for your debug templates!

(use-package dap-mode
  ;;:custom
  ;;(lsp-enable-dap-auto-configure nil)
  :config
  ;;(dap-ui-mode 1)
  ;;(dap-tooltip-mode 1)
  (require 'dap-node)
  (dap-node-setup))

I use Miniconda for my Python and R environment and package management. To integrate it with Emacs, we can use the conda package.

;; Configure conda package for anaconda integration
(use-package conda
  :init
  (setq conda-anaconda-home (expand-file-name "~/.miniconda"))
  (setq conda-env-home-directory (expand-file-name "~/.miniconda/")))

Magit is the best Git interface I’ve ever used. Common Git operations are easy to execute quickly using Magit’s command panel system.

;; Configure magit for git integration
(use-package magit)

;; Add leader key bindings 
(jdw/leader-key-def
 "g"   '(:ignore t :which-key "git")
 "gs"  'magit-status
 "gd"  'magit-diff-unstaged
 "gc"  'magit-branch-or-checkout
 "gl"  '(:ignore t :which-key "log")
 "glc" 'magit-log-current
 "glf" 'magit-log-buffer-file
 "gb"  'magit-branch
 "gP"  'magit-push-current
 "gp"  'magit-pull-branch
 "gf"  'magit-fetch
 "gF"  'magit-fetch-all
 "gr"  'magit-rebase)

Git Gutter helps by highlighting changes to the branch.

(use-package git-gutter
  :hook ((text-mode . git-gutter-mode)
         (prog-mode . git-gutter-mode))
  :config
  (setq git-gutter:update-interval 0.02))

(use-package git-gutter-fringe
  :config
  (define-fringe-bitmap 'git-gutter-fr:added [224] nil nil '(center repeated))
  (define-fringe-bitmap 'git-gutter-fr:modified [224] nil nil '(center repeated))
  (define-fringe-bitmap 'git-gutter-fr:deleted [128 192 224 240] nil nil 'bottom))