Document emacs configuration

modules/emacs/early-init.el

@@ -33,6 +33,7 @@
 
 (add-hook 'emacs-startup-hook #'hm/restore-file-name-handler-alist)
 
+;; Nix manages our packages
 (setq package-enable-at-startup nil)
 
 ;; Avoid expensive frame resizing. Inspired by Doom Emacs.

modules/emacs/init.el

@@ -9,7 +9,9 @@
 
 ;; For :diminish in (use-package).
 (require 'diminish)
-;; For :general in (use-package).
+;; For :general in (use-package). Needs to be included before
+;; everything else so `use-package' definitely already knows about
+;; `:general'.
 (use-package general
   :config
   (general-evil-setup t)
@@ -37,13 +39,16 @@
     "wd" '(delete-window :which-key "delete")
   )
 
+;; Better defaults that aren't defaults for some reason.
 (use-package better-defaults)
 
+;; Autocomplete
 (use-package company
   :diminish (company-mode)
   :config (global-company-mode)
   )
 
+;; Replacements for emacs built-ins that better integrate with `ivy'.
 (use-package counsel
   :diminish (counsel-mode)
   :config (counsel-mode 1)
@@ -61,31 +66,36 @@
     )
   )
 
+;; Direnv integration in emacs.
 (use-package direnv :config (direnv-mode))
 
+;; Vim keybindings
 (use-package evil
+  :custom
   ;; Disable default evil keybindings, since evil-collection is a superset
   ;; See https://github.com/emacs-evil/evil-collection/issues/60
-  :custom
   (evil-want-keybinding nil)
   (evil-want-integration t)
   :config (evil-mode 1)
   )
 
+;; Vim keybindings in other packages
 (use-package evil-collection
   :after (evil)
   :config (evil-collection-init)
   )
 
-(use-package fira-code-mode
-  :config (when window-system (global-fira-code-mode))
-  )
+;; Ligatures in GUI mode
+;; Should probably switch to ligature.el, but it isn't on MELPA (yet).
+(use-package fira-code-mode :config (when window-system (global-fira-code-mode)))
 
+;; Linting integration
 (use-package flycheck
   :diminish (flycheck-mode)
   :config (global-flycheck-mode)
   )
 
+;; Autocomplete framework
 (use-package ivy
   :custom
   (ivy-use-virtual-buffers t)
@@ -94,6 +104,7 @@
   :diminish (ivy-mode)
   )
 
+;; Ledger syntax support
 (use-package ledger-mode
   :mode "\\.journal\\'"
   :custom
@@ -105,8 +116,10 @@
   (ledger-post-auto-align t)
   )
 
+;; Language server support
 (use-package lsp-mode :commands (lsp))
 
+;; Git integration
 (use-package magit
   :general
   (nmap
@@ -116,6 +129,7 @@
     )
   )
 
+;; Markdown syntax support
 (use-package markdown-mode
   :commands (markdown-mode gfm-mode)
   :mode ("README\\.md\\'" . gfm-mode)
@@ -123,6 +137,7 @@
   :mode ("\\.markdown\\'" . markdown-mode)
   )
 
+;; Theming
 (use-package modus-themes
   :custom
   (modus-themes-bold-constructs t)
@@ -135,8 +150,10 @@
   (modus-themes-load-operandi)
   )
 
+;; Nix syntax support
 (use-package nix-mode :mode "\\.nix\\'")
 
+;; Project management
 (use-package projectile
   :after (ripgrep)
   :diminish (projectile-mode)
@@ -156,12 +173,13 @@
     )
   )
 
-(use-package python-mode
-  :mode "\\.py\\'"
-  )
+;; Python syntax support
+(use-package python-mode :mode "\\.py\\'")
 
+;; Ripgrep support (needed for `projectile-ripgrep')
 (use-package ripgrep)
 
+;; `ivy'-integrated `/'
 (use-package swiper
   :general
   (nmap
@@ -171,26 +189,35 @@
   (nmap "/" 'swiper)
   )
 
+;; HTML (and HTML template) support
 (use-package web-mode
   :mode "\\.html\\.erb\\'")
 
+;; Show keybindings
 (use-package which-key
   :diminish (which-key-mode)
   :config (which-key-mode)
   )
 
+;; YAML syntax support
 (use-package yaml-mode
   :mode "\\.yml\\'"
   :mode "\\.yaml\\'"
   )
 
-(setq inhibit-startup-screen t)
-
-(when window-system
-  (set-frame-font "Fira Code 9"))
+;; Enable basic auto pairs. Maybe replace this with something more
+;; advanced later? Look into configuring pairs for frequently used
+;; modes.
 (electric-pair-mode)
+
+;; Always display line numbers
 (global-display-line-numbers-mode)
 
+;; Don't show default startup screen
+(setq inhibit-startup-screen t)
+
+;; Font configuration
+(when window-system (set-frame-font "Fira Code 9"))
 (defun emoji-fonts ()
   "Setup emoji font priorities."
   (set-fontset-font t 'symbol "Noto Color Emoji")