dotfiles/emacs/config.org

Doom Emacs Configuration

• Document Structure
  • Doom Emacs
  • Tangle
    • Noweb Reference
  • Files tree
    • Emacs Configuration Files
    • Other files
  • Emacs file prefixing
    • Lexical Bindings
    • Warn user not to modify *.el files directly.
    • Applying to all files
• Doom Modules
  • Completion
  • UI
    • Fancy Welcome Image
  • Editor
    • Custom Formatter
  • Emacs
  • Term
  • Checker
    • Custom Dictionary
  • Tools
    • Magit Forge Support
  • Language
  • Emails
  • App
  • Config
• General UI Tweaks
  • Window Titlebar
  • Fonts
• Keys
  • Local Leader
  • Speedup whichkey response
• Auto-Mode Alist
  • Tridactyl
• Orgmode
  • Directories
    • .archive
    • .attach
    • Projects
    • roam
    • todo
    • Journals
    • Work
  • Syncing
  • A Prettier Orgmode
    • Use a serif variable font
    • Pretty mode
    • Agenda faces
    • Prettify Symbols
    • Fancy Source Blocks
  • Drawers
    • State Change Log
    • Clock drawers
  • Roam
    • Dailies Templates
    • Keybinds
  • Mermaid
  • Babel stuff
    • Src blocks
    • Diff
  • Export to Tufte
  • Capture
• GPT
  • ChatGPT
  • TRAIL_RUN CoPilot
  • Keybinds
• Snippets
  • Orgmode
• Content Stolen From
• Footnotes

I'll fill out the how and why of this all as I figure out what the hell I'm doing. My current Emacs Configuration is a mess of copy and pasted snippet loosely grouped together. There's a fair number of work around, to transient configuration issues that now no longer exist, and more of stuff cribbed off StackOverflow & held together with string & bubble gum. While not yet calling Configuration Bankrupt's, I am going to try to see if I can restructure this technical debt.

This Emacs configuration is written using the Literate Programming (sort of) paradigm (well sort of) proposed by Donald Knuth in 1984, and uses Hlissner's awesome Doom Emacs configuration framework. While I like Literate Programming, literate configuration can be a mixed bag. Literate Programming produces more prose then code. Discoverability & readability can be drowned out under the prose about the current thoughts, pros & cons, backstory, deciding thoughts, & moral pondering. While this verbosity¹ aids documentation and understanding, its often at the cost of readability. As a compromise I'm going to version both to the verbose config.org file and all of the produced configuration files; this will allow us to git blame both the this file and the generated files.

Document Structure

Doom Emacs

I'm utilizing Hlissner's Doom Emacs frameworks. Doom Emac's configuration is divided into 150 modules, & fair number of convenience functions. Rather than detailing stuff about I'll say to go read FAQs & Index.

Configuration is located in the $DOOMDIR directory; this can be located either² at ~/.doom.d or $XDG_CONFIG_HOME/doom.

Tangle

This org-mode document works by using tangles. By default Doom's literate config mode adds any #+begin_src blocks into the config.el file³. If you want to tangle to a specific file you pass in a file name.

#+begin_src emacs-lisp :tangle "example.el"

or to disable it tangling for a codeblock set the :tangle property in code block header to no.

#+begin_src orgmode :tangle no

Noweb Reference

This document uses noweb reference syntax. This allows us to extract bits of configuration into named codeblocks, which can be interpolated into another code block's variable. For example:

#+NAME: initialization
#+BEGIN_SRC emacs-lisp
  (setq sentence "Never a foot too far, even.")
#+END_SRC

#+BEGIN_SRC emacs-lisp :noweb yes
  <<initialization>>
  (reverse sentence)
#+END_SRC

will produce

#+BEGIN_SRC emacs-lisp :noweb yes
  (setq sentence "Never a foot too far, even.")
  (reverse sentence)
#+END_SRC

NOTE: unless you explicitly turn off the named code block will be tangled into config.el. Use the no tangle option if you want to disable this.

Files tree

There's a fair number of files located in $DOOMDIR. Some are configuration, some are additional tooling not use directly by emacs.

tree $DOOMDIR -L 2

.
├── +keybinds.el
├── +orgmode.el
├── config.el
├── config.html
├── config.org
├── dist
│   ├── bundle.js
│   ├── code.css
│   ├── custom.css
│   ├── setup.org
│   └── tufte.css
├── init.el
├── makefile
├── packages.el
└── snippets
    └── org-mode

4 directories, 13 files

Emacs Configuration Files

Doom will automatically load the following files.

init.el

Enabled Doom Modules

package.el

Packages to fetch from MELPA, Github, etc.

config.el

General Emacs configuration

Any additional files should follow the pattern of +name.el and should be scoped to that individual purpose.

This should be loaded by the config.el file by using the load! macro⁴ e.g.

(load! "+name")

Currently this includes

+orgmode.el

Additional configuration for Orgmode. Considering this is one of the primary modes I use emacs in there's a fair bit of configuration there.

+keybinds.el

A relatively new and not fully utilized file. The plan is to use this as a centralized location for all custom keybinds.

Other files

There are several other files here not directly used by emacs but are related to it.

makefile

Install script using make⁵.

dist/*

These are files used by the output of ox-tufte.⁶

config.html

This org file exported from ox-tufte. This is not versioned.

snippets/[major mode]/*

These are YASnippets. These are manage by this document. See Snippets for more.

Everything else should be emacs configuration.

Emacs file prefixing

Lexical Bindings

There minor but non-zero start time benefits for using Lexical Bindings comments. All files created should start with

#+name:lexical-binding

;;; -*- lexical-binding: t; -*-

Warn user not to modify *.el files directly.

As mentioned above, we are versioning the generated emacs lisp configuration. We shouldn't modified these files as they'll be clobbed anytime the org-tangle is run. Lets include a warning to this effect.

#+name:modification-warning

;;; This file is generated via tangles from the config.org file. Do not modify this file.
;;; Any modifications here will be clobbered and versioned over. Seriously just don't.

Applying to all files

We need to apply this to all of the following files.

find ~/.doom.d/* -iname '*.el' | sed "s/.*\///"

+keybinds.el
+orgmode.el
config.el
init.el
packages.el

Since we've used a named these blocks we can use Noweb Reference for all of the files.

+keybinds.el

<<lexical-binding>>
<<modification-warning>>

+orgmode.el

<<lexical-binding>>
<<modification-warning>>

config.el

<<lexical-binding>>
<<modification-warning>>

init.el

<<lexical-binding>>
<<modification-warning>>

packages.el

<<lexical-binding>>
<<modification-warning>>

Doom Modules

The configuration is below is pulled from the template init.example.el provided by doom. This one is based off commit e966249.

;; This file controls what Doom modules are enabled and what order they load
;; in. Remember to run 'doom sync' after modifying it!

;; NOTE Press 'SPC h d h' (or 'C-h d h' for non-vim users) to access Doom's
;;      documentation. There you'll find a link to Doom's Module Index where all
;;      of our modules are listed, including what flags they support.

;; NOTE Move your cursor over a module's name (or its flags) and press 'K' (or
;;      'C-c c k' for non-vim users) to view its documentation. This works on
;;      flags as well (those symbols that start with a plus).
;;
;;      Alternatively, press 'gd' (or 'C-c c d') on a module to browse its
;;      directory (for easy access to its source code).

(doom! :completion
       <<doom-completion>>

       :ui
       <<doom-ui>>

       :editor
       <<doom-editor>>

       :emacs
       <<doom-emacs>>

       :term
       <<doom-term>>

       :checkers
       <<doom-checker>>

       :tools
       <<doom-tools>>

       :os
       (:if IS-MAC macos)  ; improve compatibility with macOS

       :lang
       <<doom-lang>>

       :email
       <<doom-email>>

       :app
       <<doom-app>>

       :config
       <<doom-config>>
       )

The code of these can be found in the modeules directory, the read me for each module will list any additional configuration options.

Completion

https://github.com/doomemacs/doomemacs/tree/master/modules/completion

#+name:doom-completion

;; (company           ; the ultimate code completion backend
;;  +childframe       ; not quite a window & not quite a frame
;; ; +tng              ; Use tab instead of ctrl+space
;;  )
(corfu
 +icons
 +orderless
 )
;;helm              ; the *other* search engine for love and lifes
;;ido               ; the other *other* search engine...
;;ivy               ; a search engine for love and life
(vertico           ; the search engine of the future
 +icons            ; make a little prettier
)

+childframe exists for both company & vertico, but looks a little weird with Vertico. We have for gone it for the time being.

UI

https://github.com/doomemacs/doomemacs/tree/master/modules/ui

#+name:doom-ui

;;deft              ; notational velocity for Emacs
doom              ; what makes DOOM look the way it does
doom-dashboard    ; a nifty splash screen for Emacs
doom-quit         ; DOOM quit-message prompts when you quit Emacs
(emoji +unicode)  ; 🙂
hl-todo           ; highlight TODO/FIXME/NOTE/DEPRECATED/HACK/REVIEW
;;hydra
;;indent-guides     ; highlighted indent columns
;;ligatures         ; ligatures and symbols to make your code pretty again
;;minimap           ; show a map of the code on the side
modeline          ; snazzy, Atom-inspired modeline, plus API
nav-flash         ; blink cursor line after big motions
neotree           ; a project drawer, like NERDTree for vim
ophints           ; highlight the region an operation acts on
(popup +defaults)   ; tame sudden yet inevitable temporary windows
;;tabs              ; a tab bar for Emacs
(treemacs          ; a project drawer, like neotree but cooler
 +lsp)
;;unicode           ; extended unicode support for various languages
(vc-gutter +pretty) ; vcs diff in the fringe
vi-tilde-fringe   ; fringe tildes to mark beyond EOB
(window-select    ; visually switch windows
 +numbers)        ; c-w N
workspaces        ; tab emulation, persistence & separate workspaces
zen               ; distraction-free coding or writing

Fancy Welcome Image

Rather than the boring ascii doom logo. Lets some the one off the box art. This is enabled by the doom-dashboard module.

#+CAPTION:Doom Welcome Icon

(setq fancy-splash-image (concat doom-user-dir "./.resources/doom.png"))

Editor

https://github.com/doomemacs/doomemacs/tree/master/modules/editor

#+name:doom-editor

(evil +everywhere); come to the dark side, we have cookies
file-templates    ; auto-snippets for empty files
fold              ; (nigh) universal code folding
(format +onsave)  ; automated prettiness
;;god               ; run Emacs commands without modifier keys
;;lispy             ; vim for lisp, for people who don't like vim
;;multiple-cursors  ; editing in many places at once
;;objed             ; text object editing for the innocent
;;parinfer          ; turn lisp into python, sort of
rotate-text       ; cycle region at point between text candidates
snippets          ; my elves. They type so I don't have to
;;word-wrap         ; soft wrapping with language-aware indent

Custom Formatter

Doom uses emacs-format-all-the-code for its formatting. It's a great package, but I use different formatters for a couple language. At this time I'm only going to update sql-mode to use pgformatter. It's supported, but instead used by default.

(setq-hook! 'sql-mode-hook +format-with 'pgformatter)

Emacs

https://github.com/doomemacs/doomemacs/tree/master/modules/emacs #+name:doom-emacs

dired             ; making dired pretty [functional]
electric          ; smarter, keyword-based electric-indent
(ibuffer +icons)  ; interactive buffer management
(undo +tree)             ; persistent, smarter undo for your inevitable mistakes
vc                ; version-control and Emacs, sitting in a tree

Term

https://github.com/doomemacs/doomemacs/tree/master/modules/term

#+name:doom-term

;;eshell            ; the elisp shell that works everywhere
;;shell             ; simple shell REPL for Emacs
;;term              ; basic terminal emulator for Emacs
vterm             ; the best terminal emulation in Emacs

Vterm is great. It does require some additional configuration to work properly. See relavant doc for more.

Checker

https://github.com/doomemacs/doomemacs/tree/master/modules/checker

#+name:doom-checker

(syntax +childframe)              ; tasing you for every semicolon you forget
(spell            ; tasing you for misspelling mispelling
 +aspell
 +everywhere)
grammar           ; tasing grammar mistake every you make

Custom Dictionary

(setq ispell-dictionary "en"
      ispell-personal-dictionary "~/org/.ispell.en.pws")

Tools

https://github.com/doomemacs/doomemacs/tree/master/modules/tools

#+name:doom-tools

;;ansible
;;biblio            ; Writes a PhD for you (citation needed)
;;collab            ; buffers with friends
(debugger +lsp)         ; FIXME stepping through code, to help you add bugs
;;direnv
;;docker
editorconfig      ; let someone else argue about tabs vs spaces
;;ein               ; tame Jupyter notebooks with emacs
(eval +overlay)     ; run code, run (also, repls)
;;gist              ; interacting with github gists
(lookup              ; navigate your code and its documentation
 +dictionary
 +docset
 +offline)
(lsp +peek)              ; M-x vscode
(magit +forge)      ; a git porcelain for Emacs
make              ; run make tasks from Emacs
;;pass              ; password manager for nerds
;;pdf               ; pdf enhancements
;;prodigy           ; FIXME managing external services & code builders
;;rgb               ; creating color strings
taskrunner        ; taskrunner for all your projects
(terraform         ; infrastructure as code
 +lsp)
;;tmux              ; an API for interacting with tmux
tree-sitter       ; syntax and parsing, sitting in a tree...
;;upload            ; map local to remote projects via ssh/ftp

NOTE: :leader r is currently being used by roam. See Roam Keybinds. This conflicts with the upload module. If you wish to use this module in the future you will need to updated one of the keybinds to not conflict.

Magit Forge Support

For use with Github this requires the creation of a Github Token (see here). This will need to be appended to your ~/.authinfo.gpg file using the format below⁷.

machine api.github.com login yourlogin^code-review password MYTOKENGOESHERE

For more on Forge see Magit's Forge documentation.

Language

https://github.com/doomemacs/doomemacs/tree/master/modules/lang

#+name:doom-lang

;;agda              ; types of types of types of types...
;;beancount         ; mind the GAAP
;;(cc +lsp)         ; C > C++ == 1
;;clojure           ; java with a lisp
;;common-lisp       ; if you've seen one lisp, you've seen them all
;;coq               ; proofs-as-programs
;;crystal           ; ruby at the speed of c
;;csharp            ; unity, .NET, and mono shenanigans
data              ; config/data formats
;;(dart +flutter)   ; paint ui and not much else
;;dhall
;;elixir            ; erlang done right
;;elm               ; care for a cup of TEA?
emacs-lisp        ; drown in parentheses
;;erlang            ; an elegant language for a more civilized age
;;ess               ; emacs speaks statistics
;;factor
;;faust             ; dsp, but you get to keep your soul
;;fortran           ; in FORTRAN, GOD is REAL (unless declared INTEGER)
;;fsharp            ; ML stands for Microsoft's Language
;;fstar             ; (dependent) types and (monadic) effects and Z3
;;gdscript          ; the language you waited for
(go                 ; the hipster dialect
 +lsp
 +tree-sitter)
;;(graphql +lsp)    ; Give queries a REST
;;(haskell +lsp)    ; a language that's lazier than I am
;;hy                ; readability of scheme w/ speed of python
;;idris             ; a language you can depend on
(json              ; At least it ain't XML
 +lsp
 +tree-sitter)
;;(java +lsp)       ; the poster child for carpal tunnel syndrome
(javascript        ; all(hope(abandon(ye(who(enter(here))))))
 +lsp
 +tree-sitter)
;;julia             ; a better, faster MATLAB
;;kotlin            ; a better, slicker Java(Script)
;;latex             ; writing papers in Emacs has never been so fun
;;lean              ; for folks with too much to prove
;;ledger            ; be audit you can be
;;lua               ; one-based indices? one-based indices
markdown          ; writing docs for people to ignore
;;nim               ; python + lisp at the speed of c
(nix               ; I hereby declare "nix geht mehr!"
 +tree-sitter)
;;ocaml             ; an objective camel
(org               ; organize your plain life in plain text
 +dragndrop
 +journal
 +pandoc
 +pomodoro
 +pretty
 +roam2)
;;php               ; perl's insecure younger brother
;;plantuml          ; diagrams for confusing people more
;;purescript        ; javascript, but functional
(python            ; beautiful is better than ugly
 +lsp
 +poetry
 +pyright
 +tree-sitter)
;;qt                ; the 'cutest' gui framework ever
;;racket            ; a DSL for DSLs
;;raku              ; the artist formerly known as perl6
;;rest              ; Emacs as a REST client
;;rst               ; ReST in peace
(ruby ;;+rails     ; 1.step {|i| p "Ruby is #{i.even? ? 'love' : 'life'}"}
 +rbenv
 +lsp
 +tree-sitting)
;;(rust +lsp)       ; Fe2O3.unwrap().unwrap().unwrap().unwrap()
;;scala             ; java, but good
;;(scheme +guile)   ; a fully conniving family of lisps
(sh                ; she sells {ba,z,fi}sh shells on the C xor
 +lsp
 +tree-sitter)
;;sml
;;solidity          ; do you need a blockchain? No.
;;swift             ; who asked for emoji variables?
;;terra             ; Earth and Moon in alignment for performance.
(web               ; the tubes
 +lsp
 +tree-sitter)
(yaml +lsp)              ; JSON, but readable
;;zig               ; C, but simpler

Emails

https://github.com/doomemacs/doomemacs/tree/master/modules/email

#+name:doom-email

(mu4e +org)
;;notmuch
;;(wanderlust +gmail)

App

https://github.com/doomemacs/doomemacs/tree/master/modules/app

#+name:doom-app

;;calendar
;;emms
;;everywhere        ; *leave* Emacs!? You must be joking
;;irc               ; how neckbeards socialize
;;(rss +org)        ; emacs as an RSS reader
;;twitter           ; twitter client https://twitter.com/vnought

Config

https://github.com/doomemacs/doomemacs/tree/master/modules/config

#+name:doom-config

literate
(default +bindings +smartparens)

General UI Tweaks

Window Titlebar

The titlebar display string will display ♢ if there exist unsaved buffer modifications & ♦ otherwise.

(setq doom-fallback-buffer-name "Doom"
      +doom-dashboard-name "Doom Dashboard")

(setq frame-title-format
      '(""
        (:eval
         (if (s-contains-p org-roam-directory (or buffer-file-name ""))
             (replace-regexp-in-string
              ".*/[0-9]*-?" "☰ "
              (subst-char-in-string ?_ ?  buffer-file-name))
           "%b"))
        (:eval
         (let ((project-name (projectile-project-name)))
           (unless (string= "-" project-name)
             (format (if (buffer-modified-p)  " ♢ %s" " ♦ %s") project-name))))))

Fonts

I use the nerdfont's Hasklig for my monospace font & Huerta Tipografica's Alegreya serif font.

(setq doom-font (font-spec :family "Hasklig" :size 14 :height 1)
      doom-variable-pitch-font (font-spec :family "Alegreya" :height 1.3)
      doom-big-font (font-spec :family "Hasklig" :size 18))

Keys

Keybinds should be centralized in $DOOMDIR/+keybinds.el. This is loaded from $DOOMDIR/config.el file via

(load! "+keybinds")

Doom comes with some good keybind macros (see here for why). Documentation for this can be found here, but in broad strokes:

1. Start with a map! macro. You can use
2. When possible use :when to limit scope.
3. Use :prefix and :prefix-map where possible.
4. Always use :desc to describe what is being done.

Below is a sample snippet from Rameez Khan's blog (first hit on "doom emacs keybind" using DDG):

(map! :leader
   (:prefix-map ("a" . "applications")
                (:prefix ("j" . "journal")
                 :desc "New journal entry" "j" #'org-journal-new-entry
                 :desc "Search journal entry" "s" #'org-journal-search)))

Note: Keybinds should be defined with in the context that they are being used, not here

Local Leader

Lets set the local leader to ,. We may want to remap this to ; later. Both of these seem to have issues with potential key conflicts with evil-snipe. This seems to primarily exists with regards to org-mode. Github issue can be found here.

(setq doom-localleader-key ",")

Speedup whichkey response

whichkey is slow to respond, lets make it a bit faster.

(setq which-key-idle-delay 0.1)

Auto-Mode Alist

Some files we'll need to set the major-mode for manually. Either based on where the file is located, or its extension. To do this add the value to the auto-mode-alist and specify the major mode.

(add-to-list 'auto-mode-alist '("/path/to/file/.*\\.file" . markdown-mode))

Tridactyl

I am currently using Firefox with Tridactyl. The editorcmd creates a temporary file & opens it with the editor of choice. The domain is included in the temporary file name, but its a fair assumption that it will markdown. We can use this to set the syntax of the file in question. This likely just be markdown.

(add-to-list 'auto-mode-alist '("/\\(tmp\\|private/var\\)/.*/tmp_.*\\.txt" . markdown-mode))

Orgmode

This file will be needed for emacs batch automation, where its not reasonable to start up my entire working env. This file can be located at $DOOMDIR/+orgmode.el.

(load! "+orgmode")

This file may get consumed via emacs batch scripting, so we need ot make sure the orgmode is actually loaded.

(require 'org)

Directories

Notes are stored in the $HOME/org directory, and are synced to GitHub. See Syncing for more on this.

(custom-set-variables '(org-directory "~/org/"))

I've tried to organize things based on purpose & this will likely change in the future. The current directory looks like this

~/org
├── .archive
├── .attach
├── README.org
├── _logseq
├── journals
├── projects
├── roam
└── work

.archive

Where old files go. See org-archive-subtree for more.

.attach

This is things that aren't orgmode files, but should be included in an orgmode file. Tangled scripts, images, etc.

(setq org-download-image-dir (concat org-directory ".attach/"))

Projects

I keep a todo.org at the root of each project. These are symlinked into the Projects directory. Nextcloud does not sync symlinked documents.

roam

org-roam is a great Zettelkasten toolkit with back link graphing. I'll try to store as much of my written notes in this format.

(setq org-roam-directory (concat org-directory "roam"))

todo

Incomplete list of todo files as there is always more.

(setq org-agenda-files (list (concat org-directory "todo" )))

Journals

Dailies. This is also handled by Org-roam.

(setq org-roam-dailies-directory (concat org-directory "journals/"))

Work

I still want to capture work related notes where ever I am though.

(defvar-local +org-capture-work-todo-file
    (expand-file-name "Work/todo.org" org-directory))
(add-to-list 'org-capture-templates
             '("w" "Work Todo" entry
               (file+headline +org-capture-work-todo-file "Inbox")
               "* [_] %i%?\n%a -  %u" :prepend t))

Syncing

Syncing of the org-directory is done via git with remote of https://github.com/jamesepatrick/notes. Changes are auto-committed & pushed using git-auto-commit-mode in Emacs & Working Copy with iOS Shortcuts on iOS.

Grab the package from MELPA

(package! git-auto-commit-mode)

For configuring it we'll want the following settings:

gac-automatically-push-p

Automatically push new changes.

gac-automatically-add-new-files-p

Automatically add new files.

Additionally we'll also want to add a big of additional logic so that we will automatically pull changes as well. It may be worth setting up a crontab to automate the pull in the future.

This snippet below is from siatwe's comment here.

(use-package! git-auto-commit-mode
  :config
  (setq-default gac-automatically-push-p t)
  (setq-default gac-automatically-add-new-files-p t)

  (defun gac-pull-before-push (&rest _args)
    (let ((current-file (buffer-file-name)))
      (shell-command "git pull")
      (when current-file
        (with-current-buffer (find-buffer-visiting current-file)
          (revert-buffer t t t)))))
  (advice-add 'gac-push :before #'gac-pull-before-push))

Configuring should be done at the at the per directory level. The following snippet should be placed at $HOME/org/.dir-locals.el.

((nil . ((eval git-auto-commit-mode 1)
         (gac-automatically-push-p t)
         (gac-automatically-add-new-files-p t))))

A Prettier Orgmode

Use a serif variable font

This uses doom-variable-pitch-font as defined in the font section.

(add-hook! 'org-mode-hook #'mixed-pitch-mode)

Pretty mode

(add-hook! 'org-mode-hook #'+org-pretty-mode)

Agenda faces

(setq org-agenda-deadline-faces
      '((1.001 . error)
        (1.0 . org-warning)
        (0.5 . org-upcoming-deadline)
        (0.0 . org-upcoming-distant-deadline)))

Prettify Symbols

There is a few of these built into the orgmode's +pretty module. Checkboxes are not included so lets include it.

(add-hook 'org-mode-hook (lambda ()
                           "Beautify Org Checkbox Symbol"`
                           (push '("[ ]" . "☐") prettify-symbols-alist)
                           (push '("[_]" . "☐") prettify-symbols-alist)
                           (push '("[X]" . "☑" ) prettify-symbols-alist)
                           (push '("[-]" . "⊟" ) prettify-symbols-alist)
                           (prettify-symbols-mode)))

And when you hover over it, disable it.

(setq prettify-symbols-unprettify-at-point 'right-edge)

Fancy Source Blocks

This was grabbed from Rasmus Pank's blog.

this makes the beginning / ending of both source and quote blocks, & headers for that display a little cleaner.

(with-eval-after-load 'org
  (defvar-local rasmus/org-at-src-begin -1
    "Variable that holds whether last position was a ")

  (defvar rasmus/ob-header-symbol ?☰
    "Symbol used for babel headers")

  (defun rasmus/org-prettify-src--update ()
    (let ((case-fold-search t)
          (re "^[ \t]*#\\+begin_src[ \t]+[^ \f\t\n\r\v]+[ \t]*")
          found)
      (save-excursion
        (goto-char (point-min))
        (while (re-search-forward re nil t)
          (goto-char (match-end 0))
          (let ((args (org-trim
                       (buffer-substring-no-properties (point)
                                                       (line-end-position)))))
            (when (org-string-nw-p args)
              (let ((new-cell (cons args rasmus/ob-header-symbol)))
                (cl-pushnew new-cell prettify-symbols-alist :test #'equal)
                (cl-pushnew new-cell found :test #'equal)))))
        (setq prettify-symbols-alist
              (cl-set-difference prettify-symbols-alist
                                 (cl-set-difference
                                  (cl-remove-if-not
                                   (lambda (elm)
                                     (eq (cdr elm) rasmus/ob-header-symbol))
                                   prettify-symbols-alist)
                                  found :test #'equal)))
        ;; Clean up old font-lock-keywords.
        (font-lock-remove-keywords nil prettify-symbols--keywords)
        (setq prettify-symbols--keywords (prettify-symbols--make-keywords))
        (font-lock-add-keywords nil prettify-symbols--keywords)
        (while (re-search-forward re nil t)
          (font-lock-flush (line-beginning-position) (line-end-position))))))

  (defun rasmus/org-prettify-src ()
    "Hide src options via `prettify-symbols-mode'.

        `prettify-symbols-mode' is used because it has uncollpasing. It's
        may not be efficient."
    (let* ((case-fold-search t)
           (at-src-block (save-excursion
                           (beginning-of-line)
                           (looking-at "^[ \t]*#\\+begin_src[ \t]+[^ \f\t\n\r\v]+[ \t]*"))))
      ;; Test if we moved out of a block.
      (when (or (and rasmus/org-at-src-begin
                     (not at-src-block))
                ;; File was just opened.
                (eq rasmus/org-at-src-begin -1))
        (rasmus/org-prettify-src--update))
      ;; Remove composition if at line; doesn't work properly.
      ;; (when at-src-block
      ;;   (with-silent-modifications
      ;;     (remove-text-properties (match-end 0)
      ;;                             (1+ (line-end-position))
      ;;                             '(composition))))
      (setq rasmus/org-at-src-begin at-src-block)))

  ;; This function helps to produce a single glyph out of a
  ;; string. The glyph can then be used in prettify-symbols-alist.
  ;; This function was provided by Ihor in the org-mode mailing list.
  (defun yant/str-to-glyph (str)
    "Transform string into glyph, displayed correctly."
    (let ((composition nil))
      (dolist (char (string-to-list str)
                    (nreverse (cdr composition)))
        (push char composition)
        (push '(Br . Bl) composition))))

  (defun rasmus/org-prettify-symbols ()
    (mapc (apply-partially 'add-to-list 'prettify-symbols-alist)
          (cl-reduce 'append
                     (mapcar (lambda (x) (list x (cons (upcase (car x)) (cdr x))))
                             `(("#+begin_src" . ?⎡) ;; ⎡ ➤ 🖝 ➟ ➤ ✎
                               ;; multi-character strings can be used with something like this:
                               ;; ("#+begin_src" . ,(yant/str-to-glyph "```"))
                               ("#+end_src"   . ?⎣) ;; ⎣ ✐
                               (":LOGBOOK:"   . ?) ;;
                               ("#+header:" . ,rasmus/ob-header-symbol)
                               ("#+begin_quote" . ?«)
                               ("#+end_quote" . ?»)))))
    (turn-on-prettify-symbols-mode)
    (add-hook 'post-command-hook 'rasmus/org-prettify-src t t))
  (add-hook 'org-mode-hook #'rasmus/org-prettify-symbols))

Drawers

https://orgmode.org/manual/Drawers.html

State Change Log

Logs updates can bleed into the notes. Sticking them in a drawer works as a better escape then indentations.

(setq org-log-into-drawer t)

Clock drawers

(setq org-clock-into-drawer t)

Roam

I use org-roam v2 for most of my note taking. TODO expand this section.

Dailies Templates

(setq org-roam-dailies-capture-templates
      '(("l" "Log" entry "*  %T %?"
         :target (file+head+olp "%<%Y-%m-%d>.org"
                                "#+title: %<%Y-%m-%d>\n#+filetags: %<:%Y:%B:daily:>\n\n* Goals\n* Logs"
                                ("Logs")))
        ("g" "Goal" entry "* TODO %?"
         :target (file+head+olp "%<%Y-%m-%d>.org"
                                "#+title: %<%Y-%m-%d>\n#+filetags: %<:%Y:%B::daily>\n\n* Goals\n* Logs"
                                ("Goals")))))

Keybinds

The standard keybind for getting to Roam's daily capture is pretty long. To capture a Log entry I have to type SPC n r d T l. I want to capture as many logs and goals as possible, so lets shorten this up some.

(map! :leader
      (:when (modulep! :lang org +roam2)
        (:prefix-map ("r" . "roam")
         :desc "Find node"              "/"    #'org-roam-node-find
         :desc "Capture to node"        "n"    #'org-roam-capture
         :desc "Capture Today"          "c"    #'org-roam-dailies-capture-today
         :desc "Goto Today"             "t"    #'org-roam-dailies-goto-today
         )
        )
      )

:leader r is used by :tools upload for "remote", but since I'm not using this lets just not care about that.

Mermaid

MermaidJS is a diagramming and charting tool similar to Dot/Graphviz, but significantly prettier with less boilerplate. We'll likely only ever want to modify it in the context of org-mode so we'll want ob-mermaid.

Add the following the packages.el

(package! ob-mermaid)

Babel stuff

Babel execute can be tweaked per the syntax see orgmode docs here.

Src blocks

These are grabbed from gtrun's configuration.'

(setq org-src-fontify-natively t
      org-src-preserve-indentation t
      org-src-tab-acts-natively t
      org-src-window-setup 'current-window)

Diff

The snippet below is largely pulled from John Kitchin Stackexchange Post.

(defun org-babel-execute:diff (body params)
  "Applies diff patches. Use with care.
See https://emacs.stackexchange.com/questions/63517/org-mode-evaluate-diff-code-block"
  (with-temp-buffer
    (insert body "\n")
    (shell-command-on-region (point-min) (point-max) "patch --strip=1" "*patch*")
    (prog1
    (with-current-buffer "*patch*" (buffer-string))
      (kill-buffer "*patch*"))))

As an sample:

#+BEGIN_SRC org :tangle a.org
1
2
#+END_SRC

#+BEGIN_SRC org :tangle b.org
1
3
#+END_SRC
#+begin_src diff
--- a.org   2021-02-21 20:20:27.000000000 -0500
+++ b.org   2021-02-21 20:20:27.000000000 -0500
@@ -1,2 +1,2 @@
 1
-2
+3
#+end_src

#+RESULTS:
: patching file a.org

#+BEGIN_SRC sh
cat a.org
#+END_SRC

#+RESULTS:
| 1 |
| 3 |

Export to Tufte

Rather than using org-export-dispatch's html export, we'll want to use ox-tufte. The HTML output is a more reasonable than the HTML format.

(package! ox-tufte)

Just load the require to setup the dependency.

(use-package! ox-tufte)

By default the org-export-dispatch, includes some basic styling. This causes issues with our HTML. We'll need to turn off these.

(after! org
  (setq org-html-head ""
        org-html-head-extra ""))

The syntax highlighting for html is done inline in the by default. We don't want to do that; we're using CSS. See the file in code.css file for more.

(after! org
  (setq org-html-htmlize-output-type "css"))

To use this you will need to include the setup file. This will load the required css & js files. See here for more.

#+SETUPFILE: ~/.dotfiles/emacs/dist/setup.org

This will load the CSS and JS files located in the dotfiles/emacs/dist/ directory.

Capture

The default +org-capture/open-frame is a little small. Let's modify the parameters to make it a little larger

(setq +org-capture-frame-parameters '((name . "doom-capture")
                                      (width . 100)
                                      (height . 20)
                                      (transient . t)
                                      ))

GPT

GPT is more useful than I thought. Its incredibly helpful for writing prose which I can struggle with due to mild dysgraphia.

ChatGPT

We will be using the karthink/gptel package.

(package! gptel)

(use-package! gptel)

This package supports multiple LLM backends. I'm going to be using the OpenAI ChatGPT backend by default. We'll need to set the API key. There are a couple ways this can be done, but we're going to set this using ~/.authinfo.gpg. This will need to be decrypted before use, but this is pretty minor.

machine api.openai.com login apikey password TOKEN

TRAIL_RUN CoPilot

I'm presently using GitHub copilot for work. It can best be summarized as having a intern periodically writing code for you. The code quality is so-so, and often buggy or incorrect. You will often spend as long debugging some of the code as you would have saved writing it yourself. But it is useful for the rote drudgery that occurs with some coding.

For this I'm going to use copilot-emacs/copilot.el.

First install the package

(package! copilot
  :recipe (:host github :repo "copilot-emacs/copilot.el" :files ("*.el")))

Then configure this

(use-package! copilot
  :hook (prog-mode . copilot-mode)
  :bind (:map copilot-completion-map
              ("<tab>" . 'copilot-accept-completion)
              ("TAB" . 'copilot-accept-completion)
              ("C-TAB" . 'copilot-accept-completion-by-word)
              ("C-<tab>" . 'copilot-accept-completion-by-word)))

This does bind to company, which I've currently removed. See Completion for specifics.

Keybinds

Keybind	Command
SPC A a	gptel-menu
SPC A c	gptel-system-prompt
SPC A m	gptel-menu
SPC A o	gptel
SPC A r	gptel-rewrite-menu
SPC A s	gptel-send
SPC A t	gptel-set-topic

(map! :leader
      (:prefix-map ("A" . "GPT")
       :desc "Menu"              "m"    #'gptel-menu
       :desc "Menu"              "a"    #'gptel-menu
       :desc "Send"              "s"    #'gptel-send
       :desc "Open Session"      "o"    #'gptel
       :desc "Set Topic"         "t"    #'gptel-set-topic
       :desc "Rewrite"           "r"    #'gptel-rewrite-menu
       :desc "Change Prompt"     "c"    #'gptel-system-prompt
       )
      )

Snippets

We've enabled the snippets module earlier. This will give us use of the Doom Snippets package, but we'll want to add our own as well. Custom snippets are added under $DOOMDIR/snippets/ directory. Documentation on how to write snippets can be found at yas-snippet/documentation and doom-snippets github page.

While we'll want to store these snippets in this orgmode document, using the +snippets/create & snippets/edit may be useful for creating these.

Orgmode

In my work todo and my roam notes I've been using a list elements with nerd-fonts icons under my section header to provide quick links for the context. Below are a few that I've been using.

•  github/example

# -*- mode: snippet -*-
# name: Github Element
# uuid: gh
# key: gh
# --
-  ${1:repo}

• 󰌷 example.com

# -*- mode: snippet -*-
# name: Link Elment
# uuid: lk
# key: lk
# --
- 󰌷 ${1:link}

•  Jira-12929

# -*- mode: snippet -*-
# name: Ticker Elment
# uuid: ticket
# key: ticket
# --
-  ${1:link}

Content Stolen From

A large amount of the details listed here have been lifted from:

• tecosaur's literate configuration.
• https://zzamboni.org/post/my-emacs-configuration-with-commentary/
• https://www.gtrun.org/custom/config.htm

Footnotes

⁴Documentation here. ⁵Yes, I'm aware make is a terrible task runner.

---

¹

for example this entire paragraph could have been skipped. ²See documentation here.

³

See Doom FAQ on this for more.

⁶

this is documented in Export to Tufte

⁷

See Doom Magit documentation.