Emacs Configuration Modules

Table of Contents

1. Overview

This directory contains modular Emacs configuration files, split from a single large emacs-configs.org file for better organization and maintainability.

2. File Structure

Each configuration module is a separate Org file:

File Description Tangles To
01-early-init.org Performance optimizations, must load before packages ~/.emacs.d/early-init.el
02-init.org Core Emacs settings and built-in packages ~/.emacs.d/init.el
03-theme.org Visual appearance, color theme, mode line ~/.emacs.d/elisp/settings/theme-conf.el
04-window.org Window management and navigation ~/.emacs.d/elisp/settings/window-conf.el
05-completion.org Completion frameworks ~/.emacs.d/elisp/settings/completion-conf.el
06-dired.org Directory editor enhancements ~/.emacs.d/elisp/settings/dired-conf.el
07-org.org Knowledge management (org-mode, org-roam) ~/.emacs.d/elisp/settings/org-conf.el
08-shell.org Terminal and shell integration ~/.emacs.d/elisp/settings/shell-conf.el
09-programming.org Language-specific configurations (index) ~/.emacs.d/elisp/settings/prog-*.el
programming/ Subdirectory with language-specific modules See programming/README.org
10-miscellaneous.org Utility functions and helpers ~/.emacs.d/elisp/*.el
11-platform-linux.org Linux-specific settings ~/.emacs.d/init.el (conditional)
12-platform-macos.org macOS-specific settings ~/.emacs.d/init.el (conditional)
13-platform-windows.org Windows-specific settings ~/.emacs.d/init.el (conditional)

3. Usage

3.1. Tangling (Generating Configuration Files)

3.1.1. Tangle All Files

From the repository root: 

./tangle.sh

This will:

  • Recursively tangle all modules in configs/ and subdirectories
  • Include files in configs/programming/ subdirectory
  • Generate all necessary .el files in ~/.emacs.d/
  • Skip backup files (*.org.backup)

3.1.2. Tangle Individual File

Open any config file in Emacs and run: 

M-x org-babel-tangle

Or use the keybinding: C-c C-v t

3.2. HTML Export

The main emacs-configs.org file uses #+INCLUDE directives to bring all modules together for export.

To export to HTML:

  1. Open ../emacs-configs.org in Emacs
  2. Run: M-x org-html-export-to-html
  3. Or use the keybinding: C-c C-e h h

Alternatively, the whole site can be built using: 

./build.sh

4. Editing

4.1. Adding Documentation

Each module should have:

  • Clear section headings (** or ***)
  • Explanatory text before code blocks
  • Comments within code blocks for complex logic

4.2. Adding New Configuration

  1. Identify the appropriate module (or create a new one)
  2. Add documentation explaining what the configuration does
  3. Add the code block with appropriate :tangle header
  4. Test by tangling and reloading Emacs

4.3. Creating New Modules

If adding a new module:

  1. Create configs/NN-name.org (use next number in sequence)
  2. Add appropriate front matter and documentation
  3. Add to ../emacs-configs.org with #+INCLUDE directive
  4. Update this README

5. Benefits of This Structure

  • Easier Navigation: Jump directly to the section you need
  • Faster Editing: Smaller files load and edit faster
  • Better Documentation: Each module can have detailed explanations
  • Selective Loading: Can tangle only specific modules during development
  • Git-Friendly: Smaller diffs, easier to review changes
  • Reusability: Individual modules can be shared or reused

6. Tangling Details

All modules preserve their original :tangle directives, so:

  • They generate the same output files as the original monolithic config
  • The directory structure in ~/.emacs.d/ remains unchanged
  • Existing Emacs setup continues to work without modification

7. Backup

The original monolithic file is backed up as: 

../emacs-configs.org.backup