core Documentation

1. Project Overview & Quickstart (doomemacs/core) Copy Chapter

Table of Contents Copy Section

• Introduction
• Features
• Prerequisites
• Install
• Roadmap
• Getting help
• Contribute

Introduction

It is a story as old as time. A stubborn, shell-dwelling, and melodramatic
vimmer—envious of the features of modern text editors—spirals into
despair before he succumbs to the dark side. This is his config.

Doom is a configuration framework for GNU Emacs tailored for Emacs bankruptcy
veterans who want less framework in their frameworks, a modicum of stability
(and reproducibility) from their package manager, and the performance of a hand
rolled config (or better). It can be a foundation for your own config or a
resource for Emacs enthusiasts to learn more about our favorite operating
system.

Its design is guided by these mantras:

• Gotta go fast. Startup and run-time performance are priorities. Doom goes
  beyond by modifying packages to be snappier and load lazier.
• Close to metal. There's less between you and vanilla Emacs by design.
  That's less to grok and less to work around when you tinker. Internals ought
  to be written as if reading them were part of Doom's UX, and it is!
• Opinionated, but not stubborn. Doom is about reasonable defaults and
  curated opinions, but use as little or as much of it as you like.
• Your system, your rules. You know better. At least, Doom hopes so! It
  won't automatically install system dependencies (and will force plugins not
  to either). Rely on doom doctor to tell you what's missing.
• Nix/Guix is a great idea! The Emacs ecosystem is temperamental. Things
  break and they break often. Disaster recovery should be a priority! Doom's
  package management should be declarative and your private config reproducible,
  and comes with a means to roll back releases and updates (still a WIP).

Check out the FAQ for answers to common questions about the project.

Features

• Minimalistic good looks inspired by modern editors.
• Curated and sane defaults for many packages, (major) OSes, and Emacs itself.
• A modular organizational structure for separating concerns in your config.
• A standard library designed to simplify your elisp bike shedding.
• A declarative package management system (powered by
  straight.el) with a command line interface. Install packages from anywhere,
  not just (M)ELPA, and pin them to any commit.
• Optional vim emulation powered by evil-mode, including ports of popular vim
  plugins like vim-sneak, vim-easymotion, vim-unimpaired and
  more!
• Opt-in LSP integration for many languages, using lsp-mode or eglot
• Support for many programming languages. Includes syntax highlighting,
  linters/checker integration, inline code evaluation, code completion (where
  possible), REPLs, documentation lookups, snippets, and more!
• Support for many tools, like docker, pass, ansible, terraform, and more.
• A Spacemacs-esque keybinding scheme, centered around leader
  and localleader prefix keys (SPC and SPCm for
  evil users, C-c and C-c l for vanilla users).
• A rule-based popup manager to control how temporary buffers
  are displayed (and disposed of).
• Per-file indentation style detection and editorconfig integration. Let
  someone else argue about tabs vs spaces.
• Project-management tools and framework-specific minor modes with their own
  snippets libraries.
• Project search (and replace) utilities, powered by ripgrep and ivy or
  helm.
• Isolated and persistent workspaces (also substitutes for vim tabs).
• Support for Chinese and Japanese input systems.
• Save a snapshot of your shell environment to a file for Emacs to load at
  startup. No more struggling to get Emacs to inherit your PATH, among other
  things.

Prerequisites

• Required:
  • GNU Emacs 27.1–30.2 (30.2 is recommended)
    • If only using Doom's core, 27.1+ is required.
    • If using Doom's modules (especially tree-sitter support), 29.1+ is
      required.
  • Git >= 2.23
  • ripgrep >= 11.0
• Optional, but recommended:
  • fd 7.3.0+ (used to improve file indexing performance)
  • GNU variants of find, ls, and tar (on MacOS and BSD *nix)
  • Symbola font (Emacs' fallback font for glyphs it can't display)

[!WARNING]
Avoid unstable and pre-release builds of Emacs. These end in .50, .60,
or .9X (e.g. 28.1.91). Doom should generally work on Emacs HEAD (the
maintainer dogfoods it), but support lags behind the bleeding edge by at least
a month or so.

[!IMPORTANT]
Doom is comprised of ~150 optional modules, some of which may have
additional dependencies. Visit their documentation or run bin/doom doctor to check for any that you may have missed.

Install

git clone --depth 1 https://github.com/doomemacs/core ~/.config/emacs
~/.config/emacs/bin/doom install

Then read our Getting Started guide to be walked through
installing, configuring and maintaining Doom Emacs.

It's a good idea to add ~/.config/emacs/bin to your PATH! Other bin/doom
commands you should know about:

• doom sync to synchronize your private config with Doom by installing missing
  packages, removing orphaned packages, and regenerating caches. Run this
  whenever you modify your private init.el or packages.el, or install/remove
  an Emacs package through your OS package manager (e.g. mu4e or agda).
• doom sync --env to include a snapshot of your shell environment that Doom
  will load at startup. This allows Emacs to inherit your PATH, among other
  things. This replaces
  exec-path-from-shell.
• doom upgrade to update Doom to the latest release & all installed packages.
• doom doctor to diagnose common issues with your system and config.

Roadmap

Doom is an active and ongoing project. To make that development more
transparent, its roadmap (and other concerns) are published across three github
project boards and a newsletter:

• Development Roadmap
• Packages under review:
  lists plugins we are watching and considering for inclusion, and what their
  status for inclusion is. Please consult this list before requesting new
  packages/features.

• Upstream bugs: lists
  issues that originate from elsewhere, and whether or not we have local
  workarounds or temporary fixes for them.
• Doom's newsletter (not finished) will contain changelogs in between
  releases.

Getting help

Emacs is no journey of a mere thousand miles. You will run into problems and
mysterious errors. When you do, here are some places you can look for help:

• Our documentation covers many use cases.
  • The Configuration section covers how to configure Doom and
    its packages.
  • The Package Management section covers how to install
    and disable packages.
  • This section explains the bin/doom script's most important
    commands.
  • This section lists some common configuration mistakes new
    users make, when migrating a config from another distro or their own.
  • This answer shows you how to add your own themes to your
    private config.
  • This answer shows you how to change the default font.
  • Your issue may be documented in the FAQ.
• With Emacs built-in help system documentation is a keystroke away:
  • For functions: SPC h f or C-h f
  • For variables: SPC h v or C-h v
  • For a keybind: SPC h k or C-h k
  • To search available keybinds: SPC h b b or C-h b b
• Run bin/doom doctor to detect common issues with your development
  environment and private config.
• Check out the FAQ or Community FAQs, in case your question
  has already been answered.
• Search Doom's issue tracker
  in case your issue was already reported.
• Hop on our Discord server; it's active and friendly! Keep an eye on
  the #announcements channel, where I announce breaking updates and releases.

Contribute

Doom is a labor of love and incurable madness, but I'm only one guy. Doom
wouldn't be where it is today without your help. I welcome contributions of any
kind!

• I :heart: pull requests and bug reports (see the Contributing
  Guidelines)!
• Don't hesitate to tell me my Elisp-fu
  sucks, but please
  tell me why.
• Hop on our Discord server and say hi! Help others, hang out or talk
  to me about Emacs, gamedev, programming, physics, pixel art, anime, gaming --
  anything you like. Nourish this lonely soul.
• If you'd like to support my work financially, buy me a drink through
  liberapay or paypal. My work contends with studies, adventures in indie
  gamedev and freelance work. Donations help me allocate more time to my Emacs
  and OSS capers.

2. Official Technical Reference & Guides (doomemacs/docs) Copy Chapter

docs.doomemacs.org

This repository houses the HTML build pipelines for Doom's documentation. It
scrapes the documentation from the recent release branches of doomemacs/core,
doomemacs/modules, and doomemacs/modules-contrib, and is published to
docs.doomemacs.org.

Prerequisites Copy Chapter

Compiling this project to HTML requires the following:

• Emacs >= 27.1
• Doom core >= 3.0.0
• dart-sass >= 1.89.2
• minify >= 2.23.1

This project contains a shell.nix that will initialize an environment for
building this project (except for Emacs). If Doom Core's bin/doom script is
present on your $PATH, that will be used instead deploying a project-local
copy.

Publishing Copy Chapter

[!IMPORTANT]
The doom publish command and the associated CI/CD that auto-publishes this
repo to docs.doomemacs.org are a work-in-progress and are not yet available,
so the instructions below will not work yet. This notice will be removed once
that changes.

This repository is automatically built and published to docs.doomemacs.org.
Here's how to build and preview the latest documentation manually:

git clone --depth 1 https://github.com/doomemacs/docs docs
cd docs
nix-shell
publish   # defined in shell.nix

python -m http.server 8000  # any http server will do
firefox 127.0.0.1:8000