From 2be43cc479dfd4cfb621f14381330c708291e324 Mon Sep 17 00:00:00 2001 From: Christian Cleberg Date: Sun, 28 Jul 2024 19:46:20 -0500 Subject: conversion from Zola to Weblorg --- content/blog/2024-03-13-doom-emacs.org | 360 +++++++++++++++++++++++++++++++++ 1 file changed, 360 insertions(+) create mode 100644 content/blog/2024-03-13-doom-emacs.org (limited to 'content/blog/2024-03-13-doom-emacs.org') diff --git a/content/blog/2024-03-13-doom-emacs.org b/content/blog/2024-03-13-doom-emacs.org new file mode 100644 index 0000000..a535e5d --- /dev/null +++ b/content/blog/2024-03-13-doom-emacs.org @@ -0,0 +1,360 @@ +#+date: <2024-03-13> +#+title: Doom Emacs & Org-Mode +#+description: + + +** Screenshots + +These screenshots are showing a project opened with projectile, a +treemacs side pane open with the project contents, multiple buffers +tiled next to each other, and the help pane open at the bottomm. + +The themes are =doom-homage-white= and =doom-homage-black=. + +#+caption: Doom Emacs Light Mode +[[https://img.cleberg.net/blog/20240314-doom-emacs/light.png]] + +#+caption: Doom Emacs Dark Mode +[[https://img.cleberg.net/blog/20240314-doom-emacs/dark.png]] + +** Getting Started + +I 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 my +personal note taking, wiki, and even this blog. As a result, I have been +stumbling further into the world of Emacs and found myself at a point +where I now prefer to do most of my basic editing within Emacs. + +I'll leave the markdown vs. org-mode debate for another post, but I love +org-mode's extensibility and interactive nature within Emacs, but it +becomes very unwieldy in any other client implementation of org-mode - +especially on iOS. On the flip side, markdown is limited in +functionality and fractured into different standards, but it's simple +and popular enough that there are a plethora of great clients to choose +from that will get the job done. + +For now, I want to focus on how I have been using Emacs and some of the +things that would have helped me learn it faster had I known where to +start. + +*** Installation + +This post focuses on [[https://github.com/doomemacs/doomemacs][Doom +Emacs]], which is an Emacs framework that provides an alternative +experience to the vanilla [[https://www.gnu.org/software/emacs/][GNU +Emacs]]. + +The +[[https://github.com/doomemacs/doomemacs/blob/master/docs/getting_started.org][Getting +Start Guide]] has an extremely detailed walkthrough of installation for +all systems, so please refer to that guide for up-to-date instructions. + +I chose to install on macOS, using the Homebrew option with the +=railwaycat/emacsmacport= version of Emacs. + +Once the program is installed, you can run the program by typing =emacs= +in a terminal. If you installed a version of Emacs that supports both a +GUI and TUI, you will have to run =emacs -nw= to get the TUI instead of +the default GUI. + +*** Configuration + +Once installed, you can configure Doom by editing the files within the +=~/.doom.d/= directory. This directory holds four files: + +1. =config.el= - Personal configuration file +2. =custom.el= - Custom set variables +3. =init.el= - Doom modules and load order, must run =doom sync= after + modifying +4. =packages.el= - Declare packages to install in this file, then run + =doom sync= to install + +I only needed a few customizations for my configuration, so I'll list +them below. + +#+begin_src lisp +;; ~/.doom.d/config.el +(setq doom-theme 'doom-homage-black) +(setq display-line-numbers-type t) +(setq org-directory "~/Documents/Notes/") + +;; lengthy org-publish directives at the bottom of the file +#+end_src + +#+begin_src lisp +;; ~/.doom.d/init.el +(doom! :input + :completion + company ; the ultimate code completion backend + vertico ; the search engine of the future + + :ui + doom ; what makes DOOM look the way it does + doom-dashboard ; a nifty splash screen for Emacs + (emoji +unicode) ; 🙂 + hl-todo ; highlight TODO/FIXME/NOTE/DEPRECATED/HACK/REVIEW + minimap ; show a map of the code on the side + modeline ; snazzy, Atom-inspired modeline, plus API + 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 + (vc-gutter +pretty) ; vcs diff in the fringe + vi-tilde-fringe ; fringe tildes to mark beyond EOB + workspaces ; tab emulation, persistence & separate workspaces + + :editor + (evil +everywhere); come to the dark side, we have cookies + file-templates ; auto-snippets for empty files + fold ; (nigh) universal code folding + snippets ; my elves. They type so I don't have to + + :emacs + dired ; making dired pretty [functional] + electric ; smarter, keyword-based electric-indent + undo ; persistent, smarter undo for your inevitable mistakes + vc ; version-control and Emacs, sitting in a tree + + :term + term ; basic terminal emulator for Emacs + + :checkers + syntax ; tasing you for every semicolon you forget + + :tools + (eval +overlay) ; run code, run (also, repls) + lookup ; navigate your code and its documentation + magit ; a git porcelain for Emacs + + :os + (:if (featurep :system 'macos) macos) ; improve compatibility with macOS + + :lang + common-lisp ; if you've seen one lisp, you've seen them all + emacs-lisp ; drown in parentheses + markdown ; writing docs for people to ignore + org ; organize your plain life in plain text + python ; beautiful is better than ugly + sh ; she sells {ba,z,fi}sh shells on the C xor + + :app + irc ; how neckbeards socialize + (rss +org) ; emacs as an RSS reader + + (default +bindings +smartparens)) +#+end_src + +If you're editing these files within Doom directly, remember to run +=SPC h r r= to reload the configuration. Also remember to run +=doom sync= for any changes to the =init.el= or =packages.el= files. + +** Basic Functionality + +I kept a cheat sheet note open at first with all of the basic functions +typed out, copied as I went through the tutorial. After a little while, +I no longer needed it. I highly recommend writing down the most +applicable shortcuts for your preferred functionality and refer back to +it until you've memorized it. + +Memorizing the shortcuts will differ based on the type of Emacs +framework being used. Personally, migrating from vanilla Emacs to Doom +Emacs simplified everything by a large factor and instantly enabled me +to start working on my projects, eliminating most of the hurdles I was +running into. The vanilla emacs hotkeys became obnoxious and I actually +stopped using Emacs entirely for about a month before trying Doom. + +For me, the first logical step is to interact with the local filesystem. +To do this, I needed to know how to open directories, open files, save +files, discard changes, close files, and switch between open files. Here +are some example shortcuts I've written down in order to accomplish +file-based actions. + +| Doom Hotkey | Emacs Hotkey | Description | +|-----------------+---------------+----------------------------------------| +| =SPC := | =C-x= | Run functions | +| =SPC f f= | =C-x f= | Open file in buffer | +| =SPC f d= | =C-x d= | Open directory with =dired= | +| =i= | =C-x C-q= | Edit current buffer (insert mode) | +| =q= | =C-x C-q= | Quit out of insert mode | +| =SPC f s= | =C-x s= | Save current buffer | +| =SPC b k= | =C-x k= | Kill current buffer | +| =SPC w h/j/k/l= | =C-x o=[fn:2] | Move left/down/up/right to next buffer | + +In general, when in Doom, you can press =SPC= and wait a second for the +help pane to appear with all available hotkey options. For example, you +can press =SPC=, wait for the help pane, and then select a key such as +=g= to enter the git help pane and explore further command options. + +** Editing + +Next in my process is to dive into editing for any languages I'm +currently using. In this post, I will just cover Markdown and Org-Mode +but I have also been slowly adoping some Python and general web dev +tools as well. + +*** Markdown + +#+caption: Markdown Preview +[[https://img.cleberg.net/blog/20240314-doom-emacs/markdown.png]] + +Markdown is fairly simple as the syntax is limited, so just make sure +the =~/.doom.d/init.el= includes the =markdown= declaration in the +=:lang= section. + +This package includes the following hotkey menus. The insert and toggle +menu expands further, allowing you to insert various markdown elements +and toggle things like link hiding. + +| Doom Hotkey | Function | +|------------------------------+--------------------------| +| =SPC m '= | markdown-edit-code-block | +| =SPC m e= | markdown-export | +| =SPC m i= | +insert | +| =SPC m o= | markdown-open | +| =SPC m p= | markdown-preview | +| =SPC m t= | +toggle | +| =SPC : markdown-table-align= | markdown-table-align | + +*** Org-Mode + +#+caption: Org-Mode Preview +[[https://img.cleberg.net/blog/20240314-doom-emacs/org.png]] + +Similar to the markdown section above, ensure that the +=~/.doom.d/init.el= includes the =org= declaration in the =:lang= +section. + +There are a few hot keys, but a quick search with =SPC : org= shows that +there are 865 possible org-related functions you can run. I won't +possibly be able to list them all, so I will simply cover a few of the +basic commands I use myself. + +| Doom Hotkey | Function | +|----------------+---------------------------------------| +| =SPC m t= | org-todo | +| =SPC n t= | org-todo-list | +| =SPC o A= | org-agenda | +| =SPC X= | org-capture | +| =SPC m p p= | org-priority | +| =SPC m d s= | org-schedule | +| =TAB= | org-cycle | +| =SHIFT TAB= | Collapse/open all headings in buffer | +| =M-q= | Format/wrap current section | +| =M-Left/Right= | Demote/promote current heading | +| =M-Down/Up= | Shift current heading section down/up | + +1. Org-Publish + + Org includes a + [[https://orgmode.org/manual/Publishing.html][publishing management + system]] by default that allows you to export org files to Org, + iCalendar, HTML, LaTex, Markdown, ODT, and Plain Text. Most of these + can be exported into another buffer and opened, or simply to an + external file. + + While inside an org file, simply run =SPC m e= or + =M-x org-export-dispatch= to open the export menu. This menu will + show all options and ask you to select an option. If you want to + export to HTML, simply press =h= and then =H= (As HTML buffer), =h= + (As HTML file), or =o= (As HTML file and open). + +2. Projects + + Some publishing options are easier with a defined project in Emacs. + To create a project within Emacs, I use two methods: + + 1. Add the project via the projectile command =SPC p a=. Does not + always work for me. + 2. Add an empty =.projectile= file in the project root. + + Once a project has been created, you can create custom publishing + actions within your =~/.doom.d/config.el= file. For example, here's a + test project I created to try and convert this blog to org-mode + recently. + + #+begin_src lisp + ;; org-publish + (require 'ox-publish) + + (defun my/org-sitemap-date-entry-format (entry style project) "Format ENTRY in + org-publish PROJECT Sitemap format ENTRY ENTRY STYLE format that includes + date." (let ((filename (org-publish-find-title entry project))) (if (= (length + filename) 0) (format "*%s*" entry) (format "{{{timestamp(%s)}}} + [[file:%s][%s]]" (format-time-string "%Y-%m-%d" (org-publish-find-date entry + project)) entry filename)))) + + (setq org-export-global-macros '(("timestamp" . "@@html:@@"))) + + (setq org-publish-project-alist + `(("blog" + :base-directory "~/Source/cleberg.net/" + :base-extension "org" + :recursive t + :publishing-directory "~/Source/cleberg.net/public/" + :publishing-function org-html-publish-to-html + ;; HTML5 + :html-doctype "html5" + :html-html5-fancy t + ;; Disable some Org's HTML defaults + :html-head-include-scripts nil + :html-head-include-default-style nil + :section-numbers nil + :with-title nil + ;; Sitemap + :auto-sitemap t + :sitemap-title: "Sitemap" + :sitemap-sort-files anti-chronologically + ; :sitemap-function my/org-sitemap-date-entry-format + ;; Customize HTML output + :html-divs ((preamble "header" "preamble") + (content "main" "content") + (postamble "footer" "postamble")) + :html-head " + + + + " + :html-preamble " +

%t

+ " + :html-postamble " +

Last build: %T

+

Created with %c

" + ) + + ("static" + :base-directory "~/Source/cleberg.net/static/" + :base-extension "css\\|txt\\|jpg\\|gif\\|png" + :recursive t + :publishing-directory "~/Source/cleberg.net/public/" + :publishing-function org-publish-attachment) + + ("cleberg.net" :components ("blog" "static")))) + #+end_src + +** General Thoughts + +I have enjoyed Doom Emacs (far more than GNU Emacs) and will likely +continue to use it as my main editor for the time being. Org-Mode is +certainly the largest factor here, as I far prefer it over Markdown due +to its inherent features and detailed markup options. However, working +with org-mode on iOS has been a pain and I will have to see if there's +an easier way to resolve those issues or if going back to separate +Markdown, Reminders, and Calendar apps is easier to work with than an +all-in-one org solution. + +[fn:1] Doom's evil-window functionality is a bit different from GNU + Emacs, but you can always switch to the "other" buffer with + =C-x o= or =C-x b= to get a list of buffers to select. + +[fn:2] Doom's evil-window functionality is a bit different from GNU + Emacs, but you can always switch to the "other" buffer with + =C-x o= or =C-x b= to get a list of buffers to select. -- cgit v1.2.3-70-g09d2