razzmatazz / doom-emacs

An Emacs configuration for the stubborn martian vimmer

Screenshots | Get started | Contribute | Documentation | FAQ

---

Quick start

git clone https://github.com/hlissner/doom-emacs ~/.emacs.d
~/.emacs.d/bin/doom install

Table of Contents

• What is Doom Emacs
  • Doom's mantras
  • Features
• Getting Help
  • Community
  • Troubleshooting
  • Contributing

What is Doom Emacs

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 succumbing to the dark side. This is his config.

Doom is a configuration for GNU Emacs designed to make Emacs faster and easier to customize. It can serve as framework for your own configuration or a resource for fellow Emacs enthusiasts who want to learn more about our favorite OS.

Doom's mantras

• Gotta go fast. Startup and run-time performance are high priorities. Expensive functionality (built-in or in plugins) is modified and optimized toward this end, otherwise, they must be opt-in.
• Close to metal. There's less between you and vanilla Emacs, by design. There's less to grok. Modules should be syntactically sweet and backend logic explicit and abstraction-light. The code itself ought to be designed as if grokking it were part of the user experience; and it is!
• Opinionated, but not stubborn. Doom is a bundle of reasonable defaults and curated opinions, but you aren't stuck with it. Use as little or as much of it as you like. Use it as-is as a complete Emacs distribution; disable everything and use it as a baseline for your own; or anywhere in between.
• Your system, your rules. There are more ways to set up your programming environment than there are dislikes on Youtube Rewind '18, so Doom and its plugins promise not to automatically (and definitely not silently) install system dependencies. This means fonts, packages and programs. doom doctor will tell you what's missing though!

Features

• A curated set of sane defaults for all packages, all (major) OSes, and Emacs itself.
• Support for many programming languages. Too many to list. 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.
• Minimalistic good looks inspired by modern editors.
• A modular architecture for a more organized Emacs configuration.
• A custom elisp library to help you simplify your config.
• A declarative package management system (powered by straight.el) with a command line interface. Install packages from anywhere, not just (M)ELPA.
• Vim-emulation powered by evil-mode, including ports of popular vim plugins and functionality.
• A Spacemacs-esque keybinding scheme, centered around leader and localleader prefix keys (SPC and SPCm, by default).
• A rule-based popup management system that dictates how temporary or disposable buffers are displayed (and disposed of).
• Automatic indentation 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 the_silver_searcher or ripgrep.
• Isolated and persistent workspaces (also substitutes for vim tabs).
• An environment variables file generator and loader, so that Emacs can perfectly inherit your shell configuration.
• Everything is optional!

Getting Help

Community

We have a Discord server! Hop on and say hi!

Troubleshooting

Encountered strange behavior or an error? Here are some things to try before you shoot off that bug report:

• Run bin/doom refresh. This ensures Doom is properly set up and its autoloads files are up-to-date.
• If you have byte-compiled your config (with bin/doom compile), see if bin/doom clean makes the issue go away. Never debug issues with a byte-compiled config, it will make your job harder.
• Run bin/doom doctor to detect common issues in your development environment.
• Search Doom's issue tracker for mention of any error messages you've received.
• Visit our FAQ to see if your issue is listed.

If all else fails, file that bug report! Please include the behavior you've observed, the behavior you expected, and any error messages or warnings logged to the *Messages* buffer (can be opened with SPC h e or M-x view-echo-area-messages).

It's a great help if you included a backtrace with errors, i.e. M-x toggle-debug-on-error then recreating the error(s).

Contributing

Doom (and my Emacs work in general) is a labor of love and incurable madness, done on my spare time. If you'd like to support my work, there are many things you can do to help; I welcome any contribution!

• I love pull requests and bug reports. Check out the Contributing Guidelines to find out how you can help out.
• I welcome Elisp pointers! 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 out, hang out or talk to me about Emacs, or gamedev, or programming, machine learning, physics, pixel art, anime, gaming -- anything you like. Nourish this lonely soul!
• If you'd like to support my work financially, consider buying me a drink through liberapay or paypal. Donations are a great help. My work here contends with studies, ventures in indie gamedev, and my freelance work.