Doom Emacs Documentation

If your issue isn’t particular to Doom, you’ll have better luck asking the larger Emacs community instead:

• r/emacs
• r/orgmode
• Emacs on IRC
• emacs.stackexchange.com
• Emacs mailing lists
• Emacs newsgroups
• emacs-china.org
• Emacs Quora

With the likes of VSCode, Atom, Sublime Text, IntelliJ, even Neovim clamoring for the top spot in developer mindshare, why consider a 50-some year old Lisp operating system from the stone age? Why embrace its anachronistic language and ecosystem, or struggle against its coiling-into-infinity learning curve when you could be productive on day 2 with just about any other modern editor?

There are many reasons, but it’s greatest asset is undeniably its:

• Extensibility. Emacs shines in the hands of an experienced user who knows exactly what they need from their tools (and is willing to build them). Certainly, most text editors boast some degree of “programmability”, but none of them hold a candle to:

  • How much of Emacs is configurable,
  • How low the barrier of entry into extending Emacs is,
  • How self-documenting Emacs is,

  Emacs Lisp isn’t a great language, all around, but it’s a great language for exploratory programming and rapid iteration. It gets you from “I want to do X” to “I’m doing X” in fewer steps than any other editor.

• Emacs’ second greatest asset is its versatility, which is owed to the fact that Emacs isn’t really a text editor, but a platform for plain text applications. You’ll find folks using Emacs for much more than software development:

  • Task planning
  • File management
  • Terminal emulation
  • Email client
  • Remote server tool
  • Git frontend
  • Web client/server
  • and more…

  Emacs can be thought of as a platform to integrate all these applications into one set of consistent keybinds and workflows – a Life IDE, if you will. – Tecosaur [source]

• Emacs’ ecosystem is home to some amazing plugins: there is no better git porcelain than Magit and no greater ecosystem for personal organization (notes, todo’s, agendas, etc) than Org. They’re so fantastic, folks have tried to port them to other editors with varying success. Still, you can’t beat the originals.
• Emacs Lisp may not be a particularly good Lisp, but it’s an excellent (and sane) language for rapid iteration and hacking on your editor.

Of course, there are other reasons; Emacs is FOSS, boasts wide and deep integration with a variety of tools and languages, and has a strong ecosystem of users and packages, but in the end, it is up to you to decide if any of these strengths apply to you.

The previous section established Emacs’ strengths and weaknesses, so where does Doom Emacs come in? Doom is a configuration for Emacs meant to address many of its issues, especially those concerning performance, but why exactly should someone use it?

• Its package manager. Stop micromanaging your plugins and fighting Emacs’ rolling-release package manager. Doom’s is declarative, non-rolling release, and (nominally) reproducible; which is unique on the Emacs starter-kit scene. Don’t let upstream issues surprise you. Roll back or re-pin packages when you don’t have the time to deal with issues. Wield precise control over your packages.

  It also integrates with command line workflows, so automate to your heart’s content.

• To save time. If you care about personalizing the software you use on a daily basis, even half as much as I do, then you need professional help, but you also know it is time consuming. Emacs out-of-the-box is a wasteland of archaic defaults, full of plugins rife with gotchas and oddities that may or may not be abandonware. It will be an uphill battle. Let Doom deal with all that noise to save yourself some time.

  Time you could otherwise spend attending your daughter’s dance recitals, that baseball game your son’s team almost won last Thursday, or answering the court summons to fight for custody of your kids.

• It’s a gentler introduction to Emacs. Emacs is hard™. Doom files down its rougher edges.
• Emacs is slow. Doom can’t promise to resolve all Emacs’ performance issues, but it certainly helps, and it will always be a priority.
• It can be a barebones framework. Disable all its modules and you get many of Doom’s perks without its opinions; why go vanilla when you can have vanilla + better defaults + a stronger elisp toolchain from the get go?

What it can do for you

• Better defaults.
• Faster baseline.
• Pre-configured modules.

• Use it with out-of-the-box defaults.
• As a reference.
• As a barebones foundation for your own config.

The Meta key

…

There are two ways to load a theme. Both assume the theme is installed and available. You either set doom-theme or manually load a theme with the load-theme function:

;;; add to $DOOMDIR/config.el
(setq doom-theme 'doom-tomorrow-night)
;; or
(load-theme 'doom-tomorrow-night t)

The only difference between the two is when the theme is loaded. Doom loads doom-theme later in the startup process, while calling load-theme will load the theme immediately. If you don’t know which to use, set doom-theme.

Doom exposes five (optional) variables for controlling fonts in Doom, they are:

• doom-font
• doom-variable-pitch-font
• doom-serif-font
• doom-unicode-font (the fallback font for unicode symbols that your default font doesn’t support)
• doom-big-font (used for doom-big-font-mode)

They all accept either a font-spec, font string ("Input Mono-12"), or xlfd font string.

e.g.

;;; Add to $DOOMDIR/config.el
(setq doom-font (font-spec :family "Input Mono Narrow" :size 12 :weight 'semi-light)
      doom-variable-pitch-font (font-spec :family "Fira Sans") ; inherits `doom-font''s :size
      doom-unicode-font (font-spec :family "Input Mono Narrow" :size 12)
      doom-big-font (font-spec :family "Fira Mono" :size 19))

Doom supports LSP, but it is not enabled by default. To enable it, you must:

1. Enable the :tools lsp module,
2. Enable the +lsp flag for the appropriate modules you want LSP support for (e.g. :lang python +lsp or :lang rust +lsp),
3. Install one of the supported LSP servers through your package manager or other means. That module’s documentation will tell you how to install them, otherwise consult the server table on the lsp-mode project page.
4. Run $ doom sync on the command line and restart Emacs.

Some language modules may lack LSP support (either because it hasn’t been implemented yet or I’m not aware of it yet – let us know!). To enable LSP for these languages, add this to $DOOMDIR/config.el:

(add-hook 'MAJOR-MODE-local-vars-hook #'lsp!)
;; Replace MAJOR-MODE. e.g. `lisp-mode-local-vars-hook'

Short answer: You can, but you shouldn’t.

Long answer: Restarting Emacs is always your safest bet, but Doom provides a few tools for experienced Emacs users to skirt around it (most of the time):

• Evaluate your changes on-the-fly with M-x +eval/region (bound to the gr operator for evil users) or M-x eval-last-sexp (bound to C-x C-e). Changes take effect immediately.

• On-the-fly evaluation won’t work for all changes. e.g. Changing your doom! block in =$DOOMDIR/init.el.

  But rather than running $ doom sync and restarting Emacs, Doom provides M-x doom/reload for your convenience (bound to <help> r r). This runs $ doom sync, restarts the Doom initialization process and re-evaluates your personal config. However, this won’t clear pre-existing state; Doom won’t unload modules/packages that have already been loaded and it can’t anticipate complications arising from your private config.

• You can quickly restart Emacs and restore the last session with M-x doom/restart-and-restore (bound to <leader> q r).

To paraphrase (and expand upon) a reddit answer to this question by @gilbertw1:

• Doom is lighter than Spacemacs. Doom starts up faster and is better optimized, but Spacemacs has more features.
• Doom is thinner than Spacemacs. There are fewer abstractions between you and vanilla Emacs, and what abstractions do exist are thin by design. This means there’s less to understand and it’s easier to hack.
• Doom is much more opinionated than Spacemacs. Doom does not strive to be a one-size-fits-all, beginner-friendly solution, nor is it configured by consensus. It is [mostly] the work of one developer and caters to his vim-slanted tastes. Doom’s defaults enforce very particular (albeit optional) workflows.
• Doom lacks manpower. Bugs stick around longer, documentation is lighter and development is at the mercy of it’s maintainer’s schedule, health and whims.
• Doom is not beginner friendly. Doom lacks a large community to constantly improve and produce tutorials/guides for it. Spacemacs is more likely to work right out of the box. Doom also holds your hand less. A little elisp, shell and git-fu will go a long way to ease you into Doom.
• Doom is managed through it’s command line interface. The bin/doom script allows you to script package management, manage your config, or utilize elisp functionality externally, like org tangling or batch processing.
• Doom’s package manager is declarative and rolling release is opt-in. Doom takes a little after nix, striving for as much config reproducibility as Emacs (and git) will permit. Spacemacs uses package.el, which is only rolling release.

1. A release-YY.0M branch is created.

Welcome to our documentation about the documentation. Here I’ll walk you through how best to navigate our docs and the conventions we use for them – and in such painstaking detail that you’ll memorize it all simply to avoid the horror of revisiting it. You’re welcome.

develop

Our development (i.e. nightly) branch. Development happens rapidly here; often seeing ~10 commits a day.

main

Our stable branch. develop is merged into main once all tests are passed.

Doom has adopted its own spin-off of conventional commits:

TYPE[!][(SCOPE[,SCOPE...])]: SUMMARY

[BODY]

[FOOTER]

For example:

• …
• …
• …

As of 074b9eb0, use $ doom ci lint-commits HEAD~1 to locally lint your last commit against these rules.

…

…

…

Watch your missed deadlines in real time

This module adds a calendar view for Emacs, with org and google calendar sync support.

A media player for music no one’s heard of

This module enables Emacs to be used as a music player. It uses mpd as a backend server and mpc to update your music database.

*leave* Emacs!? You must be joking

This module adds system-wide popup Emacs windows for quick edits.

How neckbeards socialize

This module turns Emacs into an IRC client, capable of OS notifications.

Flags: +org

An RSS reader that Google can’t shut down

Read RSS feeds in the comfort of Emacs.

Be superficial in plain text

Enjoy twitter from emacs.

• View various timelines side by side, e.g. user’s timeline, home, etc.
• Post new tweets
• Send direct messages
• Retweet
• Follow and un-follow users
• Favorite tweets

Tasing grammar mistake every you make

This module adds grammar checking to Emacs to aid your writing by combining lang-tool and writegood-mode.

Flags: +aspell +enchant +everywhere +flyspell +hunspell

Tasing you for misspelling mispelling

This modules provides spellchecking powered by aspell, hunspell or enchant.

Spellcheck is automatically loaded in many text-mode derivatives, which includes org-mode, markdown-mode, the Git Commit buffer (from magit), mu4e-compose-mode, and others.

• Spell checking and correction using aspell, hunspell or enchant.
• Ignores source code inside org or markdown files.
• Lazily spellchecking recent changes only when idle.
• Choosing suggestions using completion interfaces (ivy or helm).

Flags: +childframe

Tasing you for every semicolon you forget

This module provides syntax checking and error highlighting, powered by flycheck.

Flags: +childframe +tng

The ultimate code completion backend

This module provides code completion, powered by company-mode. It is required for code completion in many of Doom’s :lang modules.

Flags: +childframe +fuzzy +icons

the *other* search engine for love and life

This module provides Helm integration for a variety of Emacs commands, as well as a unified interface for project search and replace, powered by ripgrep.

A foil for other search engines

Interactive DO things. The completion engine that is mostly built-into Emacs.

Flags: +childframe +fuzzy +icons +prescient

Yesterday's lightest search engine

This module provides Ivy integration for a variety of Emacs commands, as well as a unified interface for project search and replace, powered by ripgrep.

I prefer ivy over ido for its flexibility. I prefer ivy over helm because it’s lighter, simpler and faster in many cases.

Flags: +icons

The search engine for life and love

This module enhances the Emacs search and completion experience, and also provides a united interface for project search and replace, powered by ripgrep.

It does this with several modular packages focused on enhancing the built-in completing-read interface, rather than replacing it with a parallel ecosystem like ivy and helm do. The primary packages are:

• Vertico, which provides the vertical completion user interface
• Consult, which provides a suite of useful commands using completing-read
• Embark, which provides a set of minibuffer actions
• Marginalia, which provides annotations to completion candidates
• Orderless, which provides better filtering methods

Reasonable defaults for reasonable people

This module provides a set of reasonable defaults, including:

• A Spacemacs-esque keybinding scheme
• Extra Ex commands for evil-mode users
• A configuration for (almost) universally repeating searches with ; and ,

Disguise your config as documentation

This module enables support for a literate config.

A literate config consists of a $DOOMDIR/config.org. All src blocks within are tangled $DOOMDIR/config.el, by default, when $ doom sync is executed.

Flags: +everywhere

Come to the dark side, we have cookies

This holy module brings the vim experience to Emacs.

Fill the void in your empty files

This module adds file templates for blank files, powered by yasnippet.

What you can't see won't hurt you

This module marries hideshow, vimish-fold, and outline-minor-mode to bring you marker, indent and syntax-based code folding for as many languages as possible.

Flags: +onsave

Standardize your ugly code

This module integrates code formatters into Emacs. Here are some of the formatters that it currently supports:

asmfmt, black, brittany, cabal-fmt, clang-format, cmake-format, dartfmt, dfmt, dhall format, dockfmt, elm-format, emacs, fish_indent, fprettify, gleam format, gofmt, iStyle, jsonnetfmt, ktlint, latexindent, ledger-mode, lua-fmt, mix format, nixfmt, node-cljfmt, ocp-indent, perltidy, prettier, purty, rufo, rustfmt, scalafmt, script shfmt, snakefmt, sqlformat, styler, swiftformat, tidy

IDDQD

Adds god-mode support to Doom Emacs, allowing for entering commands without modifier keys, similar to Vim’s modality, separating command mode and insert mode.

Vim for lisp, for people who don't like vim

This module adds lispy key functionality in Lisp languages, including:

• Common Lisp
• Emacs Lisp
• Scheme
• Racket
• Hy
• LFE
• Clojure
• Fennel

If :editor evil is enabled, lispyville would also be activated for every mode where lispy is active

The default key themes that are set are as follows:

'((operators normal)
  c-w
  (prettify insert)
  (atom-movement normal visual)
  slurp/barf-lispy
  additional
  additional-insert)

To change the key themes set lispyville-key-theme. Think of lispyville-key-theme as the equivalent of parinfer-extensions. See lispyville’s README for more info on the specific keybindings of each key theme (starting here).

Make all your mistakes at the same time

This module adds a multiple cursors implementation to Emacs (two, if you use evil) that loosely take after multi-cursors in modern editors, like Atom or Sublime Text.

Flags: +manual

Text object editing for the innocent

This modules adds objed, a global minor-mode for navigating and manipulating text objects. It combines the ideas of versor-mode and other editors like Vim or Kakoune and tries to align them with regular Emacs conventions.

This module is incompatible with the :editor evil. Enabling them both will cause errors.

See the objed project README for information on keybinds and usage.

For lispers that like Python more (i.e. nobody)

Parinfer is a minor mode that aids the writing of Lisp code. It automatically infers parenthesis matching and indentation alignment, keeping your code balanced and beautiful.

The original parinfer-mode has been deprecated and superceded by parinfer-rust-mode, which has much better performance.

The only back'n'forth nerds will ever know

This module adds text rotation; the ability to cycle through keywords or text patterns at point. e.g. Swapping true and false.

My elves type so I don't have to

This module adds snippet expansions to Emacs, powered by yasnippet.

Soft-wrapping with language-aware indent

This module adds a minor-mode +word-wrap-mode, which intelligently wraps long lines in the buffer without modifying the buffer content.

Flags: +icons +ranger

Making dired pretty [functional]

This module provides reasonable defaults and augmentations for dired.

Shocking keyword-based electric-indent

This module augments the built-in electric package with keyword-based indentation (as opposed to character-based).

Flags: +icons

Edit me like your French buffers

This module augments the built-in ibuffer package.

• Adds project-based grouping of buffers
• Support for file-type icons
• Uses human-readable file-size

(No description)

Flags: +tree

Persistent, smarter undo for your inevitable mistakes

This module augments Emacs’ built-in undo system to be more intuitive and to persist across Emacs sessions.

Be the difference you want to see in the fringe

This module augments Emacs builtin version control support and provides better integration with git.

Flags: +gmail +org

The great filter Hanson hadn't anticipated

This module makes Emacs an email client, using mu4e.

• Tidied mu4e headers view, with flags from all-the-icons.
• Consistent coloring of reply depths (across compose and gnus modes).
• Prettified mu4e:main view.
• Cooperative locking of the mu process. Another Emacs instance may request access, or grab the lock when it’s available.
• org-msg integration with +org, which can be toggled per-message, with revamped style and an accent color.
• Gmail integrations with the +gmail flag.
• Email notifications with mu4e-alert, and (on Linux) a customised notification style.

I want to live in Emacs, but as we all know, living is incomplete without email. So I prayed to the text editor gods and they (I) answered. Emacs+evil’s editing combined with org-mode for writing emails? Yes please.

It uses mu4e to read my email, but depends on offlineimap (to sync my email via IMAP) and mu (to index my mail into a format mu4e can understand).

Flags: +afew +org

Closest Emacs will ever be to multi-threaded

This module turns Emacs into an email client using notmuch.

Flags: +gmail

To boldly go where no mail has gone before

This module has no description. Write one?

Spend your 3 hours a week in Emacs

This module adds support for traditional Chinese script by introducing two input methods: Pinyin and Wubi.

Ah, a man of culture

This module adds support for Japanese script.

Flags: +azerty +bepo

auie,ctsrnm is the superior home row

This module provides barebones support for using Doom with non-qwerty keywoard layouts.

Types of types of types of types...

This module adds support for the agda programming language. The Emacs support exists directly in the agda repository but not in melpa.

Flags: +lsp

Mind the GAAP

This module adds support for Beancount to Emacs. Beancount, like ledger, lets you manage your money in plain text.

Flags: +lsp

C > C++ == 1

This module adds support for the C-family of languages: C, C++, and Objective-C.

• Code completion (company-irony)
• eldoc support (irony-eldoc)
• Syntax-checking (flycheck-irony)
• Code navigation (rtags)
• File Templates (c-mode, c++-mode)
• Snippets (cc-mode, c-mode, c++-mode)
• Several improvements to C++11 indentation and syntax highlighting.

Flags: +lsp

Java with a lisp

This module adds support for the Clojure(Script) language.

• Interactive development environment (cider): REPL, compilation, debugging, running tests, definitions & documentation lookup, code completion, and much more
• Refactoring (clj-refactor)
• Linting (clj-kondo), requires :checkers syntax
• LSP support (clojure-lsp)

If you've seen one lisp, you've seen them all

This module provides support for Common Lisp and the Sly development environment. Common Lisp is not a single language but a specification, with many competing compiler implementations. By default, Steel Bank Common Lisp (SBCL) is assumed to be installed, but this can be configured.

Common Lisp benefits from a mature specification and rich standard library. Thanks to its powerful REPL and debugger, it boasts an “interactive programming” style often unseen in other languages. Compiled Common Lisp programs are trusted to run unmodified for a long time.

Proofs as programs

This module adds coq support, powered by Proof General.

• Code completion (company-coq)
• Snippets

Ruby at the speed of c

This modules adds crystal support.

• Syntax-checking (flycheck)
• REPL (inf-crystal)

Flags: +dotnet +lsp +unity

Unity, .NET, and mono shenanigans

This module adds C# support to Emacs, powered by Omnisharp (directly or through LSP).

Flags: +flutter +lsp

Paint ui and not much else

Dart is a client-optimized language by Google for fast apps on any platform. It is fast and optimized for UI, famous for the Flutter framework, also made by Google. Both Flutter and Dart are free and open-source.

This module wraps dart-mode, with LSP features like code completion for .dart files, syntax highlighting, debugging, closing labels, etc.

A dumping ground for data formats

This module adds Emacs support for CSV and XML files.

Config as code

This module adds Dhall language support to Emacs.

Dhall is a programmable configuration language that you can think of as: JSON + functions + types + imports.

Flags: +lsp

Erlang done right

This module provides support for Elixir programming language via alchemist or elixir-ls.

Flags: +lsp

Care for a cup of TEA?

This module adds Elm support to Doom Emacs.

A parsel-tongue for the oldest serpent

This module extends support for Emacs Lisp in Doom Emacs.

• Macro expansion
• Go-to-definitions or references functionality
• Syntax highlighting for defined and quoted symbols
• Replaces the built-in help with the more powerful helpful
• Adds function example uses to documentation

Flags: +lsp

An elegant language for a more civilized age

This module provides support Erlang programming language. Support for the sourcer language server is optional.

Includes:

• Code completion (+lsp, :completion company, & :completion ivy)
• Syntax checking (:checkers syntax)

Flags: +stan

73.6% of all statistics are made up

This module adds support for various statistics languages, including R, S-Plus, SAS, Julia and Stata.

...

This module adds support to the factor programming language and its associated fuel emacs plugin.

DSP, but you get to keep your soul

Add support to Faust language inside emacs.

• Faust code syntax highlighting and indentation
• Project-based (inter-linked Faust files)
• Build/compile with output window
• Graphic diagrams generation and visualization in the (default) browser
• Browse generated C++ code inside Emacs
• Inter-linked files/buffers :
  • From “component” to Faust file
  • From “include” to Faust library file
• From error to line number
• From function name to online documentation
• Fully configurable (build type/target/architecture/toolkit, keyboard shortcuts, etc.)
• Automatic keyword completion (if Auto-Complete is installed)
• Automatic objets (functions, operators, etc.) template insertion with default sensible values (if :editor snippets is enabled)
• Modeline indicator of the state of the code

Flags: +lsp

ML stands for Microsoft's Language

This module adds F# support to Doom Emacs.

(Dependent) types and (monadic) effects and Z3

This module adds F* support, powered by fstar-mode.el.

• Syntax highlighting
• Interactively process F* files one definition at a time
• Query the running F* process to look up definitions, documentation, and theorems

Flags: +lsp

the language you waited for

This module adds support for GDScript, the scripting language of the Godot game engine, to Doom Emacs, powered by gdscript-mode.

Flags: +lsp

The hipster dialect

This module adds Go support, with optional (but recommended) LSP support via gopls.

• Code completion (gocode)
• Documentation lookup (godoc)
• Eldoc support (go-eldoc)
• REPL (gore)
• Syntax-checking (flycheck)
• Auto-formatting on save (gofmt) (requires :editor format +onsave)
• Code navigation & refactoring (go-guru)
• File templates
• Snippets
• Generate testing code (go-gen-test)
• Code checking (flycheck-golangci-lint)

Flags: +lsp

A language that's lazier than I am

This module adds Haskell support to Doom Emacs.

(No description)

A language you can depend on

This module adds rudimentary Idris support to Doom Emacs.

Flags: +lsp +meghanada

The poster child for carpal tunnel syndrome

This module adds Java support to Doom Emacs, including android-mode and groovy-mode.

Flags: +lsp

all(hope(abandon(ye(who(enter(here))))))

This module adds JavaScript and TypeScript support.

• Code completion (tide)
• REPL support (nodejs-repl)
• Refactoring commands (js2-refactor)
• Syntax checking (flycheck)
• Browser code injection with skewer-mode
• Coffeescript & JSX support
• Jump-to-definitions and references support (xref)

Flags: +lsp

At least it ain't XML

This module adds JSON support to Doom Emacs.

Flags: +lsp

A better, faster MATLAB

This module adds support for the Julia language to Doom Emacs.

• Syntax highlighting and latex symbols from julia-mode
• REPL integration from julia-repl
• Code completion and syntax checking, requires :tools lsp and +lsp

Flags: +lsp

A Java(Script) that doesn't depress you

This module adds Kotlin support to Doom Emacs.

Flags: +cdlatex +fold +latexmk +lsp

Writing papers in Emacs has never been so fun

Provide a helping hand when working with LaTeX documents.

• Sane defaults
• Fontification of many popular commands
• Pretty indentation of wrapped lines using the adaptive-wrap package
• Spell checking with flycheck
• Change PDF viewer to Okular or latex-preview-pane
• Bibtex editor
• Autocompletion using company-mode
• Compile your .tex code only once using LatexMk

For folks with too much to prove

This module adds support for the Lean programming language to Doom Emacs.

Be audit you can be

This module adds support for ledger files. Ledger is a command line double-entry accounting system that works with simple text files holding transactions in the following format:

2015/10/12 Exxon
    Expenses:Auto:Gas                         $10.00
    Liabilities:MasterCard                   $-10.00

This modules enables the following features:

• Syntax and indentation support for ledger files
• Add, edit, and delete transactions
• Generate reports
• Schedule transactions
• Sort transactions
• Display statistics about transactions
• Display balance up to a point

Flags: +fennel +lsp +moonscript

One-based indices? one-based indices

This module adds Lua support to Doom Emacs.

• REPL
• Love2D specific functions
• Moonscript support
• Fennel support

Flags: +grip

Write docs for people to ignore

This module provides Markdown support for Emacs.

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML. See the Syntax page for details pertaining to Markdown’s formatting syntax. You can try it out, right now, using the online Dingus.

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email. – John Gruber

Python + lisp at the speed of C

This module adds Nim support to Doom Emacs.

• Code completion (nimsuggest + company)
• Syntax checking (nimsuggest + flycheck)
• Org babel support (ob-nim)

I hereby declare "nix geht mehr!"

This module adds support for the Nix language to Doom Emacs, along with tools for managing Nix(OS).

Including:

• Syntax highlighting
• Completion through company and/or helm
• Nix option lookup
• Formatting (nixfmt)

Flags: +lsp

An objective camel

This module adds OCaml support to Doom Emacs, powered by tuareg-mode.

• Code completion, documentation look-up, code navigation and refactoring (merlin)
• Type, documentation and function argument display on idle (merlin-eldoc)
• REPL (utop)
• Syntax-checking (merlin with flycheck-ocaml)
• Auto-indentation (ocp-indent)
• Code formatting (ocamlformat)
• Dune file format (dune)

Flags: +brain +dragndrop +gnuplot +hugo +ipython +journal +jupyter +noter +pandoc +pomodoro +present +pretty +roam +roam2

Organize your plain life in plain text

This module adds org-mode support to Doom Emacs, along with a number of adjustments, extensions and reasonable defaults to make it more performant and intuitive out of the box:

• A custom, centralized attachment system that stores files in one place, rather than in the same directory as the input file(s) (only applies to attachments from files in/under org-directory).
• Executable code blocks with support for a variety of languages and tools (depending on what :lang modules are enabled).
• Supports an external org-capture workflow through the bin/org-capture shell script and +org-capture/open-frame.
• A configuration for using org-mode for slide-show presentations or exporting org files to reveal.js slideshows.
• Drag-and-drop support for images (with inline preview) and media files (drops a file icon and a short link) (requires +dragndrop flag).
• Integration with pandoc, ipython, jupyter, reveal.js, beamer, and others (requires flags).
• Export-to-clipboard functionality, for copying text into formatted html, markdown or rich text to the clipboard (see +org/export-to-clipboard and +org/export-to-clipboard-as-rich-text).

Org is a system for writing plain text notes with syntax highlighting, code execution, task scheduling, agenda management, and many more. The whole idea is that you can write notes and mix them with references to things like articles, images, and example code combined with the output of that code after it is executed.

https://www.mfoot.com/blog/2015/11/22/literate-emacs-configuration-with-org-mode/

Flags: +hack +lsp

Perl's insecure younger brother

This module adds support for PHP 5.3+ (including PHP7) to Doom Emacs.

• ctags-based code completion (company-php and phpctags)
• eldoc support (ac-php and php-extras)
• REPL (php-boris)
• Code refactoring commands (php-refactor-mode)
• Unit-test commands (phpunit)
• Support for laravel and composer projects (with project-specific snippets)
• File templates
• Snippets

PHP was the first programming language I got paid to code in, back in the Cretaceous period (2003). My sincerest apologies go out to all the programmers who inherited my earliest PHP work. I know you’re out there, writhing in your straitjackets.

Save a programmer today. Stop a friend from choosing PHP as their first language.

Diagrams to confuse people more

This module adds plantuml support to Emacs; allowing you to generate diagrams from plain text.

Flags: +lsp

Javascript, but functional

This module adds Purescript support to Doom Emacs.

Flags: +conda +cython +lsp +poetry +pyenv +pyright

Beautiful is better than ugly

This module adds Python support to Doom Emacs.

• Syntax checking (flycheck)
• Snippets
• Run tests (nose, pytest)
• Auto-format (with black, requires :editor format)
• LSP integration (mspyls, pyls, or pyright)

The cutest GUI framework ever

This module provides language functionality for Qt specific files.

• Syntax highlighting for qml files
• Syntax highlighting for .pro and .pri files used by qmake

Flags: +lsp +xp

The DSL for DSLs

This module adds support for the Racket programming language to Doom Emacs.

The artist formerly known as perl6

This module adds support for the Raku programming language to Doom Emacs.

Emacs as a REST client

This module turns Emacs into a REST client.

• Code-completion (company-restclient)
• Code evaluation
• Imenu support for restclient-mode
• org-mode: babel support (ob-restclient)

restclient-mode is tremendously useful for automated or quick testing REST APIs. My workflow is to open an org-mode buffer, create a restclient source block and hack away. restclient-mode and company-restclient power this arcane wizardry.

ReST in peace

This module adds ReStructured Text support to Doom Emacs.

Flags: +chruby +lsp +rails +rbenv +rvm

1.step {|i| p "Ruby is #{i.even? ? 'love' : 'life'}"}

This module add Ruby and optional Ruby on Rails support to Emacs.

• Code completion (robe)
• Syntax checking (flycheck)
• Jump-to-definitions (robe)
• Bundler
• Rubocop integration (flycheck)

Flags: +lsp

Fe2O3.unwrap().unwrap().unwrap().unwrap()

This module adds support for the Rust language and integration for its tools, e.g. cargo.

• Code completion (racer or an LSP server)
• Syntax checking (flycheck)
• LSP support (for rust-analyzer and rls) (rustic)
• Snippets

Flags: +lsp

Java, but good

This module adds scala and sbt support to Doom Emacs.

Through the power of Metals (LSP) this module offers:

• Goto Definition
• Completions
• Hover
• Paremeter Hints
• Find References
• Run/Debug
• Find Implementations
• Rename Symbol
• Code Actions
• Document Symbols
• Formatting
• Folding
• Organize Imports

Flags: +chez +chibi +chicken +gambit +gauche +guile +kawa +mit +racket

A fully conniving family of lisps

This module provides support for the Scheme family of Lisp languages, powered by geiser.

Flags: +fish +lsp +powershell

She sells {ba,z,fi}sh shells on the C xor

This module adds support for shell scripting languages (including Powershell and Fish script) to Doom Emacs.

• Code completion (company-shell)
• Syntax Checking (flycheck)

...

THis module adds SML (Standard ML) programming language support to Doom Emacs.

Do you need a blockchain? No.

This module adds Solidity support to Doom Emacs.

• Syntax-checking (flycheck)
• Code completion (company-solidity)
• Gas estimation (C-c C-g)

Flags: +lsp

We asked for emoji variables?

This module adds support for the Swift programming language to Doom Emacs.

Earth and Moon in alignment for performance.

\(No description yet\)

The tubes

This module adds support for various web languages, including HTML5, CSS, SASS/SCSS, Pug/Jade/Slim, and HAML, as well as various web frameworks, like ReactJS, Wordpress, Jekyll, Phaser, AngularJS, Djano, and more.

Flags: +lsp

JSON, but readable

This module provides support for the YAML file format to Doom Emacs.

Flags: +lsp

C, but simpler

This module adds Zig support, with optional (but recommended) LSP support via zls.

• Syntax highlighting
• Syntax-checking (flycheck)
• Code completion and LSP integration (zls)

Compatibility for our favorite walled garden

This module provides extra functionality for macOS.

Flags: +osc

Make TTY Emacs suck less

This module configures Emacs for use in the terminal, by providing:

• System clipboard integration (through an external clipboard program or OSC-52 escape codes in supported terminals).
• Cursor-shape changing across evil states (requires a terminal that supports it).
• Mouse support in the terminal.

The elisp shell that works everywhere

This module provides additional features for the built-in Emacs Shell

The Emacs Shell or eshell is a shell-like command interpreter implemented in Emacs Lisp. It is an alternative to traditional shells such as bash, zsh, fish, etc. that is built into Emacs and entirely cross-platform.

A REPL for your shell

Provides a REPL for your shell.

shell is more REPL than terminal emulator. You can edit your command line like you would any ordinary text in Emacs – something you can’t do in term (without term-line-mode, which can be unstable) or vterm.

Due to shell’s simplicity, you’re less likely to encounter edge cases (e.g. against your shell config), but it’s also the least capable. TUI programs like htop or vim won’t work in shell directly, but will be launched in a term buffer – which handles them reasonably well.

It's terminal

(No description)

As good as terminal emulation gets in Emacs

This module provides a terminal emulator powered by libvterm. It is still in alpha and requires a component be compiled (vterm-module.so).

vterm is as good as terminal emulation gets in Emacs (at the time of writing) and the most performant, as it is implemented in C. However, it requires extra steps to set up:

• Emacs must be built with dynamic modules support,
• and vterm-module.so must be compiled, which depends on libvterm, cmake, and libtool-bin.

vterm will try to automatically build vterm-module.so when you first open it, but this will fail on Windows, NixOS and Guix out of the box. Install instructions for nix/guix can be found in the :term vterm module’s documentation. There is no way to install vterm on Windows that I’m aware of (but perhaps with WSL?).

Allow silly people to focus on silly things

(No description)

(No description)

Flags: +lsp

Step through code to help you add bugs

Introduces a code debugger to Emacs, powered by realgud or dap-mode (LSP).

This document will help you to configure dap-mode Native Debug(GDB/LLDB) as there is still not enough documentation for it.

Save (or destroy) the environment at your leisure

This module integrates direnv into Emacs.

direnv is an environment switcher for the shell. It knows how to hook into bash, zsh, tcsh, fish shell and elvish to load or unload environment variables depending on the current directory. This allows project-specific environment variables without cluttering the ~/.profile file.

Before each prompt, direnv checks for the existence of a “.envrc” file in the current and parent directories. If the file exists (and is authorized), it is loaded into a bash sub-shell and all exported variables are then captured by direnv and then made available to the current shell.

Flags: +lsp

Yo dawg, I heard you like OSes, so I…

This module allows you to manipulate Docker images, containers, and more from Emacs.

Provides a major dockerfile-mode to edit Dockerfiles. Additional convenience functions allow images to be built easily.

docker-tramp offers TRAMP support for Docker containers.

Someone else can argue about tabs and spaces

This module integrates EditorConfig into Emacs, allowing users to dictate code style on a per-project basis with an .editorconfig file (formal specification).

Tame Jupyter notebooks with emacs

Adds Jupyter notebook integration into Emacs.

Flags: +overlay

Run code, run (also, repls)

This modules adds inline code evaluation support to Emacs and a universal interface for opening and interacting with REPLs.

A pastebin for Githubsters

Adds the ability to manage, pull from, or push to your Gists from within Emacs.

Flags: +dictionary +docsets +offline

Navigate your labyrinthine code and docs

This module adds code navigation and documentation lookup tools to help you quickly look up definitions, references, documentation, dictionary definitions or synonyms.

• Jump-to-definition and find-references implementations that just work.
• Powerful xref integration for languages that support it.
• Search online providers like devdocs.io, stackoverflow, google, duckduckgo, or youtube (duckduckgo and google have live suggestions).
• Integration with Dash.app docsets.
• Support for online (and offline) dictionaries and thesauruses.

Flags: +eglot +peek

M-x vscode

This module integrates language servers into Doom Emacs. They provide features you’d expect from IDEs, like code completion, realtime linting, language-aware imenu/xref integration, jump-to-definition/references support, and more.

As of this writing, this is the state of LSP support in Doom Emacs:

Flags: +forge

Wield git like a wizard

This module provides Magit, an interface to the Git version control system.

The discount build system

This module adds commands for executing Makefile targets.

Flags: +auth

A password manager for nerds

This module provides an Emacs interface to Pass.

Emacs, your next PDF reader

This module improves support for reading and interacting with PDF files in Emacs.

It uses pdf-tools, which is a replacement for the built-in doc-view-mode for PDF files. The key difference being pages are not pre-rendered, but instead rendered on-demand and stored in memory; a much faster approach, especially for larger PDFs.

Displaying PDF files is just one function of pdf-tools. See its project website for details and videos.

No sweatshop is complete without child processes

This module provides an interface for managing external services from within Emacs.

Creating color strings

Highlights color hex values and names with the color itself, and provides tools to easily modify color values or formats.

Taskrunner for all your projects

This module integrates taskrunner into Doom Emacs, which scraps runnable tasks from build systems like make, gradle, npm and the like.

Infrastructure as code

This module adds support for working with Terraform files within Emacs. This includes syntax highlighting, intelligent code completion, and the ability to run Terraform commands directly from Emacs.

From one multiplexer to another

This module provides an API for talking to Tmux sessions.

Map local directories to remotes via ssh/ftp

Uses ssh-deploy to map a local folder to a remote one.

From the ssh-deploy README:

The ssh-deploy plug-in for Emacs makes it possible to effortlessly deploy local files and directories to remote hosts via Tramp (including but not limited to SSH, SFTP, FTP). It tries to provide functions that can be easily used by custom scripts.

The idea for this plug-in was to mimic the behavior of PhpStorm deployment functionality.

Notational velocity for Emacs

Deft is a major mode for creating, browsing, and filtering notes written in plain text formats, such as org-mode, markdown, and LaTeX. It enables you to quickly jot down thoughts and easily retrieve them later.

Make Doom fabulous again

This module gives Doom its signature look: powered by the doom-one theme (loosely inspired by Atom’s One Dark theme) and solaire-mode. Includes:

• A custom folded-region indicator for hideshow.
• “Thin bar” fringe bitmaps for git-gutter-fringe.
• File-visiting buffers are slightly brighter (thanks to solaire-mode).

Welcome to your doom

This module adds a minimalistic, Atom-inspired dashboard to Emacs.

Besides eye candy, the dashboard serves two other purposes:

1. To improve Doom’s startup times (the dashboard is lighter than the scratch buffer in many cases).

2. And to preserve the “last open directory” you were in. Occasionally, I kill the last buffer in my project and I end up who-knows-where (in the working directory of another buffer/project). It can take some work to find my way back to where I was. Not with the Dashboard.

   Since the dashboard cannot be killed, and it remembers the working directory of the last open buffer, M-x find-file will work from the directory I expect.

One does not simply quit Emacs

A silly module that throws cute confirmation prompts at you when you exit Emacs, like DOOM (the game) did. Some quotes are from the classic games, others are random, nerdy references that no decent human being has any business recognizing.

Flags: +ascii +github +unicode

💩

This module gives Emacs the ability to display and insert emojis (ASCII, Github style, or unicode styles), as well as convert certain text patterns (e.g. :smile:) into emojis.

TODO FIXME NOTE DEPRECATED HACK REVIEW

This module adds syntax highlighting for various tags in code comments, such as TODO, FIXME, and NOTE, among others.

Discount modality for mythological beast hunters

This module adds hydra to Doom Emacs, as well as a few custom built hydras to start with:

• A hydra to control windows +hydra/window-nav/body.
• A hydra to control text zoom level +hydra/text-zoom/body.

Line up them indent columns

\(No description yet\)

Flags: +extra

Distract folks from your code

This module enables ligatures and arbitrary symbol substitutions with mac-auto-operator-composition-mode (on supported macOS systems) or composition tables (harfbuzz on Emacs 28), falling back on prettify-symbols-mode otherwise.

A map for lost programmers

This module displays a minimap of the buffer in a sidebar, similar to the feature found in many other editors.

Flags: +light

Snazzy, Atom-inspired modeline, plus API

This module provides an Atom-inspired, minimalistic modeline for Doom Emacs, powered by the doom-modeline package (where you can find screenshots).

Blink after big motions

This module flashes the line around the cursor after any significant motion, to make it easy to follow after big operations.

Tremendously helpful on large, 1600p+ or 4K displays.

NERDTree for evil nerds

This module brings a side panel for browsing project files, inspired by vim’s NERDTree.

Sure, there’s dired and projectile, but sometimes I’d like a bird’s eye view of a project.

An indicator for “what did I just do?”

This module provides op-hints (operation hinting), i.e. visual feedback for certain operations. It highlights regions of text that the last operation (like yank) acted on.

Uses evil-goggles for evil users and volatile-highlights otherwise.

Flags: +all +defaults

Tame sudden yet inevitable temporary windows

This module provides a customizable popup window management system.

Not all windows are created equally. Some are less important. Some I want gone once they have served their purpose, like code output or a help buffer. Others I want to stick around, like a scratch buffer or org-capture popup.

More than that, popups ought to be the second class citizens of my editor; spawned off to the side, discarded with the push of a button (e.g. ESC or C-g), and easily restored if I want to see them again. Of course, this system should clean up after itself and kill off buffers I mark as transient.

Keep tabs on your buffers, literally

This module adds an Atom-esque tab bar to the Emacs UI.

Flags: +lsp

A project drawer like neotree but cooler

Treemacs is a file and project explorer similar to NeoTree or vim’s NerdTree, but largely inspired by the Project Explorer in Eclipse. It shows the file system outlines of your projects in a simple tree layout allowing quick navigation and exploration, while also possessing basic file management utilities. It includes:

• Integration with Git (when :tools magit is enabled)
• Integration with Evil (when :editor evil +everywhere is enabled)
• Workspace awareness (when :ui workspaces is enabled)

Extended unicode support for various languages

This module extends Doom’s ability to display non-English unicode. It is primarily useful for non-English Emacs users, for whom Doom’s built-in unicode support in insufficient.

This module relies on the unicode-fonts package. It tries to setup the default emacs fontset to cover as many unicode glyphs as possible by scanning all available glyphs from all available fonts.

When this module is enabled:

• Emacs will prefer to use the doom-unicode-font font to display non-latin glyphs if it provides coverage for them.
• The first time you run Emacs a unicode cache will be generated – this will take a while!
• The cache will be regenerated every time Emacs is made aware of new fonts or you change the font configuration e.g. by modifying doom-unicode-font.
• The cache will be stored and should not be regenerated unless font-related configuration or the versions of relevant packages changes.

Get your diff out of the gutter

This module displays a diff of the current file (against HEAD) in the fringe. Supports Git, Svn, Hg, and Bzr.

Fringe tildes beyond EOB

Displays a tilde(~) in the left fringe to indicate an empty line, similar to Vi.

Flags: +numbers +switch-window

Visually switch windows

This module provides several methods for selecting windows without the use of the mouse or spatial navigation (e.g. C-w {h,j,k,l}).

The command other-window is remapped to either switch-window or ace-window, depending on which backend you’ve enabled. It is bound to C-x o (and C-w C-w for evil users).

It also provides numbered windows and selection with the winum package, if desired. Evil users can jump to window N in C-w <N> (where N is a number between 0 and 9). Non evil users have C-x w <N> instead.

Tab emulation, persistence, & separate workspaces

This module adds support for workspaces, powered by persp-mode, as well as a API for manipulating them.

There are many ways to use workspaces. I spawn a workspace per task. Say I’m working in the main workspace, when I realize there is a bug in another part of my project. I open a new workspace and deal with it in there. In the meantime, I need to check my email, so mu4e gets its own workspace.

Once I’ve completed the task, I close the workspace and return to main.

Distraction-free mode for the eternally distracted

This module provides two minor modes that make Emacs into a more comfortable writing or coding environment. Folks familiar with “distraction-free” or “zen” modes from other editors – or olivetti, sublimity, and tabula-rasa (Emacs plugins) – will feel right at home.

These modes are:

mixed-pitch-mode

Which renders (most) text in a variable pitch font (see doom-variable-pitch-font). Unlike variable-pitch-mode, this will not affect segments of text that are intended to remain in a fixed pitch font, such as code blocks or ASCII tables.

writeroom-mode

Our all-in-one “zen” mode that will:

1. Center the current buffer.
2. Remove superfluous UI elements (like the modeline).
3. Activate mixed-pitch-mode.
4. Scale up the buffer’s text slightly (see +zen-text-scale).
5. And make the window’s borders slightly thicker (see +zen-window-divider-size).

Last updated 2021-10-16

There are contributions that will be immediately refused, either due to project policy or an external factor blocking development. A list of these is maintained here and is likely to change from time to time. Consult it each time you prepare to file a pull request.

• Feature-gate keybinds in the :config default module. That is to say, PRs to wrap keybinds in (:when (featurep! ...) ...) checks will not be accepted. I explain why in this issue.
• Directly modify modules/index.org: this file is automatically generated by doom make module-index and should not be modified by hand.
• Add questions to docs/faq.org without prior approval. Selecting questions for the FAQ requires the insight of our maintainer and community leaders. Please discuss it with them beforehand.

• Correct less than 5 non-technical spelling and grammar errors. These are popular, especially during Hacktoberfest, but their value don’t justify the time cost of reviewing them all so a minimum of 5 errors is required to be accepted. Otherwise, we’d prefer you ping us on Discord or simply wait until it is discovered by a maintainer (or a user with enough errors to correct).

  Of course, any correction that impacts the technical correctness of our documentation is exempt from this rule. e.g. Misspelling the name of a package in a shell command.

Last updated 2021-10-16

These are packages whose pins should not be updated:

• format-all: a rewrite of the :editor format module is in the works and updates upstream have introduced breaking changes to the package that are incompatible with our module (and go again our design goals for the module).

An effective bug report is informative. Please try to provide:

• A backtrace of all mentioned errors.
• A step-by-step reproduction of the issue.
• Information about your Doom config and system environment.
• Screenshots/casts of the issue (if possible).

This section will show you how to collect this information.

…

1. Now you wait for a code review:
   • If your PR is approved, you don’t need to do anything. It will be merged soon (the maintainer approves PRs ahead of time, then merges them in bulk later).
   • Your PR may acquire one of these labels:
     • status:needs-work: I’m interested in your PR, but it needs some changes to be accepted. Keep in mind there may be a delay between getting this tag and getting an explanation for it.
     • status:moved: the PR won’t be merged because it will be addressed elsewhere, in another PR or a future commit.
2. The PR is either merged or closed.

…

…

…

For collaborators with PR merge permissions have three options when merging commits on the Github UI: a conventional merging, squashing, or rebasing. When do you do which?

• If a PR has one commit:
  • Squash it if the commit message needs correcting.
  • Rebase it otherwise.
• If a PR has multiple commits:
  • Squash it if extra commits are corrective and/or add no value to the PR’s git history.
  • Merge it conventionally otherwise (don’t forget to substitute s/^Merge /merge: /).
• If the PR has merge conflicts, ask OP to rebase or redo their PR.