Emacs Configuration Manual

A guide to every package and setting in mhrdq8i/elispconf.

File Structure

~/.emacs.d/
├── init.el              ← Entry point, loads everything
├── custom.el            ← Auto-generated by Emacs (don't edit manually)
└── lisp/
    ├── setup-common.el  ← UI, editor, general packages
    ├── setup-git.el     ← Git integration
    ├── setup-devops.el  ← Docker, Kubernetes, Ansible
    ├── lang-rust.el     ← Rust development
    └── lang-markdown.el ← Markdown editing

init.el sets up the package manager, then loads each file with require. The order matters — setup-common.el loads first because other files depend on packages it configures (like eglot and company).

init.el — Package Manager

Setting	What it does
package-archives	Tells Emacs where to download packages from. MELPA has community packages, GNU ELPA has official ones.
use-package	A macro that makes installing and configuring packages cleaner. Without it, you'd write a lot of boilerplate.
use-package-always-ensure t	Automatically installs any package you mention with use-package if it's not already installed.
custom-file	Emacs auto-saves UI settings (like theme changes) to a file. This keeps that junk out of init.el.

setup-common.el — General Settings

UI Settings

Setting	Why
inhibit-startup-message t	Skips the default welcome screen. You don't need it.
tool-bar-mode -1	Removes the toolbar (the row of icons below the menu). Wastes space.
menu-bar-mode -1	Removes the menu bar. You'll use keybindings instead.
scroll-bar-mode -1	Removes the scrollbar. The modeline already shows your position.
global-display-line-numbers-mode 1	Shows line numbers on the left. Essential for programming.
column-number-mode 1	Shows the current column in the modeline. Useful for staying within 80 chars.
set-face-attribute 'default nil :height 120	Sets font size to 12pt (height is in 1/10 pt units).
global-hl-line-mode 1	Highlights the line your cursor is on. Makes it easier to find your cursor.

Editor Behavior

Setting	Why
indent-tabs-mode nil	Uses spaces instead of tabs. Standard for most languages.
tab-width 4	Each indent level is 4 spaces.
make-backup-files nil	Stops Emacs from creating file~ backup files everywhere.
auto-save-default nil	Stops Emacs from creating #file# autosave files. You save manually with C-x C-s.
create-lockfiles nil	Stops .#file lock files. Only matters for multi-user editing.
require-final-newline t	Adds a newline at the end of every file on save. POSIX standard, avoids git diffs.
show-trailing-whitespace t	Highlights trailing spaces in red. Keeps your code clean.

Scrolling

Setting	Why
scroll-margin 3	Keeps 3 lines visible above/below the cursor when scrolling. Prevents the cursor from hitting the edge.
scroll-conservatively 100	Scrolls one line at a time instead of jumping half a page. Feels more natural.

Quality of Life

Setting	Why
save-place-mode 1	Remembers your cursor position in each file. When you reopen a file, you're back where you left off.
show-paren-mode 1	Highlights matching parentheses/brackets. Essential when writing Lisp or any code with nesting.
electric-pair-mode 1	Auto-closes brackets, quotes, parens. Type ( and you get () with cursor inside.
global-auto-revert-mode 1	If a file changes on disk (e.g., git pull), Emacs reloads it automatically.
ring-bell-function 'ignore	Disables the beep sound. Nobody wants that.
delete-selection-mode 1	Selected text gets replaced when you type, like every other editor. Without this, typed text just inserts alongside the selection.
fill-column 80	Sets the recommended line width to 80 characters. Used by M-q to wrap text.

Encoding

Setting	Why
prefer-coding-system 'utf-8	Everything is UTF-8. Prevents encoding issues with special characters.

setup-common.el — Packages

doom-themes

What: A collection of modern, well-designed color themes.

Why: doom-one is a dark theme with good contrast and syntax highlighting. It's easy on the eyes for long coding sessions.

doom-modeline

What: A fancy modeline (the status bar at the bottom).

Why: Shows file name, git branch, line/column, encoding, and major mode in a clean, compact format. Much better than the default.

nerd-icons

What: Icon font support.

Why: Used by doom-modeline and treemacs to display file type icons. Run M-x nerd-icons-install-fonts the first time.

which-key

What: Displays available keybinding completions in a popup.

Why: When you press a prefix like C-c and pause for 0.3 seconds, a popup shows all the keys you can press next and what they do. This is how you discover and learn keybindings. Extremely valuable for beginners.

company

What: **Comp**lete **Any**thing — an auto-completion framework.

Why: Pops up a completion menu as you type. Shows function names, variables, keywords. Works with every language through backends. eglot feeds it smart completions from the language server.

Setting	Why
company-idle-delay 0.1	Shows completions after 100ms of typing. Fast but not intrusive.
company-minimum-prefix-length 1	Starts completing after just 1 character.
company-selection-wrap-around t	Scrolling past the last suggestion wraps to the first.
company-tooltip-align-annotations t	Right-aligns type annotations in the popup. Cleaner look.

eglot

What: Emacs's built-in LSP (Language Server Protocol) client.

Why: Connects Emacs to language servers like rust-analyzer. This gives you go-to-definition, find references, inline errors, completions, rename, and code actions. It's the single most important package for programming.

Why eglot over lsp-mode? Eglot is built into Emacs 29+, lighter, and follows Emacs conventions. Less configuration, fewer dependencies.

projectile

What: Project management — treats any git repo (or directory with a marker file) as a "project."

Why: Lets you jump between projects (C-c p p), find files within a project (C-c p f), and grep across the whole project (C-c p s g). Without this, you're stuck opening files one at a time.

treemacs

What: A file tree sidebar, similar to VS Code's explorer.

Why: Visual overview of your project structure. Toggle it with C-c T. Useful when exploring unfamiliar codebases.

undo-tree

What: Visualizes your undo history as a tree instead of a linear stack.

Why: Emacs's default undo is confusing — redo is "undo the undo." Undo-tree gives you a visual branching history so you never lose a state.

multiple-cursors

What: Edit multiple places at once with multiple cursors.

Why: Select a word, press C-> to add a cursor at the next occurrence, repeat. Now type once and all cursors update. Great for renaming variables or editing repetitive code.

expand-region

What: Incrementally expands your selection by semantic units.

Why: Press C-= and selection grows: word → string → expression → block → function. Press again to expand more. Much faster than manual selection.

move-text

What: Moves the current line or selected lines up or down.

Why: M-S-Up / M-S-Down reorders lines without cutting and pasting. Common operation when reorganizing code.

avy

What: Jump to any visible text with 2 characters.

Why: Press C-;, type 2 characters, and avy highlights all matches with letters. Press a letter to jump there instantly. Faster than searching or arrow keys for on-screen navigation.

rg (ripgrep)

What: Search across files using ripgrep.

Why: Faster than grep. Searches your project for a string and shows results with jump-to-location. Respects .gitignore automatically.

ace-window

What: Jump to any window with a single character.

Why: When you have 3+ windows open, M-o labels each window with a letter. Press the letter to switch. Faster than cycling with C-x o.

setup-git.el — Git Integration

magit

What: A complete Git interface inside Emacs.

Why: This is widely considered the best Git interface on any platform. Instead of typing git status, git add, git commit in a terminal, you do everything interactively in a buffer.

Binding	Why
C-x g	Your main entry point. Opens the status buffer — shows staged, unstaged, and untracked files.
C-x M-g	Quick access to any Magit command via a dispatch menu.
C-c g s	Alternative way to open status.
C-c g b	Blame mode — shows who wrote each line and when.
C-c g l	Shows the commit log for the current branch.
C-c g d	Shows the diff for the current file.

setup-devops.el — DevOps Tools

dockerfile-mode

What: Syntax highlighting and editing support for Dockerfiles.

Why: Without it, Dockerfiles are plain text with no highlighting or indentation help.

docker

What: Manage Docker containers, images, volumes, and networks from Emacs.

Why: C-c D opens an interface to list, start, stop, remove containers without switching to a terminal.

docker-compose-mode

What: Syntax highlighting for docker-compose.yml files.

Why: YAML is error-prone. Proper highlighting catches indentation mistakes.

kubernetes / k8s-mode

What: kubernetes gives you a dashboard for your cluster. k8s-mode provides syntax support for k8s manifests.

Why: C-c K opens an overview of pods, deployments, services. Useful if you work with Kubernetes.

ansible / ansible-doc

What: Ansible playbook support. Auto-activates when editing YAML files that look like Ansible.

Why: Adds Ansible-specific syntax highlighting and lets you look up module documentation with ansible-doc.

terraform (via eglot)

What: Registers terraform-ls as the language server for Terraform files.

Why: Gives you completions, validation, and go-to-definition in .tf files. Requires terraform-ls installed on your system.

lang-rust.el — Rust Development

rust-mode

What: Major mode for Rust files — syntax highlighting, indentation, and basic editing.

Why: The foundation for Rust development. Every .rs file uses this mode.

Setting	Why
rust-format-on-save t	Runs rustfmt every time you save. Keeps your code consistently formatted.
eglot-ensure hook	Automatically starts rust-analyzer when you open a Rust file.
company-mode hook	Enables auto-completion in Rust buffers.

rust-analyzer (via eglot)

What: Not a package — it's an external program registered as the LSP server for Rust.

Why: Provides smart completions, inline type hints, error checking, go-to-definition, and refactoring. Install it separately (rustup component add rust-analyzer).

toml-mode

What: Syntax highlighting for .toml files.

Why: Cargo.toml is how you configure Rust projects. Proper highlighting helps catch mistakes.

lang-markdown.el — Markdown Editing

markdown-mode

What: Major mode for Markdown files with live preview, syntax highlighting, and structure navigation.

Why: Makes writing documentation much easier than editing raw text.

Setting	Why
markdown-fontify-code-blocks-natively t	Syntax-highlights code inside fenced blocks (e.g., Rust code in a README).
markdown-enable-wiki-links t	Recognizes [[wiki-style]] links.
markdown-make-gfm-checkboxes-buttons t	Makes - [x] checkboxes clickable.
markdown-header-scaling t	Renders headers in different sizes, like a browser.
markdown-command "pandoc -f gfm -t html5"	Uses Pandoc for preview/export. Requires pandoc installed.
gfm-mode for README.md	Uses GitHub-Flavored Markdown mode for README files.

markdown-toc

What: Auto-generates a table of contents from your headings.

Why: C-c C-t inserts or updates a TOC in your Markdown file. Keeps documentation navigable.

External Dependencies

These are not Emacs packages — you install them on your system.

Tool	Install	Used by
rust-analyzer	rustup component add rust-analyzer	eglot (Rust LSP)
pandoc	package manager (apt, brew, etc.)	markdown-mode preview/export
ripgrep	package manager	rg.el (project-wide search)
terraform-ls	package manager or manual	eglot (Terraform LSP)
shellcheck	package manager	Bash linting (if added later)
docker	package manager	docker.el
kubectl	package manager	kubernetes.el