You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Christopher James Hayward
898fe1e646
|
4 years ago | |
|---|---|---|
| config | 4 years ago | |
| hosts | 4 years ago | |
| modules | 4 years ago | |
| README.org | 4 years ago | |
| init.el | 4 years ago | |
README.org
Dotfiles
^^ @@@@@@@@@
^^ ^^ @@@@@@@@@@@@@@@
@@@@@@@@@@@@@@@@@@ ^^
@@@@@@@@@@@@@@@@@@@@
~~~~ ~~ ~~~~~ ~~~~~~~~ ~~ &&&&&&&&&&&&&&&&&&&& ~~~~~~~ ~~~~~~~~~~~ ~~~
~ ~~ ~ ~ ~~~~~~~~~~~~~~~~~~~~ ~ ~~ ~~ ~
~ ~~ ~~ ~~ ~~ ~~~~~~~~~~~~~ ~~~~ ~ ~~~ ~ ~~~ ~ ~~
~ ~~ ~ ~ ~~~~~~ ~~ ~~~ ~~ ~ ~~ ~~ ~
~ ~ ~ ~ ~ ~~ ~~~~~~ ~ ~~ ~ ~~
~ ~ ~ ~ ~~ ~ ~ #+end_example
Immutable GNU Emacs dotfiles, inspired by Doom, built for Liberty.
+ 100% Literate
+ 100% Immutable
+ 100% Reproducible
* Init
:PROPERTIES:
:header-args: :tangle ~/.local/source/dotfiles/init.el
:END:
Although later versions of Emacs introduce =early-init.el=, it's not used in this configuration for two reasons:
+ It's not required due to the modularity
+ Maintaining support for older versions
Assuming you have completed all of the following tasks prior to proceeding further:
1. Imported the =secrets=
2. Initialized the =passwords=
3. Defined the =host= file
4. Created all required symbolic links
Load the host configuration.
#+begin_src emacs-lisp
(let ((host-file (concat "~/.local/source/dotfiles/hosts/" system-name ".el")))
(when (file-exists-p host-file)
(load-file host-file)))
#+end_src
Load the enabled modules.
#+begin_src emacs-lisp
(dolist (m dotfiles/modules)
(let ((mod-file (concat "~/.local/source/dotfiles/modules/" (symbol-name m) ".el")))
(when (file-exists-p mod-file)
(load-file mod-file))))
#+end_src
* Hosts
Each host system that runs Emacs has a file defined in the =hosts/= sub directory, following the pattern of ~$HOSTNAME.el~. All of the configurations are defined within this file, the values of which are read from by the other modules during startup and installation. This does *not* cover hosts that are controlled via =TRAMP=, as that will be covered in another section.
** Example (Ubuntu)
:PROPERTIES:
:header-args: :tangle ~/.local/source/dotfiles/hosts/ubuntu.el
:END:
The first configuration, which was built using the Ubuntu 20.04 LTS server edition. I decided to incorporate =flatpaks= into this build. Setting the ~$BROWSER~ variable is required in the desktop module. Set the browser to the flatpak borwser currently installed, this could change to chromium, firefox, or any other browser by changing this environment variable.
#+begin_src emacs-lisp
(setenv "BROWSER" "flatpak run org.mozilla.firefox")
#+end_src
Add the modules you want to initialize to the ~dotfiles/modules~ variable.
#+begin_src emacs-lisp
(defvar dotfiles/modules '(core
desktop
writing
projects
interface))
#+end_src
Specify the cache directory.
#+begin_src emacs-lisp
(defvar dotfiles/cache "~/.cache/emacs")
#+end_src
Functionality like =completion= and =hints= can be delayed to avoid popups for common manuevers. Adjust this value to your personal taste.
#+begin_src emacs-lisp
(defvar dotfiles/idle 0.0)
#+end_src
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.
#+begin_src emacs-lisp
(defvar dotfiles/leader-key "SPC")
(defvar dotfiles/leader-key-global "C-SPC")
#+end_src
Define where the source repositories are stored, with most projects being relative from that directory.
#+begin_src emacs-lisp
(defvar dotfiles/src "~/.local/source/")
#+end_src
The brain project provides the basis for my agenda, notes, blog, and presentations.
#+begin_src emacs-lisp
(defvar dotfiles/brain (concat dotfiles/src "brain/"))
(defvar dotfiles/notes (concat dotfiles/brain "notes/"))
(defvar dotfiles/bib (concat dotfiles/brain "resources.bib"))
#+end_src
Secret keys and passwords are stored in a seperate repository.
#+begin_src emacs-lisp
(defvar dotfiles/secrets (concat dotfiles/src "secrets/"))
(defvar dotfiles/passwords (concat dotfiles/src "passwords/"))
#+end_src
* Modules
Breaking down the project into logical units or chapters to keep the code more maintainable and organized. This is also a fundemental requirement to achieve the goal of modularity. Incorporating just the =core= module on a build server to build literate programming projects is just one example of what can be achieved.
** Core
:PROPERTIES:
:header-args: :tangle ~/.local/source/dotfiles/modules/core.el :results silent
:END:
Minimal configuration to make Emacs usable for my own personal workflow. This does very little in the ways of improving the visuals, only removing what is included by default and not required.
*** Cleanup
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 are loaded, we change the value to ~dotfiles/cache~. I elaborate more on the technique in my post [[https://chrishayward.xyz/posts/immutable_emacs/][Immutable Emacs]].
#+begin_src emacs-lisp
(setq user-emacs-directory dotfiles/cache)
#+end_src
Because this project uses version-control, we can disable more unwanted features:
+ Lock files
+ Backup files
#+begin_src emacs-lisp
(setq create-lockfiles nil
make-backup-files nil)
#+end_src
*** Package management
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 where packages are sourced from.
+ 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.
#+begin_src emacs-lisp
(setq straight-repository-branch "develop"
straight-use-package-by-default t)
#+end_src
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.
#+begin_src emacs-lisp
(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))
#+end_src
Complete the integration with ~use-package~ by installing it with =straight=.
#+begin_src emacs-lisp
(straight-use-package 'use-package)
#+end_src
*** Hermetic evaluation
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.
#+begin_src emacs-lisp
(use-package no-littering)
#+end_src
Emacs' default user interface is horrendous, but with less than 10 lines of code we can change that.
#+begin_src emacs-lisp
(setq inhibit-startup-message t)
(global-prettify-symbols-mode)
(scroll-bar-mode -1)
(menu-bar-mode -1)
(tool-bar-mode -1)
(tooltip-mode -1)
#+end_src
*** Literate programming
*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.
+ [[https://orgmode.org/worg/org-contrib/babel/languages/index.html][Babel languages]]
+ [[https://orgmode.org/manual/Structure-Templates.html][Structure templates]]
#+begin_src emacs-lisp
(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")))
#+end_src
#+begin_src emacs-lisp
(defun dotfiles/tangle (dir)
"Recursively tangle the Org files within a directory."
(interactive)
(let ((org-files (directory-files-recursively dir "org")))
(dolist (f org-files)
(org-babel-tangle-file f))))
#+end_src
*** Custom keybindings
Make the =ESC= key quit (most) prompts, instead of the default =C-g=.
#+begin_src emacs-lisp
(global-set-key (kbd "<escape>") 'keyboard-escape-quit)
#+end_src
**** Hints
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.
#+begin_src emacs-lisp
(use-package which-key
:diminish which-key-mode
:init (which-key-mode)
:config (setq which-key-idle-delay dotfiles/idle))
#+end_src
**** Leader
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.
#+begin_src emacs-lisp
(use-package general
:config
(general-create-definer dotfiles/leader
:states '(normal motion)
:keymaps 'override
:prefix dotfiles/leader-key
:global-prefix dotfiles/leader-key-global))
#+end_src
Use [[https://github.com/abo-abo/hydra][hydra]] for transient keybindings sharing a common prefix.
#+begin_src emacs-lisp
(use-package hydra)
#+end_src
**** Evil mode
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][evil-mode]] is the extensible VI layer for Emacs.
#+begin_src emacs-lisp
(use-package evil
:init (setq evil-want-integration t
evil-want-keybinding nil)
:config (evil-mode 1))
#+end_src
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.
#+begin_src emacs-lisp
(use-package evil-collection
:after evil
:config (evil-collection-init))
#+end_src
Surround text with functions, quotations, and any other symbols using the [[https://github.com/emacs-evil/evil-surround][evil-surround]] package.
#+begin_src emacs-lisp
(use-package evil-surround
:config (global-evil-surround-mode 1))
#+end_src
https://github.com/redguardtoo/evil-nerd-commenter
+ Toggle comments with =M-;=
#+begin_src emacs-lisp
(use-package evil-nerd-commenter
:bind ("M-;" . evilnc-comment-or-uncomment-lines))
#+end_src
**** Shortcuts
Again cherry picked from =Doom=, I want to continue utilizing the muscle memory I have developed from a year of mainlining the framework.
+ Close buffers with =SPC c=
+ Find files with =SPC . (period)=
+ Switch buffers with =SPC , (comma)=
#+begin_src emacs-lisp
(dotfiles/leader
"." '(find-file :which-key "Files")
"," '(switch-to-buffer :which-key "Buffers")
"c" '(kill-buffer-and-window :which-key "Close"))
#+end_src
Run helper functions with =SPC h=.
+ Packages =p=
+ Variables =v=
+ Functions =f=
#+begin_src emacs-lisp
(dotfiles/leader
"h" '(:ignore t :which-key "Help")
"hp" '(describe-package :which-key "Package")
"hv" '(describe-variable :which-key "Variable")
"hf" '(describe-function :which-key "Function"))
#+end_src
Quit emacs with =SPC q=.
+ Saving =q=
+ Without =w=
+ Frame (daemon) =f=
#+begin_src emacs-lisp
(dotfiles/leader
"q" '(:ignore t :which-key "Quit")
"qq" '(save-buffers-kill-emacs :which-key "Save")
"qw" '(kill-emacs :which-key "Now")
"qf" '(delete-frame :which-key "Frame"))
#+end_src
Window management with =SPC w=.
+ Swap with =w=
+ Close with =c=
+ Motions with =h,j,k,l=
+ Split with =s + <MOTION>=
#+begin_src emacs-lisp
(dotfiles/leader
"w" '(:ignore t :which-key "Window")
"ww" '(window-swap-states :which-key "Swap")
"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"))
#+end_src
Place runtime tweaks behind =SPC t=.
#+begin_src emacs-lisp
(dotfiles/leader
"t" '(:ignore t :which-key "Tweaks"))
#+end_src
*** Version control
Another hallmark feature is [[https://github.com/magit/magit][Magit]], a complete git porcelain within Emacs.
#+begin_src emacs-lisp
(use-package magit
:custom (magit-display-buffer-function
#'magit-display-buffer-same-window-except-diff-v1))
#+end_src
Work directly with github issues / pull requests using [[https://github.com/magit/forge][Forge]].
+ Requires a valid ~$GITHUB_TOKEN~
#+begin_src emacs-lisp
(use-package forge)
#+end_src
Open the *status* page for the current repository with =SPC g=.
#+begin_src emacs-lisp
(dotfiles/leader
"g" '(magit-status :which-key "Magit"))
#+end_src
*** Terminal emulation
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
#+begin_src emacs-lisp
(use-package eshell-prompt-extras
:config (setq eshell-highlight-prompt nil
eshell-prompt-function 'epe-theme-lambda))
#+end_src
Open an =eshell= buffer with =SPC e=.
#+begin_src emacs-lisp
(dotfiles/leader
"e" '(eshell :which-key "Shell"))
#+end_src
*** File management
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
#+begin_src emacs-lisp
(use-package all-the-icons)
#+end_src
https://github.com/jtbm37/all-the-icons-dired
+ Integration with dired
#+begin_src emacs-lisp
(use-package all-the-icons-dired
:hook (dired-mode . all-the-icons-dired-mode))
#+end_src
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=.
#+begin_src emacs-lisp
(require 'dired-x)
#+end_src
By default =dired= will create a new buffer everytime you press =RET= over a directory. In my workflow this leads to many unwanted =dired= buffers that have to be cleaned up manually. [[https://github.com/crocket/dired-single][Dired-single]] lets us reuse the same dired buffer.
+ Move up a directory with =h=
+ Open a single buffer with =l=
#+begin_src emacs-lisp
(use-package dired-single
:config
(evil-collection-define-key 'normal 'dired-mode-map
"h" 'dired-single-up-directory
"l" 'dired-single-buffer))
#+end_src
Open a dired buffer with =SPC d=.
#+begin_src emacs-lisp
(dotfiles/leader
"d" '(dired-jump :which-key "Dired"))
#+end_src
** Desktop
:PROPERTIES:
:header-args: :tangle ~/.local/source/dotfiles/modules/desktop.el :results silent
:END:
I use Emacs as a Desktop Environment with the [[https://github.com/ch11ng/exwm][exwm]] package. It allows Emacs to function as a complete tiling window manager for =X11=. My workflow includes launching the window manager with =xinitrc=, without the use of a display manager, controlling *everything* within Emacs.
#+begin_src conf :tangle ~/.local/source/dotfiles/config/xinitrc
exec dbus-launch --exit-with-session emacs -mm --debug-init
#+end_src
When launching into a session, if the display server is not running then =startx= should be invoked, to run the window manager. Anything that needs to be included in the ~$PATH~ should occur before the end of this file.
#+begin_src sh :tangle ~/.local/source/dotfiles/config/profile
GOPATH="$HOME/.go/"
export GOPATH
if [ -d "$GOPATH/bin" ]; then
PATH="$GOPATH/bin:$PATH"
fi
if [ -z "${DISPLAY}" ] && [ "${XDG_VTNR}" -eq 1 ]; then
exec startx
fi
#+end_src
Define a method to run an external process, allowing us to launch any application on a new process without interferring with Emacs.
#+begin_src emacs-lisp
(defun dotfiles/run (command)
"Run an external process."
(interactive (list (read-shell-command "λ ")))
(start-process-shell-command command nil command))
#+end_src
Some methods must be called and applied to the current call process in order to function correctly with Emacs hooks.
#+begin_src emacs-lisp
(defun dotfiles/run-in-background (command)
(let ((command-parts (split-string command "[ ]+")))
(apply #'call-process `(,(car command-parts) nil 0 nil ,@(cdr command-parts)))))
#+end_src
Place keybindings for executing shell commands behind =SPC x=.
+ Run with =x=
+ Run in backround with =g=
+ Run asynchronously with =z=
#+begin_src emacs-lisp
(dotfiles/leader
"x" '(:ignore t :which-key "Execute")
"xx" '(dotfiles/run :which-key "Run")
"xb" '(dotfiles/run-in-background :which-key "Run (background)")
"xz" '(async-shell-command :which-key "Async"))
#+end_src
When the window manager first launches the ~init-hook~ will be called, this allows us to define some custom logic when it's initialized.
+ 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.
#+begin_src emacs-lisp
(defun dotfiles/init-hook ()
(exwm-workspace-switch-create 1)
(setq display-time-and-date t)
(display-battery-mode 1)
(display-time-mode 1))
#+end_src
Using =autorandr= with pre configured profiles, switching screens (AKA hot plugging) is also handled through a hook.
#+begin_src emacs-lisp
(defun dotfiles/update-display ()
(dotfiles/run-in-background "autorandr --change --force"))
#+end_src
Finally we configure the window manager.
+ Enable =randr= support
Connect our custom hooks and configure the input keys, a custom layer for defining which keys are captured by Emacs, and which are passed through to =X= applications.
+ Pass through to Emacs
+ =M-x= to Emacs
+ =C-g= to Emacs
+ =C-SPC= to Emacs
+ Bindings with =S= (Super / Win)
+ Reset =S-r=
+ Launch =S-&=
+ Workspace =S-[1..9]=
#+begin_src emacs-lisp
(use-package exwm
:config
(require 'exwm-randr)
(exwm-randr-enable)
(add-hook 'exwm-init-hook #'dotfiles/init-hook)
(add-hook 'exwm-randr-screen-change-hook #'dotfiles/update-display)
(dotfiles/update-display)
(setq exwm-input-prefix-keys
'(?\M-x
?\C-g
?\C-\ )
exwm-input-global-keys
`(([?\s-r] . exwm-reset)
([?\s-&] . dotfiles/run)
,@(mapcar (lambda (i)
`(,(kbd (format "s-%d" i)) .
(lambda ()
(interactive)
(exwm-workspace-switch-create ,i))))
(number-sequence 1 9))))
(exwm-enable))
#+end_src
** Writing
:PROPERTIES:
:header-args: :tangle ~/.local/source/dotfiles/modules/writing.el :results silent
:END:
I am using [[https://orgmode.org][Org-mode]] extensively for writing projects for different purposes. Improvements beyond what are required for my Literate Programming platform include:
[[https://github.com/integral-dw/org-superstar-mode][Org-superstar-mode]] for making headline stars more *super*.
#+begin_src emacs-lisp
(use-package org-superstar
:hook (org-mode . org-superstar-mode))
#+end_src
*** Mail
Plain text email delivered via mu, mu4e and mbsync. I run my own email server, so your configuration may differ from mine. This is the ~mbsyncrc~ file I use to synchronize my local mail with my server. This is required for mu4e in Emacs.
#+begin_src conf :tangle ~/.local/source/dotfiles/config/mbsyncrc
IMAPStore xyz-remote
Host mail.chrishayward.xyz
User chris@chrishayward.xyz
PassCmd "pass chrishayward.xyz/chris"
SSLType IMAPS
MaildirStore xyz-local
Path ~/.cache/mail/
Inbox ~/.cache/mail/inbox
SubFolders Verbatim
Channel xyz
Master :xyz-remote:
Slave :xyz-local:
Patterns * !Archives
Create Both
Expunge Both
SyncState *
#+end_src
The system typically expects to find this file at ~$HOME/.mbsyncrc~, but you may also specify a custom path if launching the command using arguments. I chose to symlink the default location to my repository.
#+begin_src shell :tangle no
mbsync -a
mu index --maildir="~/.cache/mail"
#+end_src
Once the mail is being synchronized, and the mail has been indexed with =mu=, it's time to install the required packages for Emacs.
#+begin_src emacs-lisp
(use-package mu4e
:load-path "/usr/share/emacs/site-lisp/mu4e"
:config
(setq mu4e-change-filenames-when-moving t
mu4e-update-interval (* 5 60) ;; Every 5 minutes.
mu4e-get-mail-command "mbsync -a"
mu4e-maildir "~/.cache/mail"
mu4e-compose-signature
(concat "Chris Hayward\n"
"https://chrishayward.xyz\n"))
;; Ensure plain text scales for all devices.
(setq mu4e-compose-format-flowed t)
;; GPG signing key for outbound mail.
(setq mml-secure-openpgp-signers '("37AB1CB72B741E478CA026D43025DCBD46F81C0F"))
(add-hook 'message-send-hook 'mml-secure-message-sign-pgpmime)
(setq message-send-mail-function 'smtpmail-send-it)
;; Configure mail account(s).
(setq mu4e-contexts
(list
;; Main
;; chris@chrishayward.xyz
(make-mu4e-context
:name "Main"
:match-func
(lambda (msg)
(when msg
(string-prefix-p "/Main" (mu4e-message-field msg :maildir))))
:vars
'((user-full-name . "Christopher James Hayward")
(user-mail-address . "chris@chrishayward.xyz")
(smtpmail-smtp-server . "mail.chrishayward.xyz")
(smtpmail-smtp-service . 587)
(smtpmail-stream-type . starttls))))))
#+end_src
Create a keybinding to open the mail dashboard with =SPC m=.
#+begin_src emacs-lisp
(dotfiles/leader
"m" '(mu4e :which-key "Mail"))
#+end_src
*** Brain
[[https://github.com/org-roam/org-roam][Org-roam]] is a rudimentary roam replica built on =Org mode=.
#+begin_src emacs-lisp
(use-package org-roam
:hook (after-init . org-roam-mode)
:custom (org-roam-directory dotfiles/brain))
#+end_src
[[https://github.com/org-roam/org-roam-server][Org-roam-server]] is a web application that visualizes the =Org roam= database, available when Emacs' running at [[http://localhost:8080][localhost:8080]].
#+begin_src emacs-lisp
(use-package org-roam-server
:hook (org-roam-mode . org-roam-server-mode))
#+end_src
Configure keybindings behind =SPC r=.
+ Find with =f=
+ Buffer with =b=
+ Capture with =c=
+ Dailies with =d=
#+begin_src emacs-lisp
(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"))
#+end_src
Configure the default capture template for new topics.
#+begin_src emacs-lisp
(setq org-roam-capture-templates
'(("d" "Default" plain (function org-roam-capture--get-point)
"%?"
:file-name "${slug}"
:head "#+TITLE: ${title}\n"
:unnarrowed t)))
#+end_src
Configure the default capture template for daily entries.
#+begin_src emacs-lisp
(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")))
#+end_src
*** Notes
#+begin_src emacs-lisp
(use-package org-noter
:after org
:config
(setq org-noter-always-create-frame nil
org-noter-notes-search-path dotfiles/notes))
#+end_src
#+begin_src emacs-lisp
(use-package org-pdftools
:hook (org-mode . org-pdftools-setup-link))
#+end_src
#+begin_src emacs-lisp
(use-package org-noter-pdftools
:after org-noter
:config
(with-eval-after-load 'pdf-annot
(add-hook 'pdf-annot-active-handler-functions #'org-noter-pdftools-jump-to-note)))
#+end_src
#+begin_src emacs-lisp
(setq bibtex-completion-notes-path dotfiles/notes
bibtex-completion-bibliography dotfiles/bib
bibtex-completion-pdf-field "file"
bibtex-completion-notes-template-multiple-files
(concat
"#+TITLE: ${title}\n"
"#+ROAM_KEY: cite:${=key=}\n"
"#* TODO Notes\n"
":PROPERTIES:\n"
":CUSTOM_ID: ${=key}\n"
":NOTER_DOCUMENT: %(orb-process-file-field \"${=key=}\")\n"
":AUTHOR: ${author-abbrev}\n"
":JOURNAL: ${journaltitle}\n"
":DATE: ${date}\n"
":YEAR: ${year}\n"
":DOI: ${doi}\n"
":URL: ${url}\n"
":END:\n\n"))
#+end_src
#+begin_src emacs-lisp
(use-package org-ref
:config
(setq org-ref-completion-library 'org-ref-helm-cite
org-ref-get-pdf-filename-function 'org-ref-get-pdf-filename-helm-bibtex
org-ref-default-bibliography dotfiles/bib
org-ref-bibliography-notes dotfiles/notes
org-ref-notes-directory dotfiles/notes
org-ref-notes-function 'orb-edit-notes
org-ref-note-title-format "* TODO %y - %t\n
:PROPERTIES:\n
:CUSTOM_ID: %k\n
:NOTER_DOCUMENT: %F\n
:ROAM_KEY: cite:%k\n
:AUTHOR: %9a\n
:JOURNAL: %j\n
:YEAR: %y\n
:VOLUME: %v\n
:PAGES: %p\n
:DOI: %D\n
:URL: %U\n
:END:\n\n"))
#+end_src
#+begin_src emacs-lisp
(use-package org-roam-bibtex
:after (org-roam)
:hook (org-roam-mode . org-roam-bibtex-mode)
:config
(setq orb-preformat-keywords
'("=key=" "title" "url" "file" "author-or-editor" "keywords")))
#+end_src
#+begin_src emacs-lisp
(add-to-list 'org-roam-capture-templates
'("n" "Notes" plain (function org-roam-capture--get-point)
""
:file-name "notes/${slug}"
:head "#+TITLE: ${=key=}: ${title}\n\n
#+ROAM_KEY:${ref}\n\n* ${title}\n
:PROPERTIES:\n
:CUSTOM_ID: ${=key=}\n
:URL: ${url}\n
:AUTHOR: ${author-or-editor}\n
:NOTER_DOCUMENT:%(orb-process-file-field \"${=key=}\")\n
:NOTER_PAGE:\n
:END:\n\n"))
#+end_src
*** Agenda
Configure agenda sources.
+ Dailies ~~/.local/source/brain/daily/~
+ Secrets ~~/.local/source/secrets/org/~
#+begin_src emacs-lisp
(setq org-agenda-files '("~/.local/source/brain/daily/"
"~/.local/source/secrets/org/"))
#+end_src
Open an agenda buffer with =SPC a=.
#+begin_src emacs-lisp
(dotfiles/leader
"a" '(org-agenda :which-key "Agenda"))
#+end_src
*** Blogging
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 blog.
#+begin_src emacs-lisp
(use-package ox-hugo
:after ox)
#+end_src
Creaate a capture template for blog posts in the =posts= sub directory.
#+begin_src emacs-lisp
(add-to-list 'org-roam-capture-templates
'("b" "Blogging" plain (function org-roam-capture--get-point)
"%?"
:file-name "posts/${slug}"
:head "#+TITLE: ${title}\n
#+HUGO_BASE_DIR: ~/.local/source/website\n
#+HUGO_SECTION: posts\n"))
#+end_src
*** Screencasts
Create screencasts with =one-frame-per-action= GIF recording via [[https://github.com/takaxp/emacs-gif-screencast][emacs-gif-screencast]].
+ Can be paused / resumed
+ High quality images
+ Optimized size
It requires the installation of ~scrot~ and ~convert~ from the =ImageMagick= library.
#+begin_src emacs-lisp
(use-package gif-screencast
:custom
(gif-screencast-output-directory (concat dotfiles/brain "screens/")))
#+end_src
Screencast controls behind =SPC s=.
+ Start / stop with =s=
+ Pause with =t=
#+begin_src emacs-lisp
(dotfiles/leader
"s" '(:ignore t :which-key "Screencast")
"ss" '(gif-screencast-start-or-stop :which-key "Start / Stop")
"sp" '(gif-screencast-toggle-pause :which-key "Pause"))
#+end_src
*** Presentations
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=.
#+begin_src emacs-lisp
(use-package ox-reveal
:after ox
:custom (org-reveal-root "https://cdn.jsdelivr.net/reveal.js/3.9.2/"))
#+end_src
Create a capture template for presentations stored in the =slides= sub directory.
#+begin_src emacs-lisp
(add-to-list 'org-roam-capture-templates
'("p" "Presentation" plain (function org-roam-capture--get-point)
"%?"
:file-name "slides/${slug}"
:head "#+TITLE: ${title}\n"))
#+end_src
** Projects
:PROPERTIES:
:header-args: :tangle ~/.local/source/dotfiles/modules/projects.el :results silent
:END:
An IDE like experience (or better) can be achieved in Emacs using two *Microsoft* open source initiatives.
Turn Emacs into an *IDE* (or better) with the [[https://microsoft.github.io/language-server-protocol/][Language Server Protocol]], an open source initiative from *Microsoft* for the *VSCode* editor.
[[https://emacs-lsp.github.io/lsp-mode/][Lsp-mode]] brings support for language servers into Emacs.
#+begin_src emacs-lisp
(use-package lsp-mode
:custom (gc-cons-threshold 1000000000)
(lsp-idle-delay 0.500))
#+end_src
https://emacs-lsp.github.io/lsp-ui/
+ UI improvements for =lsp-mode=
#+begin_src emacs-lisp
(use-package lsp-ui
:custom (lsp-ui-doc-position 'at-point)
(lsp-ui-doc-delay 0.500))
#+end_src
*** 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.
#+begin_src emacs-lisp
(use-package projectile
:config
(setq projectile-project-search-path '("~/.local/source"))
(projectile-mode))
#+end_src
*** 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.
#+begin_src emacs-lisp
(use-package password-store
:custom (password-store-dir dotfiles/passwords))
#+end_src
Configure keybindings behind =SPC p=.
+ Copy with =p=
+ Rename with =r=
+ Generate with =g=
#+begin_src emacs-lisp
(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"))
#+end_src
*** Debugging
Handled through the [[https://microsoft.github.io/debug-adapter-protocol/][Debug Adapter Protocol]], an open source initiative from *Microsoft* for the *VSCode* editor.
[[https://emacs-lsp.github.io/dap-mode/][Dap-mode]] adds support for the protocol to Emacs.
#+begin_src emacs-lisp
(use-package dap-mode)
#+end_src
*** Completion
Text completion framework via =company= aka *Complete Anything*.
http://company-mode.github.io/
+ Integrate with =lsp-mode=
#+begin_src emacs-lisp
(use-package company)
(use-package company-lsp)
#+end_src
*** Languages
Support for individual languages are implemented here.
**** C/C++
Full *IDE* experience for Python within Emacs.
+ Completion, jumps via =lsp-mode=
+ Debugging via =dap-mode=
Install the =ccls= language server.
+ https://github.com/MaskRay/ccls
#+begin_src emacs-lisp
(use-package ccls
:hook ((c-mode c++-mode objc-mode cuda-mode) .
(lambda () (require 'ccls) (lsp))))
#+end_src
**** Python
Full *IDE* experience for Python within Emacs.
+ Completion, jumps via =lsp-mode=
+ Debugging via =dap-mode=
Install the =pyls= language server.
#+begin_src shell :tangle no
pip install --user "python-language-server[all]"
#+end_src
https://www.emacswiki.org/emacs/PythonProgrammingInEmacs
+ Built in mode
#+begin_src emacs-lisp
(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))
#+end_src
**** Go
Full *IDE* experience for Rust within Emacs.
+ Completion via =lsp-mode=
+ Debugging via =dap-mode=
Install the =gopls= language server.
#+begin_src sh :tangle no
GO111MODULE=on go get golang.org/x/tools/gopls@latest
#+end_src
Set the ~GOPATH~ environment variable prior to loading, this allows us to change the default value of ~$HOME/go~ to ~$HOME/.go~.
#+begin_src emacs-lisp
(setenv "GOPATH" (concat (getenv "HOME") "/.go/"))
#+end_src
Additionally, include the =bin= subdirectory of the ~$GOPATH~ in the ~$PATH~ variable, adding compiled golang programs.
#+begin_src emacs-lisp
(use-package go-mode
:hook (go-mode . lsp))
#+end_src
Apply some custom behaviour before saving:
+ Format buffer
+ Organize imports
#+begin_src emacs-lisp
(defun dotfiles/go-hook ()
(add-hook 'before-save-hook #'lsp-format-buffer t t)
(add-hook 'before-save-hook #'lsp-organize-imports t t))
#+end_src
#+begin_src emacs-lisp
(add-hook 'go-mode-hook #'dotfiles/go-hook)
#+end_src
** Interface
:PROPERTIES:
:header-args: :tangle ~/.local/source/dotfiles/modules/interface.el :results silent
:END:
*Bring Emacs out of the eighties*
*** Fonts
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.
#+begin_src emacs-lisp
(defvar dotfiles/font "Fira Code")
(defvar dotfiles/font-size 96)
#+end_src
Write out to all *3* of Emacs' default font faces.
#+begin_src emacs-lisp
(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)
#+end_src
Define a transient keybinding for scaling the text.
#+begin_src emacs-lisp
(defhydra hydra-text-scale (:timeout 4)
"Scale"
("j" text-scale-increase "Increase")
("k" text-scale-decrease "Decrease")
("f" nil "Finished" :exit t))
#+end_src
Increase the font size in buffers with =SPC t f=.
+ Increase =j=
+ Decrease =k=
+ Finish =f=
#+begin_src emacs-lisp
(dotfiles/leader
"tf" '(hydra-text-scale/body :which-key "Font"))
#+end_src
*** 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:
https://github.com/emacsmirror/linum-relative
-
Integrate with
display-line-numbers-modefor performance
(use-package linum-relative
:init (setq linum-relative-backend
'display-line-numbers-mode)
:config (linum-relative-global-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 :init (doom-modeline-mode 1) :custom ((doom-modeline-height 16)))
Load a theme with SPC t t.
(dotfiles/leader "tt" '(load-theme t t :which-key "Theme"))
Ligatures
Enable font ligatures via fira-code-mode, perform this action only when Fira Code is set as the current font.
;; (use-package fira-code-mode ;; :config ;; (global-fira-code-mode))
;; (use-package fira-code-mode ;; :hook prog-mode)
Dashboard
Present a dashboard when first launching Emacs.
(use-package dashboard
:config
(setq dashboard-center-content t
dashboard-set-init-info t
dashboard-set-file-icons t
dashboard-set-heading-icons t
dashboard-startup-banner 'logo
dashboard-projects-backend 'projectile
dashboard-items '((projects . 5)
(recents . 5)
(agenda . 5 )))
(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*")))