The Problem with Monolithic Configurations

Many Emacs users start with a single .emacs or init.el file. This works fine at first, but as your configuration grows to accommodate different programming languages, workflows, and packages, a single file becomes unwieldy. Common issues include:

• Hard-to-find settings when you need to make changes
• Difficult debugging when something breaks
• Challenging to selectively enable/disable features
• Poor organization making it hard to understand your own setup

A Modular Approach

Let’s explore a modular configuration structure based on my personal setup that addresses these issues.

Root Configuration File

The entry point for my configuration is _0x17de-emacs.el, which defines the base setup and loads other modules:

(setq initial-scratch-message nil
      ring-bell-function #'ignore)

(defvar _0x17de/load-path (file-name-directory (or load-file-name buffer-file-name))
  "Path of the _0x17de emacs config")

(defun _0x17de/load (paths)
  "Load files relative to this emacs config."
  (when (not (listp paths))
    (setq paths (list paths)))
  (dolist (path paths)
    (condition-case err
        (load (expand-file-name path _0x17de/load-path))
      (error (message "Failed to load _0x17de-config sub-library at %S: %S" path err)))))

The key here is the _0x17de/load function that loads modules with error handling, preventing a failure in one module from breaking your entire configuration.

Directory Structure

My configuration is organized into clear directories:

• init/ - Core settings (startup, UI, packages)
• langs/ - Language-specific configurations
• utils/ - General utilities and enhancements
• ext/ - External packages not available in package repositories

This structure makes it immediately clear where to find specific settings.

Core Initialization

The initialization sequence loads modules in logical groups:

(_0x17de/load
 '("./init/custom.el"
   "./init/speedup.el"
   "./init/package.el"
   "./init/encoding.el"
   "./init/gui.el"
   "./init/exwm.el"))

(_0x17de/load
 '("./utils/exec-path-from-shell"
   "./utils/minibuffer"
   "./utils/indention"
   ;; ... more utilities ... 
   ))

(_0x17de/load
 '("./langs/common"
   "./langs/ansible"
   "./langs/plantuml"
   ;; ... more languages ...
   ))

This approach lets you:

1. Control the order of initialization
2. Group related components
3. Easily comment out modules you don’t want to load

Graceful Error Handling

A crucial aspect of this setup is the error handling in the _0x17de/load function. If a module fails to load, it displays a message but continues loading other modules:

(condition-case err
    (load (expand-file-name path _0x17de/load-path))
  (error (message "Failed to load _0x17de-config sub-library at %S: %S" path err)))

This prevents a single module failure from breaking your entire Emacs experience.

Specialized Module Examples

Let’s examine a few module types to see how they encapsulate specific functionality.

Language Support

Language-specific modules handle everything needed for a particular language. For example, my Go configuration:

(use-package go-mode
  :defer t
  :bind
  (:map go-mode-map
        ([tab] . 'company-indent-or-complete-common)
        ([f1] . lsp-describe-thing-at-point)
        ([f12] . lsp-find-definition)
        ("S-<f12>" . lsp-find-references))
  :hook
  (go-mode . (lambda ()
               (setq tab-width 2)
               (setq company-backends '(company-capf
                                        company-files))
               (setq gofmt-command "goimports")
               (add-hook 'before-save-hook 'gofmt-before-save)
               (go-guru-hl-identifier-mode)
               (lsp-deferred)
               ;; ... more settings ...
               )))

This module:

• Loads only when editing Go files (:defer t)
• Sets up keybindings specific to Go files
• Configures language-specific tools and formatting
• Integrates with LSP for auto-completions and advanced IDE features

Utility Modules

Utilities enhance the core editing experience regardless of the file type you’re editing. For example, my multiple-cursors configuration:

(defun _0x17de/add-multiple-cursors-to-non-empty-lines (start end)
  "Add a cursor in each non-empty line of selection"
  (interactive "r")
  ;; ... implementation ...
  )

(use-package multiple-cursors
  :init
  (global-unset-key (kbd "M-<down-mouse-1>"))
  :bind
  (("C-M-z C-c" . mc/edit-lines)
   ("C-M-z C-M-c" . _0x17de/add-multiple-cursors-to-non-empty-lines)
   ("C-M-z >" . mc/mark-next-like-this)
   ;; ... more bindings ...
   ))

This module encapsulates a complete feature set with custom functions and keybindings.

Feature Flags

For optional features, I use custom variables as feature flags:

(defcustom _0x17de/use-exwm nil
  "Non-nil means EXWM will be enabled.
When this option is enabled, EXWM will be loaded and configured
as the window manager for this session."
  :type 'boolean
  :group '_0x17de)

(when _0x17de/use-exwm
  ;; ... EXWM configuration ...
  )

This allows toggling features without commenting out code or editing multiple files.

Benefits of This Approach

This modular approach offers several advantages:

1. Maintainability: Each module has a single responsibility
2. Performance: Lazy loading modules when needed
3. Portability: Easy to share modules between configurations
4. Resilience: Failures in one module don’t break everything
5. Clarity: Clear organization makes finding settings easier
6. Flexibility: Enable/disable features without editing code

Leveraging Built-in Emacs Utilities

Emacs provides several powerful utilities that make modular configurations easier to implement and maintain.

use-package: Package Management Made Simple

While not built into Emacs core (but bundled with Emacs 29+), use-package is essential for modular configurations:

(use-package python
  :ensure nil  ; Don't try to install built-in packages
  :defer t     ; Only load when needed
  :bind (:map python-mode-map
          ([f12] . lsp-find-definition)
          ("S-<f12>" . lsp-find-references))
  :hook ((python-mode . (lambda ()
                          (company-mode t)
                          (flycheck-mode t)
                          (lsp-deferred))))
  :config     ; Executed after the package loads
  (setq python-indent-offset 4))

Key use-package keywords:

• :ensure - Controls package installation
• :defer - Enables lazy loading
• :bind - Sets up keybindings (with automatic lazy loading)
• :hook - Adds mode hooks (with automatic lazy loading)
• :init - Code executed before loading
• :config - Code executed after loading
• :custom - Sets custom variables
• :commands - Creates autoloaded commands (callable via M-x or keybindings)

This declarative approach keeps package configuration concentrated in one place rather than scattered throughout your init file.

defcustom: User-Configurable Variables

defcustom creates proper user options with documentation, custom types, and integration with Emacs’ customization interface:

(defcustom _0x17de/python-global-virtualenv-dir "~/.venv"
  "Default directory for Python virtual environments.
This is used by pyvenv to locate and activate virtual environments."
  :type 'directory
  :group '_0x17de
  :safe #'stringp)

Benefits of defcustom over regular variables:

1. Type checking - The :type property validates values
2. Documentation - Self-documents the option
3. UI integration - Works with customize-* commands
4. Safety - The :safe property helps with security
5. Organization - Options can be grouped logically

define-minor-mode: Creating Toggleable Features

For modular features that can be enabled/disabled, define-minor-mode is perfect:

(define-minor-mode latex-compile-on-save-mode
  "Refresh the preview on save"
  :lighter " LTeXcos"
  :group latex-compile-on-save
  (if latex-compile-on-save-mode
      (add-hook 'after-save-hook 'latex-compile-on-save--compile nil t)
    (remove-hook 'after-save-hook 'latex-compile-on-save--compile t)))

This creates a toggleable mode with:

• A proper minor mode that can be enabled/disabled with M-x
• Automatic hook management when enabled/disabled
• Integration with the mode line via :lighter

eval-after-load: Targeted Configuration

For smaller configurations without use-package, eval-after-load provides similar lazy-loading capabilities:

(eval-after-load 'python-mode
  '(progn
     (define-key python-mode-map (kbd "C-c C-r") 'python-shell-send-region)
     (setq python-indent-offset 4)))

This defers execution until the specified feature is loaded, improving startup times.

with-eval-after-load: Modern Alternative

A more modern, macro-based version of eval-after-load:

(with-eval-after-load 'org
  (setq org-hide-emphasis-markers t)
  (add-hook 'org-mode-hook #'visual-line-mode))

This is cleaner than eval-after-load because it doesn’t require quoting the body.

autoload: Manual Lazy Loading

For maximum control over lazy loading:

;;;###autoload
(defun my/open-config-file ()
  "Open the main configuration file."
  (interactive)
  (find-file (expand-file-name "_0x17de-emacs.el" _0x17de/load-path)))

The ;;;###autoload cookie tells Emacs to make the function available without loading the entire file.

Implementation Tips

If you want to build a similar configuration:

1. Start small: Begin with a single file and add more as needed
2. Use consistent naming: Establish a convention for module files
3. Leverage use-package: For declarative, lazy-loaded package configuration
4. Add error handling: Ensure graceful recovery from failures
5. Document with defcustom: For user-facing configuration options
6. Use minor modes: For toggleable features
7. Embrace lazy loading: With autoload, eval-after-load, and with-eval-after-load

Conclusion

A modular Emacs configuration significantly improves maintainability and flexibility. By separating concerns into discrete modules with clear responsibilities, you can build a robust, personalized environment that evolves with your needs while remaining manageable.

This approach has served me well, allowing my configuration to grow from a few basic settings to a comprehensive development environment without becoming unwieldy. The time invested in proper organization pays dividends in the long term through improved stability and ease of modification.

Feel free to adapt this structure to your own needs or explore my complete configuration for more ideas and inspiration.

In this article, we’ll explore some of the fundamental concepts in Emacs Lisp that often confuse newcomers.

Variables: Global vs Local Scope

Elisp provides several ways to define variables, each with different scoping behaviors.

setq: Global Variables

The setq function is used to define and set global variables:

(setq my-variable "Hello, world!")

These variables are accessible from anywhere in your Emacs session once defined. They’re ideal for configuration settings or values that need to persist.

let and let*: Local Variables

For variables with limited scope, Elisp provides let and let*:

;; Using let for local binding
(let ((x 5)
      (y 10))
  (message "Sum: %d" (+ x y)))

;; x and y are not accessible here

The difference between let and let* is significant:

• let evaluates all variable expressions before binding
• let* evaluates in sequence, allowing later variables to reference earlier ones

;; This won't work with let
(let ((x 5)
      (y (+ x 2)))  ; Error: x is not yet bound when this is evaluated
  (message "y: %d" y))

;; This works with let*
(let* ((x 5)
       (y (+ x 2)))  ; Works because x is already bound
  (message "y: %d" y))  ; Output: "y: 7"

Understanding Quote (')

One of the most distinctive features of Lisp is the quote character ('). It prevents evaluation of an expression, instead treating it as data.

Quoting Variables

When you place a quote in front of a symbol:

'my-symbol

You’re telling Elisp, “Don’t evaluate this symbol, just give me the symbol itself.” This is similar to references in other programming languages.

Without the quote, Elisp would try to look up the value of the variable my-symbol.

List Syntax: '(...) vs (list ...) and (cons ...)

Lists are fundamental data structures in Lisp. There are several ways to create them:

;; These are equivalent:
'(a b c)
(list 'a 'b 'c)

;; These are also equivalent:
'(a . b)
(cons 'a 'b)

The quoted form '(...) is concise but has a limitation: everything inside is automatically quoted. This means you can’t mix evaluated and non-evaluated expressions.

When to use each:

• Use '(...) for literal lists that don’t need evaluation
• Use (list ...) when you need to mix literals and evaluated expressions:

(setq name "John")
(list 'person name 'age 30)  ; => (person "John" age 30)

Understanding Cons Cells: CAR and CDR

At the heart of Lisp’s data structures is the “cons cell” - a simple pair of values. Each cons cell has two parts, traditionally accessed with the functions car and cdr (pronounced “could-er”):

(setq my-pair (cons 'a 'b))

(car my-pair)  ; => a
(cdr my-pair)  ; => b

These peculiarly named functions are historical artifacts from the original Lisp implementation on IBM machines:

• car: Contents of the Address part of Register
• cdr: Contents of the Decrement part of Register

In modern terms, think of them as:

• car: head (first element)
• cdr: tail (rest of the list)

Lists in Lisp are actually chains of cons cells that always terminate with nil:

;; This list:
'(1 2 3)

;; Is actually structured as:
(cons 1 (cons 2 (cons 3 nil)))

Visualized as pairs:

(1 . (2 . (3 . nil)))

This implicit nil at the end is crucial - it’s what defines a “proper list” in Lisp. Without this nil termination, you would have a different data structure. The presence of this nil terminator is what allows functions like length to work properly and what lets Lisp know where a list ends.

You can extract elements from lists using these functions:

(setq numbers '(1 2 3 4))
(car numbers)       ; => 1
(cdr numbers)       ; => (2 3 4)
(car (cdr numbers)) ; => 2

Elisp provides convenient shorthand functions like cadr (car of cdr) for common combinations:

(cadr numbers)      ; => 2 (same as (car (cdr numbers)))
(caddr numbers)     ; => 3 (car of cdr of cdr)

The Dot Syntax in Pairs

In Emacs Lisp, you might encounter constructs with dot notation like:

(add-to-list 'auto-mode-alist '("\\.md\\'" . markdown-mode))

This dot notation represents a “cons cell” or pair. In this example, we’re creating a pair where the car is "\\.md\\'" and the cdr is markdown-mode.

The following expressions are equivalent:

'("\\.md\\'" . markdown-mode)
(cons "\\.md\\'" 'markdown-mode)

The dot creates a direct pair between two values. This syntax is commonly used in alists (like auto-mode-alist), mode hooks, and other paired data structures in Emacs.

When you see a dot in the middle of a list, it means “the rest of this list is the cdr of this cons cell” rather than continuing the list structure with an implicit nil at the end.

To understand the difference clearly:

;; A list with two elements (has an implicit nil at the end)
'(1 2)  ; => equivalent to (cons 1 (cons 2 nil))

;; A single cons cell (a pair) - NOT a proper list
'(1 . 2)  ; => equivalent to (cons 1 2)

The difference is significant:

(length '(1 2))     ; => 2
(length '(1 . 2))   ; => Error: Wrong type argument: listp, (1 . 2)

This distinction is fundamental to understanding how Lisp data structures work.

Function Quoting: #' vs '

In Elisp, you’ll see both 'function-name and #'function-name when referring to functions. The difference is important:

• 'function-name simply quotes the symbol
• #'function-name is shorthand for (function function-name), which specifically tells Elisp that the symbol represents a function

When should you use #'? Best practice is to use it whenever you’re referring to a function as a function, especially with higher-order functions:

;; Good practice
(mapcar #'1+ '(1 2 3))  ; => (2 3 4)

;; Works but less explicit
(mapcar '1+ '(1 2 3))

Using #' helps the byte-compiler optimize your code and makes your intent clearer to other programmers.

Association Lists (alists)

Association lists (alists) are lists of key-value pairs used for simple lookups:

(setq my-alist '((name . "John")
                 (age . 30)
                 (city . "Boston")))

You can access values using functions like assoc:

(cdr (assoc 'age my-alist))  ; => 30

Alists are frequently used in Emacs for configuration options, especially when the list is relatively small and frequently modified. They’re simple but not as efficient for large datasets.

Property Lists (plists)

Property lists are another key-value structure in Elisp, but with a different syntax:

(setq my-plist '(:name "John" :age 30 :city "Boston"))

Notice how the keys are prefixed with colons. These are called keywords, similar to Ruby’s symbols. You can access values using plist-get:

(plist-get my-plist :age)  ; => 30

Other languages with similar concepts include:

• Ruby with its symbols (:symbol)
• Clojure with keywords (:keyword)
• Elixir with atoms (:atom)

Plists are often used for function arguments that have default values or are optional.

Summary

Understanding these fundamental Emacs Lisp concepts will help you:

1. Write more effective Elisp code
2. Understand existing Emacs configurations
3. Create your own Emacs extensions

Emacs Lisp’s power comes from its simplicity and consistency. Once you grasp these basic concepts, you’ll find that the language follows logical patterns that make learning advanced features much easier.

Happy hacking!

Emacs comes with an excellent built-in tutorial that can be accessed with C-h t (Control-h followed by t). I highly recommend all new users complete this tutorial to get comfortable with Emacs’ fundamentals. That said, the tutorial is comprehensive and takes time to complete.

This guide serves as a TL;DR and quick reference of the most essential hotkeys you should memorize. Consider it a short recap of what’s worth knowing by heart to be immediately productive in Emacs, whether you’re new to the editor or just need a refresher.

Understanding Emacs Notation

Before diving into the hotkeys themselves, let’s decode how to read Emacs key notation:

• C- represents the Control key. For example, C-a means “hold Control and press a”.
• M- represents the Meta key, which on modern keyboards is typically the Alt key. So M-f means “hold Alt and press f”.
• C-x followed by another key represents a two-key sequence. Press Control and x together, release, then press the next key.
• M-x similarly starts a command sequence where you type the command name after pressing Alt and x.

Multiple modifier keys can be combined. For example, C-M-f means holding both Control and Alt while pressing f.

With this foundation, let’s explore the essential hotkeys that will dramatically improve your Emacs efficiency.

Essential Emacs Hotkeys by Category

Text Navigation

Efficient text navigation is the foundation of productive editing. These shortcuts let you move through your document with precision:

The navigation keys follow a pattern: f for forward, b for backward, p for previous, and n for next. Once you internalize these patterns, they become second nature.

Text Editing

These shortcuts handle the core editing operations that you’ll use hundreds of times daily:

A unique aspect of Emacs is its “kill ring” - a clipboard system that remembers multiple deleted items. After using C-y to paste the most recent item, you can press M-y repeatedly to cycle through previously killed text.

Region and Selection

Working with selections in Emacs involves understanding the concept of the “mark” and “point”:

The mark is where a selection begins, and the point is your cursor position. Together they define the “region” - Emacs’ term for a selection.

File Operations

These commands handle file management tasks:

The C-x C-f command is particularly powerful as it allows you to create new files by entering paths that don’t exist yet.

Buffer Management

In Emacs, a buffer is essentially an open file or space for editing:

Efficient buffer navigation is crucial when working with multiple files.

Window Management

Emacs allows for sophisticated window layouts:

The ability to split the editor into multiple windows, each showing different buffers, is one of Emacs’ most powerful features.

Search and Replace

Finding and replacing text efficiently is essential for editing:

Emacs’ incremental search updates as you type, making it quick to locate specific text.

Help System

When you inevitably need guidance, Emacs has built-in help:

The self-documenting nature of Emacs means help is always just a few keystrokes away.

Macros

Macros are powerful tools for automating repetitive tasks:

To use macros: press F3, perform the sequence of actions you want to repeat, press F4 to finish recording, then press F4 again each time you want to replay those exact keystrokes. This is incredibly useful for mass operations on text.

Command Execution

Finally, the gateway to thousands of Emacs commands:

This shortcut unlocks Emacs’ full potential, giving you access to any command by name.

Building Your Muscle Memory

Learning these hotkeys will take time, but the productivity payoff is immense. Start by mastering the navigation and basic editing commands, then gradually incorporate the others. Consider printing this list and keeping it near your workspace until the keystrokes become automatic.

Remember that Emacs is highly customizable - once you’re comfortable with these basics, you can create your own keybindings for commands you use frequently.

Conclusion

The beauty of Emacs lies in how it becomes an extension of your thinking process once you’ve internalized these commands. Text manipulation becomes effortless, allowing you to focus on your actual work rather than the mechanics of editing.

While this guide covers the essential hotkeys, it barely scratches the surface of what Emacs can do. As you grow more comfortable with these basics, explore specialized modes for your particular work, whether that’s programming in specific languages, writing prose, managing projects, or organizing your life.

What began as a seemingly steep learning curve will transform into a powerful skillset that follows you throughout your computing life. Happy editing!

The Power of Daily Granularity

One of the most impactful lessons I’ve learned is the importance of splitting journals into smaller, more manageable chunks. The configuration sets up org-journal with daily entries rather than maintaining one massive file for an entire year’s worth of thoughts and tasks. This approach offers several benefits:

• Improved Performance: Smaller files load faster and are less likely to cause Emacs to slow down
• Better Organization: Daily or weekly files create natural boundaries for your thoughts
• Easier Navigation: Finding specific entries becomes simpler when they’re organized by date

My configuration explicitly sets org-journal-dir to “~/org/journal” and uses the format (YYYYMMDD) for consistency and easy sorting.

Task Migration: Never Lose Track Again

A game-changing feature in org-journal is its ability to automatically move unfinished tasks to the next day’s entry. This prevents tasks from being forgotten in past journal entries and keeps your current day’s focus on what still needs attention.

Effective Agenda Management

The configuration reveals a crucial insight: simply journaling isn’t enough—you need to leverage org’s scheduling and deadline functions to create an effective overview of your commitments. The custom function _0x17de/org-highlight-todays-deadlines applies special highlighting to items due today, creating visual urgency for time-sensitive tasks.

Enhanced Task States with Custom Keywords

The standard TODO/DONE paradigm often feels inadequate for complex workflows. This configuration expands the vocabulary of task states:

(setq org-todo-keywords '((sequence "TODO" "WAITING" "DOING" "|" "DONE" "CANCELLED")))

Adding intermediate states like “WAITING” and “DOING” provides more context about where each task stands without requiring additional notes. The vertical bar separates active states from terminal states, a subtle but important distinction.

Visual Differentiation Through Custom Styling

The configuration goes beyond mere keywords by defining custom faces for different task states:

(org-modern-todo-faces '(("TODO" :foreground "white" :background "darkgreen" :weight bold)
                        ("DOING" :foreground "white" :background "orange" :weight bold)
                        ("WAITING" :foreground "white" :background "blue")))

This color-coding creates immediate visual feedback, making it easy to scan a journal page and instantly understand what’s in progress versus what’s waiting on external factors.

Modern Interface Enhancements

The use of org-modern-mode suggests an appreciation for clean, contemporary styling. This package enhances the visual appeal of org files with improved typography and modern design elements, making the journaling experience more pleasant.

Exploring New Frontiers: org-node

The configuration hints at exploration of org-node, a powerful package that enables treating org headings as nodes in a graph. This approach opens up interesting possibilities for knowledge management and connecting ideas across different journal entries and documents.

Convenient Keybindings for Quick Capture

Setting up a global keybinding (C-M-S-j) for creating new journal entries reduces friction in the journaling process. The fewer barriers to capturing thoughts, the more likely you are to maintain the practice consistently.

Integration with the Agenda

The configuration enables agenda integration with org-journal-enable-agenda-integration, ensuring that tasks and events from journal entries appear in your org-agenda views. This creates a unified system where your journal and task management seamlessly work together.

What’s Next?

For those inspired to explore this setup further, my complete Emacs configuration is available at https://github.com/0x17de/emacs-config. It offers additional insights into how these journaling practices fit into a broader productivity system.

As my own journey with org-journal continues, I’m particularly interested in diving deeper into org-node and exploring how graph-based knowledge management might enhance connections between journal entries over time.