merge org branch into main

1 files changed, 354 insertions, 0 deletions

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..321286c
--- /dev/null
+++ b/content/blog/2024-03-13-doom-emacs.org
@@ -0,0 +1,354 @@
+#+title: Doom Emacs & Org-Mode
+#+date: <2024-03-14 Thu 16:19:23>
+#+description: A quick look at my setup with Doom Emacs and the Org-Mode syntax.
+
+** 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=[^1]  | Move left/down/up/right to next buffer |
+
+[^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.
+
+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 |
+
+**** 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).
+
+**** 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:<time datetime='[$1]'
+      class='timestamp'>[$1]</time>@@")))
+
+(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 "<meta name='theme-color' content='#111' media='(prefers-color-scheme: dark)'>
+                     <meta name='theme-color' content='#fff' media='(prefers-color-scheme: light)'>
+                     <link rel='stylesheet' href='/syntax-theme-dark.css' media='(prefers-color-scheme: dark)'>
+                     <link rel='stylesheet' href='/syntax-theme-light.css' media='(prefers-color-scheme: light)'>
+                     <link rel='stylesheet' href='/styles.css' type='text/css'>"
+         :html-preamble "<nav class='site-nav' aria-label='site-nav' role='navigation'>
+                <ul>
+                        <li><a href='/'>Home</a></li>
+                        <li><a href='/blog/'>Blog</a></li>
+                        <li><a href='/services/'>Services</a></li>
+                        <li><a href='/wiki/'>Wiki</a></li>
+                </ul></nav>
+                <h1>%t</h1>
+                <time datetime='%d'>%d</time>"
+         :html-postamble "
+                <p>Last build: %T</p>
+                <p>Created with %c</p>"
+        )
+
+        ("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.