;; 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.
;; 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 =rasberry= namespace.
;; 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 [[https://chrishayward.xyz/posts/immutable-emacs/][Immutable Emacs]].
(setquser-emacs-directorydotfiles/cache)
(setquser-emacs-directorydotfiles/cache)
;; Because this project uses version-control, we can disable more unwanted features:
;; + Lock files
;; + Backup files
(setqcreate-lockfilesnil
(setqcreate-lockfilesnil
make-backup-filesnil)
make-backup-filesnil)
;; Packages
;; Download and install packages using [[https://github.com/raxod502/straight.el][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.
(setqstraight-repository-branch"develop"
(setqstraight-repository-branch"develop"
straight-use-package-by-defaultt)
straight-use-package-by-defaultt)
;; 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.
;; Complete the integration with ~use-package~ by installing it with =straight=.
(straight-use-package'use-package)
(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 [[https://github.com/emacscollective/no-littering][no-littering]] to reduce the files created by Emacs.
(use-packageno-littering)
(use-packageno-littering)
;; Emacs' default user interface is *horrendous*, let's do something about that.
(setqinhibit-startup-messaget
(setqinhibit-startup-messaget
initial-scratch-message"")
initial-scratch-message"")
@ -35,9 +77,24 @@
(when(fboundp'scroll-bar-mode)
(when(fboundp'scroll-bar-mode)
(scroll-bar-mode-1)))
(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*.
(setqgc-cons-tresholdmost-positive-fixnum
(setqgc-cons-tresholdmost-positive-fixnum
gnutls-min-prime-bits4096)
gnutls-min-prime-bits4096)
;; Babel
;; *Organize your plain life in plain text*
;; [[https://orgmode.org][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.
;; Place keybindings for executing shell commands behind =SPC x=.
;; + Run shell commands with =x=
;; + Run async shell commands with =z=
(dotfiles/leader
(dotfiles/leader
"x"'(:ignoret:which-key"Run")
"x"'(:ignoret:which-key"Run")
"xx"'(dotfiles/run:which-key"Run")
"xx"'(dotfiles/run:which-key"Run")
"xz"'(async-shell-command:which-key"Async"))
"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.
(defundotfiles/init-hook()
(defundotfiles/init-hook()
(exwm-workspace-switch-create1)
(exwm-workspace-switch-create1)
(setqdisplay-time-and-datet)
(setqdisplay-time-and-datet)
(display-battery-mode1)
(display-battery-mode1)
(display-time-mode1))
(display-time-mode1))
;; Using =autorandr= with pre configured profiles, switching screens (AKA hot plugging) is also handled through a hook.
(defundotfiles/update-display()
(defundotfiles/update-display()
"Update the displays by forcing a change through autorandr."
"Update the displays by forcing a change through autorandr."
;; Download [[https://github.com/justbur/emacs-which-key][which-key]], a package that displays the current incomplete keybinding input in a mini-buffer, showing available completion options.
(use-packagewhich-key
(use-packagewhich-key
:diminishwhich-key-mode
:diminishwhich-key-mode
:custom(which-key-idle-delaydotfiles/idle)
:custom(which-key-idle-delaydotfiles/idle)
:config(which-key-mode))
:config(which-key-mode))
;; Turn Emacs into Vim with [[https://evil.readthedocs.io/en/latest/index.html][evil-mode]], the extensible VI layer for Emacs.
(use-packageevil
(use-packageevil
:custom(evil-want-integrationt);; Required for `evil-collection'.
:custom(evil-want-integrationt);; Required for `evil-collection'.
(evil-want-keybindingnil);; Same as above
(evil-want-keybindingnil);; Same as above
:config(evil-mode1))
:config(evil-mode1))
;; Unfortunately the default keybindings are *lacking*, but there is a community curated package [[https://github.com/emacs-evil/evil-collection][evil-collection]], which does a much better job implementing keybindings you would expect to find.
(use-packageevil-collection
(use-packageevil-collection
:afterevil
:afterevil
:config(evil-collection-init))
:config(evil-collection-init))
;; Surround text with functions, quotations, and any other symbols using the [[https://github.com/emacs-evil/evil-surround][evil-surround]] package.
(use-packageevil-surround
(use-packageevil-surround
:afterevil
:afterevil
:config(global-evil-surround-mode1))
:config(global-evil-surround-mode1))
;; Toggle block comments using [[https://github.com/redguardtoo/evil-nerd-commenter][evil-nerd-commentor]] and =M-;=.
(use-packageevil-nerd-commenter
(use-packageevil-nerd-commenter
:afterevil
:afterevil
:bind("M-;".evilnc-comment-or-uncomment-lines))
:bind("M-;".evilnc-comment-or-uncomment-lines))
;; Implement the *leader* key using [[https://github.com/noctuid/general.el][general.el]], letting us easily configure prefixed keybindings in a much cleaner manner than the default methods.
(use-packagegeneral
(use-packagegeneral
:afterevil
:afterevil
:config
:config
@ -31,48 +66,131 @@
:prefixdotfiles/leader-key
:prefixdotfiles/leader-key
:global-prefixdotfiles/leader-key-global))
:global-prefixdotfiles/leader-key-global))
;; Use [[https://github.com/abo-abo/hydra][hydra]] for transient keybindings sharing a common prefix.
(use-packagehydra
(use-packagehydra
:defert)
:defert)
;; 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
(dotfiles/leader
"h"'(:ignoret:which-key"Help")
"h"'(:ignoret:which-key"Help")
"hp"'(describe-package:which-key"Package")
"hp"'(describe-package:which-key"Package")
"hv"'(describe-variable:which-key"Variable")
"hv"'(describe-variable:which-key"Variable")
"hf"'(describe-function:which-key"Function"))
"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 [[https://github.com/domtronn/all-the-icons.el][all-the-icons]]. This makes navigation and visually parsing directories much faster, given that file types are quickly identified by their corresponding icons.
(use-packageall-the-icons)
(use-packageall-the-icons)
;; Integration with =dired= comes from the [[https://github.com/jtbm37/all-the-icons-dired][all-the-icons-dired]] package.
(use-packageall-the-icons-dired
(use-packageall-the-icons-dired
:hook(dired-mode.all-the-icons-dired-mode))
: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)
(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 [[https://github.com/crocket/dired-single][dired-single]], reusing the same dired buffer.
;; 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 [[https://github.com/zwild/eshell-prompt-extras][eshell-prompt-extras]] package.
(use-packageeshell-prompt-extras
(use-packageeshell-prompt-extras
:custom(eshell-highlight-promptnil)
:custom(eshell-highlight-promptnil)
(eshell-prompt-function'epe-theme-lambda))
(eshell-prompt-function'epe-theme-lambda))
;; Open an =eshell= buffer with =SPC e=.
(dotfiles/leader
(dotfiles/leader
"e"'(eshell:which-key"Shell"))
"e"'(eshell:which-key"Shell"))
;; Source
;; #+ATTR_ORG: :width 420px
;; #+ATTR_HTML: :width 420px
;; #+ATTR_LATEX: :width 420px
;; [[./docs/images/2021-02-13-example-magit.gif]]
;; Another hallmark feature is [[https://github.com/magit/magit][Magit]], a complete git porcelain within Emacs.
;; Define a transient keybinding for scaling the text.
(defhydrahydra-text-scale(:timeout4)
(defhydrahydra-text-scale(:timeout4)
"Scale"
"Scale"
("j"text-scale-increase"Increase")
("j"text-scale-increase"Increase")
("k"text-scale-decrease"Decrease")
("k"text-scale-decrease"Decrease")
("f"nil"Finished":exitt))
("f"nil"Finished":exitt))
;; Increase the font size in buffers with =SPC t f=.
;; + Increase =j=
;; + Decrease =k=
;; + Finish =f=
(dotfiles/leader
(dotfiles/leader
"tf"'(hydra-text-scale/body:which-key"Font"))
"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.
;; #+begin_example
;; 5:
;; 4:
;; 3:
;; 2:
;; 1:
;; 156: << CURRENT LINE >>
;; 1:
;; 2:
;; 3:
;; 4:
;; 5:
;; #+end_example
;; https://github.com/emacsmirror/linum-relative
;; + Integrate with ~display-line-numbers-mode~ for performance
;; Cherry pick a few modules from =doom-emacs=. High quality and modern colour themes are provided in the [[https://github.com/hlissner/emacs-doom-themes][doom-themes]] package.
(use-packagedoom-themes
(use-packagedoom-themes
:init(load-theme'doom-moonlightt))
:init(load-theme'doom-moonlightt))
;; [[https://github.com/seagle0128/doom-modeline][doom-modeline]] provides an elegant status bar / modeline.
(use-packagedoom-modeline
(use-packagedoom-modeline
:custom(doom-modeline-height16)
:custom(doom-modeline-height16)
:config(doom-modeline-mode1))
:config(doom-modeline-mode1))
;; Load a theme with =SPC t t=.
(dotfiles/leader
(dotfiles/leader
"tt"'(counsel-load-themett:which-key"Theme"))
"tt"'(counsel-load-themett:which-key"Theme"))
;; Pretty
;; Make programming buffers prettier with [[https://github.com/pretty-mode/pretty-mode][pretty-mode]], complimentary to the built in ~prettify-symbols-mode~.
(use-packagepretty-mode
(use-packagepretty-mode
:hook(python-mode.turn-on-pretty-mode))
:hook(python-mode.turn-on-pretty-mode))
;; Ligatures
;; Enable font ligatures via [[https://github.com/jming422/fira-code-mode][fira-code-mode]], perform this action *only* when ~Fira Code~ is the current font.
;; Add support for language servers with [[https://emacs-lsp.github.io/lsp-mode/][lsp-mode]].
(use-packagelsp-mode
(use-packagelsp-mode
:commands(lsplsp-deferred)
:commands(lsplsp-deferred)
:custom(lsp-idle-delay(*5dotfiles/idle)))
:custom(lsp-idle-delay(*5dotfiles/idle)))
;; [[https://emacs-lsp.github.io/lsp-ui/][lsp-ui]] provides UI improvements for =lsp-mode=.
(use-packagelsp-ui
(use-packagelsp-ui
:afterlsp
:afterlsp
:custom(lsp-ui-doc-position'at-point)
:custom(lsp-ui-doc-position'at-point)
(lsp-ui-doc-delay0.500))
(lsp-ui-doc-delay0.500))
;; [[https://emacs-lsp.github.io/dap-mode/][Dap-mode]] adds support for the debug adapter protocol to Emacs.
(use-packagedap-mode
(use-packagedap-mode
:commands(dap-debug))
: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-packagedocker
(use-packagedocker
:commands(docker))
:commands(docker))
;; Open the management screen with =SPC k=.
(dotfiles/leader
(dotfiles/leader
"k"'(docker:which-key"Docker"))
"k"'(docker:which-key"Docker"))
;; Management
;; Configure [[https://projectile.mx][projectile]], a project interaction library for Emacs. It provides a nice set of features for operating on a project level without introducing external dependencies.
;; Text completion framework via =company= aka *Complete Anything*.
;; http://company-mode.github.io/
;; + Integrate with =lsp-mode=
(use-packagecompany
(use-packagecompany
:afterlsp)
:afterlsp)
@ -27,37 +73,99 @@
:after(lspcompany)
:after(lspcompany)
:custom(company-backend'company-lsp))
: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.
;; I am using [[https://orgmode.org][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.
;; Visualize the org-roam database with the server, available when the editor is running at http://localhost:8080
(use-packageorg-roam-server
(use-packageorg-roam-server
:hook(org-roam-mode.org-roam-server-mode))
:hook(org-roam-mode.org-roam-server-mode))
;; Hugo
;; I use [[https://gohugo.io][Hugo]] for my personal [[https://chrishayward.xyz][website]], which I write in =org-mode= before compiling to =hugo-markdown=. [[https://github.com/kaushalmodi/ox-hugo][ox-hugo]], configured for =one-post-per-file= is my technique for managing my content.
(use-packageox-hugo
(use-packageox-hugo
:afterox)
:afterox)
;; Posts
;; Add a capture template for creating new blog posts.
;; Produce high quality presentations that work anywhere with =HTML/JS= and the [[https://revealjs.com][reveal.js]] package. [[https://github.com/hexmode/ox-reveal][ox-reveal]], configured to use a =cdn= allows us to produce ones that are not dependent on a local version of =reveal.js=.
;; I use [[https://github.com/bnbeckwith/writegood-mode][writegood-mode]] to find common writing problems such as cliches and poor wording. Grammarly for the peons!
(use-packagewritegood-mode
(use-packagewritegood-mode
:afterorg
:afterorg
:config(writegood-mode))
:config(writegood-mode))
;; Toggle ~writegood~ mode with =SPC t w=.
(dotfiles/leader
(dotfiles/leader
"tw"'(writegood-mode:which-key"Grammar"))
"tw"'(writegood-mode:which-key"Grammar"))
;; Spelling
;; Use the built in =ispell= package to add spell checking features to buffers.
