content/blog/2024-03-13-doom-emacs.org
340 lines · 15886 bytes
1#+date: <2024-03-13 Wed 00:00:00>
2#+title: Configuration Guide for Doom Emacs and Org-Mode to Optimize Workflow
3#+description: Technical manual covering installation, configuration files, and usage procedures for Doom Emacs and Org-Mode targeting note management and task organization.
4#+slug: doom-emacs
5#+filetags: :doom:emacs:workflow:
6
7** Screenshots
8
9These screenshots are showing a project opened with projectile, a treemacs side
10pane open with the project contents, multiple buffers tiled next to each other,
11and the help pane open at the bottomm.
12
13The themes are =doom-homage-white= and =doom-homage-black=.
14
15#+caption: Doom Emacs Light Mode
16[[https://img.cleberg.net/blog/20240314-doom-emacs/light.png]]
17
18#+caption: Doom Emacs Dark Mode
19[[https://img.cleberg.net/blog/20240314-doom-emacs/dark.png]]
20
21** Getting Started
22
23I have been switching back and forth between [[https://en.wikipedia.org/wiki/Markdown][markdown]] and [[https://en.wikipedia.org/wiki/Org-mode][org-mode]] recently for
24my personal note taking, wiki, and even this blog. As a result, I have been
25stumbling further into the world of Emacs and found myself at a point where I
26now prefer to do most of my basic editing within Emacs.
27
28I'll leave the markdown vs. org-mode debate for another post, but I love
29org-mode's extensibility and interactive nature within Emacs, but it becomes
30very unwieldy in any other client implementation of org-mode - especially on
31iOS. On the flip side, markdown is limited in functionality and fractured into
32different standards, but it's simple and popular enough that there are a
33plethora of great clients to choose from that will get the job done.
34
35For now, I want to focus on how I have been using Emacs and some of the things
36that would have helped me learn it faster had I known where to start.
37
38*** Installation
39
40This post focuses on [[https://github.com/doomemacs/doomemacs][Doom Emacs]], which is an Emacs framework that provides an
41alternative experience to the vanilla [[https://www.gnu.org/software/emacs/][GNU Emacs]].
42
43The [[https://github.com/doomemacs/doomemacs/blob/master/docs/getting_started.org][Getting Start Guide]] has an extremely detailed walkthrough of installation
44for all systems, so please refer to that guide for up-to-date instructions.
45
46I chose to install on macOS, using the Homebrew option with the
47=railwaycat/emacsmacport= version of Emacs.
48
49Once the program is installed, you can run the program by typing =emacs= in a
50terminal. If you installed a version of Emacs that supports both a GUI and TUI,
51you will have to run =emacs -nw= to get the TUI instead of the default GUI.
52
53*** Configuration
54
55Once installed, you can configure Doom by editing the files within the
56=~/.doom.d/= directory. This directory holds four files:
57
581. =config.el= - Personal configuration file
592. =custom.el= - Custom set variables
603. =init.el= - Doom modules and load order, must run =doom sync= after modifying
614. =packages.el= - Declare packages to install in this file, then run =doom
62 sync= to install
63
64I only needed a few customizations for my configuration, so I'll list them
65below.
66
67#+begin_src lisp
68;; ~/.doom.d/config.el
69(setq doom-theme 'doom-homage-black)
70(setq display-line-numbers-type t)
71(setq org-directory "~/Documents/Notes/")
72
73;; lengthy org-publish directives at the bottom of the file
74#+end_src
75
76#+begin_src lisp
77;; ~/.doom.d/init.el
78(doom! :input
79 :completion
80 company ; the ultimate code completion backend
81 vertico ; the search engine of the future
82
83 :ui
84 doom ; what makes DOOM look the way it does
85 doom-dashboard ; a nifty splash screen for Emacs
86 (emoji +unicode) ; 🙂
87 hl-todo ; highlight TODO/FIXME/NOTE/DEPRECATED/HACK/REVIEW
88 minimap ; show a map of the code on the side
89 modeline ; snazzy, Atom-inspired modeline, plus API
90 ophints ; highlight the region an operation acts on
91 (popup +defaults) ; tame sudden yet inevitable temporary windows
92 tabs ; a tab bar for Emacs
93 treemacs ; a project drawer, like neotree but cooler
94 (vc-gutter +pretty) ; vcs diff in the fringe
95 vi-tilde-fringe ; fringe tildes to mark beyond EOB
96 workspaces ; tab emulation, persistence & separate workspaces
97
98 :editor
99 (evil +everywhere); come to the dark side, we have cookies
100 file-templates ; auto-snippets for empty files
101 fold ; (nigh) universal code folding
102 snippets ; my elves. They type so I don't have to
103
104 :emacs
105 dired ; making dired pretty [functional]
106 electric ; smarter, keyword-based electric-indent
107 undo ; persistent, smarter undo for your inevitable mistakes
108 vc ; version-control and Emacs, sitting in a tree
109
110 :term
111 term ; basic terminal emulator for Emacs
112
113 :checkers
114 syntax ; tasing you for every semicolon you forget
115
116 :tools
117 (eval +overlay) ; run code, run (also, repls)
118 lookup ; navigate your code and its documentation
119 magit ; a git porcelain for Emacs
120
121 :os
122 (:if (featurep :system 'macos) macos) ; improve compatibility with macOS
123
124 :lang
125 common-lisp ; if you've seen one lisp, you've seen them all
126 emacs-lisp ; drown in parentheses
127 markdown ; writing docs for people to ignore
128 org ; organize your plain life in plain text
129 python ; beautiful is better than ugly
130 sh ; she sells {ba,z,fi}sh shells on the C xor
131
132 :app
133 irc ; how neckbeards socialize
134 (rss +org) ; emacs as an RSS reader
135
136 (default +bindings +smartparens))
137#+end_src
138
139If you're editing these files within Doom directly, remember to run =SPC h r r=
140to reload the configuration. Also remember to run =doom sync= for any changes to
141the =init.el= or =packages.el= files.
142
143** Basic Functionality
144
145I kept a cheat sheet note open at first with all of the basic functions typed
146out, copied as I went through the tutorial. After a little while, I no longer
147needed it. I highly recommend writing down the most applicable shortcuts for
148your preferred functionality and refer back to it until you've memorized it.
149
150Memorizing the shortcuts will differ based on the type of Emacs framework being
151used. Personally, migrating from vanilla Emacs to Doom Emacs simplified
152everything by a large factor and instantly enabled me to start working on my
153projects, eliminating most of the hurdles I was running into. The vanilla emacs
154hotkeys became obnoxious and I actually stopped using Emacs entirely for about a
155month before trying Doom.
156
157For me, the first logical step is to interact with the local filesystem. To do
158this, I needed to know how to open directories, open files, save files, discard
159changes, close files, and switch between open files. Here are some example
160shortcuts I've written down in order to accomplish file-based actions.
161
162| Doom Hotkey | Emacs Hotkey | Description |
163|-----------------+---------------+----------------------------------------|
164| =SPC := | =C-x= | Run functions |
165| =SPC f f= | =C-x f= | Open file in buffer |
166| =SPC f d= | =C-x d= | Open directory with =dired= |
167| =i= | =C-x C-q= | Edit current buffer (insert mode) |
168| =q= | =C-x C-q= | Quit out of insert mode |
169| =SPC f s= | =C-x s= | Save current buffer |
170| =SPC b k= | =C-x k= | Kill current buffer |
171| =SPC w h/j/k/l= | =C-x o=[fn:2] | Move left/down/up/right to next buffer |
172
173In general, when in Doom, you can press =SPC= and wait a second for the help
174pane to appear with all available hotkey options. For example, you can press
175=SPC=, wait for the help pane, and then select a key such as =g= to enter the
176git help pane and explore further command options.
177
178** Editing
179
180Next in my process is to dive into editing for any languages I'm currently
181using. In this post, I will just cover Markdown and Org-Mode but I have also
182been slowly adoping some Python and general web dev tools as well.
183
184*** Markdown
185
186#+caption: Markdown Preview
187[[https://img.cleberg.net/blog/20240314-doom-emacs/markdown.png]]
188
189Markdown is fairly simple as the syntax is limited, so just make sure the
190=~/.doom.d/init.el= includes the =markdown= declaration in the =:lang= section.
191
192This package includes the following hotkey menus. The insert and toggle menu
193expands further, allowing you to insert various markdown elements and toggle
194things like link hiding.
195
196| Doom Hotkey | Function |
197|------------------------------+--------------------------|
198| =SPC m '= | markdown-edit-code-block |
199| =SPC m e= | markdown-export |
200| =SPC m i= | +insert |
201| =SPC m o= | markdown-open |
202| =SPC m p= | markdown-preview |
203| =SPC m t= | +toggle |
204| =SPC : markdown-table-align= | markdown-table-align |
205
206*** Org-Mode
207
208#+caption: Org-Mode Preview
209[[https://img.cleberg.net/blog/20240314-doom-emacs/org.png]]
210
211Similar to the markdown section above, ensure that the =~/.doom.d/init.el=
212includes the =org= declaration in the =:lang= section.
213
214There are a few hot keys, but a quick search with =SPC : org= shows that there
215are 865 possible org-related functions you can run. I won't possibly be able to
216list them all, so I will simply cover a few of the basic commands I use myself.
217
218| Doom Hotkey | Function |
219|----------------+---------------------------------------|
220| =SPC m t= | org-todo |
221| =SPC n t= | org-todo-list |
222| =SPC o A= | org-agenda |
223| =SPC X= | org-capture |
224| =SPC m p p= | org-priority |
225| =SPC m d s= | org-schedule |
226| =TAB= | org-cycle |
227| =SHIFT TAB= | Collapse/open all headings in buffer |
228| =M-q= | Format/wrap current section |
229| =M-Left/Right= | Demote/promote current heading |
230| =M-Down/Up= | Shift current heading section down/up |
231
2321. Org-Publish
233
234 Org includes a [[https://orgmode.org/manual/Publishing.html][publishing management system]] by default that allows you to
235 export org files to Org, iCalendar, HTML, LaTex, Markdown, ODT, and Plain
236 Text. Most of these can be exported into another buffer and opened, or simply
237 to an external file.
238
239 While inside an org file, simply run =SPC m e= or =M-x org-export-dispatch=
240 to open the export menu. This menu will show all options and ask you to
241 select an option. If you want to export to HTML, simply press =h= and then
242 =H= (As HTML buffer), =h= (As HTML file), or =o= (As HTML file and open).
243
2442. Projects
245
246 Some publishing options are easier with a defined project in Emacs. To create
247 a project within Emacs, I use two methods:
248
249 1. Add the project via the projectile command =SPC p a=. Does not always work
250 for me.
251 2. Add an empty =.projectile= file in the project root.
252
253 Once a project has been created, you can create custom publishing actions
254 within your =~/.doom.d/config.el= file. For example, here's a test project I
255 created to try and convert this blog to org-mode recently.
256
257 #+begin_src lisp
258 ;; org-publish
259 (require 'ox-publish)
260
261 (defun my/org-sitemap-date-entry-format (entry style project) "Format ENTRY in
262 org-publish PROJECT Sitemap format ENTRY ENTRY STYLE format that includes
263 date." (let ((filename (org-publish-find-title entry project))) (if (= (length
264 filename) 0) (format "*%s*" entry) (format "{{{timestamp(%s)}}}
265 [[file:%s][%s]]" (format-time-string "%Y-%m-%d" (org-publish-find-date entry
266 project)) entry filename))))
267
268 (setq org-export-global-macros '(("timestamp" . "@@html:<time datetime='[$1]'
269 class='timestamp'>[$1]</time>@@")))
270
271 (setq org-publish-project-alist
272 `(("blog"
273 :base-directory "~/Source/cleberg.net/"
274 :base-extension "org"
275 :recursive t
276 :publishing-directory "~/Source/cleberg.net/public/"
277 :publishing-function org-html-publish-to-html
278 ;; HTML5
279 :html-doctype "html5"
280 :html-html5-fancy t
281 ;; Disable some Org's HTML defaults
282 :html-head-include-scripts nil
283 :html-head-include-default-style nil
284 :section-numbers nil
285 :with-title nil
286 ;; Sitemap
287 :auto-sitemap t
288 :sitemap-title: "Sitemap"
289 :sitemap-sort-files anti-chronologically
290 ; :sitemap-function my/org-sitemap-date-entry-format
291 ;; Customize HTML output
292 :html-divs ((preamble "header" "preamble")
293 (content "main" "content")
294 (postamble "footer" "postamble"))
295 :html-head "<meta name='theme-color' content='#111' media='(prefers-color-scheme: dark)'>
296 <meta name='theme-color' content='#fff' media='(prefers-color-scheme: light)'>
297 <link rel='stylesheet' href='/syntax-theme-dark.css' media='(prefers-color-scheme: dark)'>
298 <link rel='stylesheet' href='/syntax-theme-light.css' media='(prefers-color-scheme: light)'>
299 <link rel='stylesheet' href='/styles.css' type='text/css'>"
300 :html-preamble "<nav class='site-nav' aria-label='site-nav' role='navigation'>
301 <ul>
302 <li><a href='/'>Home</a></li>
303 <li><a href='/blog/'>Blog</a></li>
304 <li><a href='/services/'>Services</a></li>
305 <li><a href='/wiki/'>Wiki</a></li>
306 </ul></nav>
307 <h1>%t</h1>
308 <time datetime='%d'>%d</time>"
309 :html-postamble "
310 <p>Last build: %T</p>
311 <p>Created with %c</p>"
312 )
313
314 ("static"
315 :base-directory "~/Source/cleberg.net/static/"
316 :base-extension "css\\|txt\\|jpg\\|gif\\|png"
317 :recursive t
318 :publishing-directory "~/Source/cleberg.net/public/"
319 :publishing-function org-publish-attachment)
320
321 ("cleberg.net" :components ("blog" "static"))))
322 #+end_src
323
324** General Thoughts
325
326I have enjoyed Doom Emacs (far more than GNU Emacs) and will likely continue to
327use it as my main editor for the time being. Org-Mode is certainly the largest
328factor here, as I far prefer it over Markdown due to its inherent features and
329detailed markup options. However, working with org-mode on iOS has been a pain
330and I will have to see if there's an easier way to resolve those issues or if
331going back to separate Markdown, Reminders, and Calendar apps is easier to work
332with than an all-in-one org solution.
333
334[fn:1] Doom's evil-window functionality is a bit different from GNU Emacs, but
335 you can always switch to the "other" buffer with =C-x o= or =C-x b= to
336 get a list of buffers to select.
337
338[fn:2] Doom's evil-window functionality is a bit different from GNU Emacs, but
339 you can always switch to the "other" buffer with =C-x o= or =C-x b= to
340 get a list of buffers to select.