dotfiles/README.org

Dotfiles

• Configuration
  • Packages
  • Cleanup
  • Keybindings
    • Evil
    • Font
    • Shortcuts
  • Editor
  • VCS
  • Files
  • Shell
  • Themes
  • Writing
• Development
  • Python
• Writing
  • Agenda
  • Blogging
  • Presentations

Immutable GNU Emacs dotfiles, inspired by Doom, built for Liberty.

• 100% Literate

• 100% Immutable

• 100% Reproducible

Configuration

Define a function to build literate programming projects.

(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))))

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")
(defvar dotfiles/font-size 96)

Functionality like completion and hints can be delayed to avoid popups for common manuevers. Adjust this value to your personal taste.

(defvar dotfiles/idle 0.0)

Avoid the infamous Emacs pinky by binding SPC as a leader key, utilizing the thumb instead of the weaker pinky finger. You may change this value if you want to use something else.

(defvar dotfiles/leader-key "SPC")

Stored source projects are in ~/.local/source/.

(defvar dotfiles/src "~/.local/source/")
(defvar dotfiles/brain (concat dotfiles/src "brain"))

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. To solve this issue, and to retain hermetic evaluation of the Emacs directory, we it to ~/.cache/emacs shortly after initialization, before most packages are loaded.

(defvar dotfiles/home user-emacs-directory)
(defvar dotfiles/cache "~/.cache/emacs")

(setq create-lockfiles nil
      make-backup-files nil
      user-emacs-directory dotfiles/cache)

Packages

https://github.com/raxod502/straight.el

• 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 are downloaded and built from source, and can be 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.

https://github.com/emacscollective/no-littering

• Reduce the files created by Emacs

(use-package no-littering)

Emacs' default user interface is horrendous, but with less than 10 lines of code we can change that.

(setq inhibit-startup-message t)
(global-prettify-symbols-mode)
(scroll-bar-mode -1)
(menu-bar-mode -1)
(tool-bar-mode -1)
(tooltip-mode -1)

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)

Keybindings

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

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

https://github.com/justbur/emacs-which-key

• Display the currently incomplete keybinding in a mini-buffer.

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

https://github.com/noctuid/general.el

• Easily configure prefixed keybindings

• Cleaner than default binding methods

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

https://github.com/abo-abo/hydra

• Transient keybindings sharing a common prefix

(use-package hydra)

Evil

After a few hour with vim I knew it was game over, I cannot even think of another way I would feel comfortable editing text. Luckily, there exist packages to emulate this within Emacs.

https://evil.readthedocs.io/en/latest/index.html

• Extendable VI layer for Emacs

• Disable default keybindings

(use-package evil
  :init (setq evil-want-integration t
	            evil-want-keybinding nil)
  :config (evil-mode 1))

https://github.com/emacs-evil/evil-collection

• Community keybindings for evil-mode

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

https://github.com/redguardtoo/evil-nerd-commenter

• Toggle comments with M-;

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

Font

Increase the font size in buffers with SPC f.

• Increase j

• Decrease k

• Finish f

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

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

Shortcuts

Again cherry picked from Doom, I want to continue utilizing the muscle memory I have developed from a year of mainlining the framework.

• Find files SPC . (period)

• Switch buffers with SPC , (comma)

(dotfiles/leader
  "," '(switch-to-buffer :which-key "Buffer")
  "." '(find-file :which-key "File"))

Quit emacs with SPC q.

• Saving q

• Without w

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

Window management with SPC w.

• Swap with w

• Close with c

• Delete with d

• 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")
  "wd" '(kill-buffer-and-window :which-key "Delete")
  "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"))

Editor

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
  :init (setq linum-relative-backend
	      'display-line-numbers-mode)
  :config (linum-relative-global-mode))

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

• Colourize nested parenthesis

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

VCS

Another flagship feature of Emacs is magit, a complete git porcelain within Emacs.

https://github.com/magit/magit

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

https://github.com/magit/forge

• Requires $GITHUB_TOKEN

(use-package forge)

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

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

Files

Emacs' can feel more modern when icon-fonts are installed and prioritized. I feel that this makes navigation of folders much faster, given that file types may be quickly identified by their corresponding icons.

https://github.com/domtronn/all-the-icons.el

• Collects various icon fonts

(use-package all-the-icons)

https://github.com/jtbm37/all-the-icons-dired

• Integration with dired

(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. This can be avoided with dired-jump, included in the dired-x package shipped with dired.

(require 'dired-x)

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 left wanting more, I would recommend they look into vterm.

https://github.com/zwild/eshell-prompt-extras

• Enable lambda shell prompt

(use-package eshell-prompt-extras
  :config (setq eshell-highlight-prompt nil
	            eshell-prompt-function 'epe-theme-lambda))

Open an eshell buffer with SPC e.

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

Themes

Bring Emacs' out of the eighties by cherry picking a few modules from Doom.

https://github.com/hlissner/emacs-doom-themes

• Modern colour themes

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

Load a theme with SPC t.

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

https://github.com/seagle0128/doom-modeline

• Elegant status bar / modeline

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

Writing

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.

• https://orgmode.org

• https://orgmode.org/worg/org-contrib/babel/languages/index.html

• https://orgmode.org/manual/Structure-Templates.html

(use-package org
  :hook
  (org-mode . (lambda ()
		(org-indent-mode)
		(visual-line-mode 1)
		(variable-pitch-mode 1)))
  :config
  (setq org-ellipsis " ▾"
	org-log-done 'time
	org-log-into-drawer t
	org-src-preserve-indentation t)

  (org-babel-do-load-languages
   'org-babel-load-languages
   '((shell . t)
     (python . t)
     (emacs-lisp . t)))

  (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 '("py" . "src python"))
  (add-to-list 'org-structure-template-alist '("el" . "src emacs-lisp")))

https://github.com/integral-dw/org-superstar-mode

• Make the headline stars more super

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

Development

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

• https://microsoft.github.io/language-server-protocol/

• https://microsoft.github.io/debug-adapter-protocol/

https://emacs-lsp.github.io/lsp-mode/

• Language servers for Emacs

(use-package lsp-mode
  :commands lsp
  :config
  (setq gc-cons-threshold 100000000
        lsp-completion-provider 'company-capf
        lsp-idle-delay dotfiles/idle))

https://emacs-lsp.github.io/lsp-ui/

• UI improvements for lsp-mode

(use-package lsp-ui
  :commands lsp-ui-mode
  :custom (lsp-ui-doc-position 'at-point))

https://emacs-lsp.github.io/dap-mode/

• Debug adapters for Emacs

(use-package dap-mode)

Text completion framework via company aka Complete Anything.

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

• Integrate with lsp-mode

(use-package company-lsp
  :commands company-lsp
  :custom (company-minimum-prefix-length 1))

Python

Full IDE experience for Python within Emacs.

• Completion, jumps via lsp-mode

• Debugging via dap-mode

Install the pyls language server.

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

https://www.emacswiki.org/emacs/PythonProgrammingInEmacs

• Built in mode

(use-package python-mode
  :hook (python-mode . lsp)
  :config (require 'dap-python)
  :custom (python-shell-interpreter "python3") ;; Required if "python" is not python 3.
          (dap-python-executable "python3")    ;; Same as above.
          (dap-python-debugger 'debugpy))

Writing

https://github.com/org-roam/org-roam

• Rudimentary roam replica with org-mode

(use-package org-roam
  :hook (after-init . org-roam-mode)
  :custom (org-roam-directory dotfiles/brain))

https://github.com/org-roam/org-roam

• Visualizes the org-roam database

• Available on http://localhost:8080

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

Configure keybindings behind SPC r.

• Find with f

• Buffer with b

• Capture with c

• Dailies with d

(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")
  "rc" '(org-roam-capture :which-key "Capture")
  "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"))

Configure the default capture template for new topics.

(setq org-roam-capture-templates
      '(("d" "default" plain (function org-roam-capture--get-point)
         "%?"
         :file-name "${slug}"
         :head "#+TITLE: ${title}\n"
         :unnarrowed t)))

Configure the default capture template for daily entries.

(setq org-roam-dailies-capture-templates
      '(("d" "default" entry (function org-roam-capture--get-point)
         "* %?"
         :file-name "daily/%<%Y-%m-%d>"
         :head "#+TITLE: %<%Y-%m-%d>\n")))

Agenda

Configure agenda sources.

• Dailies ~/.local/source/brain/daily/

• Secrets ~/.local/source/secrets/

(setq org-agenda-files '("~/.local/source/secrets/"
                         "~/.local/source/brain/daily/"))

Open an agenda buffer with SPC a.

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

Blogging

https://github.com/kaushalmodi/ox-hugo

• Configure for one-post-per-file

(use-package ox-hugo
  :after ox)

Creaate a capture template for blog posts in the posts sub directory.

(add-to-list 'org-roam-capture-templates
             '("b" "blog" plain (function org-roam-capture--get-point)
               "%?"
               :file-name "posts/${slug}"
               :head "#+TITLE: ${title}\n#+HUGO_BASE_DIR: ../\n#+HUGO_SECTION: ./\n"))

Presentations

Produce high quality presentations that work anywhere with HTML/JS via the reveal.js package.

https://github.com/hexmode/ox-reveal

• Configure to use cdn

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

Create a capture template for presentations stored in the slides sub directory.

(add-to-list 'org-roam-capture-templates
             '("s" "slides" plain (function org-roam-capture--get-point)
               "%?"
               :file-name "slides/${slug}"
               :head "#+TITLE: ${title}\n"))