+
+
+
+
+
+
+
+ 
+
+
+ 
+
+
- 
- 
- 
- 
- 
+ wiki |
+ screenshots |
+ faq |
+ troubleshooting |
+ changelog
- Wiki | - Screenshots | - Troubleshooting | - FAQ | - Changelog -
+Quick start +----------- -- - - +```bash +git clone https://github.com/hlissner/doom-emacs ~/.emacs.d +~/.emacs.d/bin/doom quickstart +``` + +> Doom supports Emacs 25.3 and newer, but **Emacs 26.1 is recommended.** Doom +> works best on Linux & MacOS. Your mileage may vary on Windows. + + +Table of Contents +================== +- [What is Doom Emacs](#what-is-doom-emacs) + - [Doom's mantras](#dooms-mantras) + - [Feature highlights](#feature-highlights) +- [Getting Help](#getting-help) +- [Contributing](#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 finally succumbing to the [dark side][evil-mode]. This is his config.
+before succumbing to the [dark side][evil-mode]. This is his config.
-Doom strives to be fast, fabulous and hacker friendly. It is tailored for
-neckbeards with blue belts or better in command-line-fu, Elisp and git.
+Doom is a configuration for [GNU Emacs](https://www.gnu.org/software/emacs/). It
+can be used as framework for your own configuration, or as a resource for fellow
+Emacs enthusiasts who want to learn more about our favorite OS.
-> Doom **only** supports Emacs >= 25.1, and is tested on Arch Linux 4.7+ and
-> MacOS 10.11. YMMV on other platforms.
+Doom's mantras
+--------------
+- **Gotta go fast.** Startup and runtime speed are high priorities; many
+ expensive, heavy-handed features and packages have been fine-tuned to that
+ end.
+- **Hacker-friendly.** Doom caters to the command line denizen unafraid of
+ writing a little (or a lot of) code to tailor their editor. It also inherits
+ your shell configuration, warts 'n all, and expects frequent trips into the
+ terminal to manage Doom with its `bin/doom` utility.
+- **Opinionated, but not stubborn.** Doom has _many_ opinions spread out across
+ its 120+ modules designed to iron out idiosynchrosies and provide a better and
+ more consistent baseline experience of Emacs and its plugins. However, they
+ mustn't ever compromise your ability to change, rewrite or disable any or all
+ of it, if you ask nicely.
+- **Written to be read.** Doom's source ought to be self documenting and easy to
+ grok. Modules should be syntactically sweet and concise, and backend logic
+ should be explicit and abstraction-light. Where complexity arises, comments
+ and documentation shouldn't be far away.
-- - -
+Feature Highlights
+------------------
+- A declarative [package management system][doom:packages] with a command line
+ interface that combines package.el, [use-package] and [quelpa], allowing you
+ to install packages from anywhere.
+- A [popup management system][doom:popups] with customizable rules to dictate
+ how temporary/disposable buffers are displayed.
+- A vim-centric (and optional) experience with [evil-mode], including ports of
+ several popular vim plugins, C-x omnicompletion and a slew of
+ [custom ex commands][doom:commands].
+- A Spacemacs-esque [keybinding scheme][doom:bindings], centered around leader
+ and localleader prefix keys (SPC and SPCm, by
+ default).
+- Indentation detection and optional integration with [url:editorconfig]. Let
+ someone else argue about tabs vs ___***spaces***___.
+- Code completion for many languages, powered by
+ [company-mode][url:company-mode] (some may have external dependencies).
+- Project-awareness powered by [projectile][url:projectile], with tools and an
+ API to navigate and manage projects, as well as project/framework-specific
+ minor modes and snippets libraries (and the ability to define your own).
+- Project search (and replace) utilities, powered by
+ [the_silver_searcher][url:ag], [ripgrep][url:rg], git-grep and
+ [wgrep][url:wgrep], with integration for [ivy][url:ivy] (the default) and
+ [url:helm].
+- Isolated and persistent workspaces powered by [persp-mode][url:persp-mode].
+ Also substitutes as vim tabs.
+- Inline/live code evaluation (using [quickrun][url:quickrun]), with REPL
+ support for a variety of languages.
+- A jump-to-definition/references implementation for all languages that tries to
+ "just work," resorting to mode-specific functionality, before falling back on
+ [dump-jump][url:dumb-jump].
-## Quick start
-```bash
-git clone https://github.com/hlissner/doom-emacs ~/.emacs.d
-cd ~/.emacs.d
-make quickstart
-```
+Troubleshooting
+===============
-Don't forget to run `make` each time you modify init.el or update Doom!
+Encountered strange behavior or an error? Here are some things to try before you
+shoot off that bug report:
-Visit the wiki for [a more detailed guide on installing, customizing and
-grokking Doom][wiki].
+- 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 your issue go away. Never debug issues with a
+ byte-compiled config, it will only 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][docs:faq] to see if your issue is listed.
-## Feature highlights
+If all else fails, [file that bug report][github:new-issue]! Please include the
+behavior you've observed, the behavior you expected, and any error message in
+the \*Messages\* buffer (can be opened with SPC h m or `M-x
+view-echo-area-messages`). It'd be a great help if you included a backtrace with
+them as well.
-+ A fast, organized and opinionated Emacs configuration with a command line
- interface.
-+ A custom, declarative [package management system][doom-packages] that combines
- package.el, [use-package] and [quelpa], allowing you to manage packages from
- the command line and install packages from sources other than ELPA.
-+ A [popup management system][doom-popups] (powered by [shackle]) that minimizes
- the presence and footprint of temporary and/or disposable buffers.
-+ A vim-like experience with [evil-mode], including ports for several vim
- plugins, C-x omnicompletion and a slew of [custom ex
- commands][doom-my-commands].
-+ Integration with [editorconfig]. Let someone else argue about tabs and spaces.
- (spaces, duh).
-+ Code completion for many languages, powered by [company-mode] (some languages
- may have external dependencies).
-+ Project-awareness powered by [projectile], with tools and an API to navigate
- and manage projects and their files.
-+ Fast project search (and replace) utilities, powered by [the_silver_searcher],
- [ripgrep] and [wgrep], with integration for [ivy] (the default), [helm] and
- ido.
-+ Isolated and persistent workspaces powered by [persp-mode]. Also substitutes
- for vim tabs.
-+ Inline/live code evaluation (using [quickrun]), including REPLs for a variety
- of languages.
+We've also got [a Discord server][url:discord]. Hop on! We can help!
-## Troubleshooting
-Found a problem? Here are some things to try:
-
-+ Run `make install` to ensure all plugins are installed.
-+ `void-function` or `void-variable` errors could signal an out-of-date
- autoloads file. Run `make autoloads` or `M-x doom//reload-autoloads` to update
- it.
-+ Scan for common OS/environment issues with `make doctor`.
-+ **Never debug byte-compiled code. It will interfere in subtle ways.** Clean up
- \*.elc files with `make clean` or `M-x doom//clean-byte-compiled-files`.
-+ Check [the FAQ][wiki-troubleshooting] to see if your issue is mentioned.
-+ Check the relevant module's README.org, if one exists. There may be extra
- steps to getting certain features to work.
-
-If all else has failed, [file a bug report][doom-new-issue].
-
-## Contribute
+Contributing
+============
Doom (and my Emacs work in general) is a labor of love and incurable madness,
-done on my spare time. It wasn't intended for public use, but I enjoy making
-Doom a resource for others.
+done on my spare time. If you'd like to support my work, I welcome
+contributions:
-If you'd like to support my efforts, I welcome contributions of any kind:
-
-+ I love pull requests and bug reports. Elisp pointers are especially welcome.
- Seriously, don't hesitate to [tell me my Elisp-fu sucks][doom-new-issue]!
-+ Talk to me about Emacs workflow, ideas or tooling. Or talk to me about
- gamedev, or pixel art, or anime, or programming, or the weather, or band camp.
- Whatever. I don't mind. Holler at henrik@lissner.net.
+- I love pull requests and bug reports. Check out the [Contributing
+ Guidelines][docs:contributing] (WIP) to find out how you can help out.
+- I welcome Elisp pointers! Don't hesitate to [tell me my Elisp-fu
+ sucks][github:new-issue] (but please tell me why).
+- Hop on [our Discord server][url:discord] 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][url:liberapay] or [paypal][url:paypal]. Donations are a
+ great help. My work here contends with full-time studies, my ventures in indie
+ gamedev, and my freelance work.
-[wiki]: /../../wiki
-[wiki-conventions]: /../../wiki/Conventions
-[wiki-modules]: /../../wiki/Modules
-[wiki-customization]: /../../wiki/Customization
-[wiki-troubleshooting]: /../../wiki/FAQ#troubleshooting
+
+
+
+
+
+
+[docs:faq]: /../../wiki/FAQ
-[doom-my-bindings]: modules/private/hlissner/+bindings.el
-[doom-my-commands]: modules/private/hlissner/+commands.el
-[doom-new-issue]: https://github.com/hlissner/doom-emacs/issues/new
-[doom-packages]: core/autoload/packages.el
-[doom-popups]: modules/ui/popup
-[doom-theme]: https://github.com/hlissner/emacs-doom-theme
+[github:new-issue]: https://github.com/hlissner/doom-emacs/issues/new
+[doom:bindings]: modules/config/default/+bindings.el
+[doom:commands]: modules/config/default/+evil-commands.el
+[doom:packages]: core/autoload/packages.el
+[doom:popups]: modules/feature/popup/README.org
-[company-mode]: https://github.com/company-mode/company-mode
-[editorconfig]: http://editorconfig.org/
-[evil-mode]: https://github.com/emacs-evil/evil
-[git-gutter-fringe]: https://github.com/syohex/emacs-git-gutter-fringe
-[helm]: https://github.com/emacs-helm/helm
-[ivy]: https://github.com/abo-abo/swiper
-[persp-mode]: https://github.com/Bad-ptr/persp-mode.el
-[projectile]: https://github.com/bbatsov/projectile
-[quelpa]: https://github.com/quelpa/quelpa
-[quickrun]: https://github.com/syohex/emacs-quickrun
-[ripgrep]: https://github.com/BurntSushi/ripgrep
-[shackle]: https://github.com/wasamasa/shackle
-[the_silver_searcher]: https://github.com/ggreer/the_silver_searcher
-[use-package]: https://github.com/jwiegley/use-package
-[vim]: https://github.com/hlissner/.vim
-[wgrep]: https://github.com/mhayashi1120/Emacs-wgrep
+[url:discord]: https://discord.gg/bcZ6P3y
+[url:liberapay]: https://liberapay.com/hlissner/donate
+[url:paypal]: https://paypal.me/henriklissner/10
+[url:company-mode]: https://github.com/company-mode/company-mode
+[url:doom-themes]: https://github.com/hlissner/emacs-doom-themes
+[url:editorconfig]: http://editorconfig.org/
+[url:evil-mode]: https://github.com/emacs-evil/evil
+[url:helm]: https://github.com/emacs-helm/helm
+[url:ivy]: https://github.com/abo-abo/swiper
+[url:persp-mode]: https://github.com/Bad-ptr/persp-mode.el
+[url:projectile]: https://github.com/bbatsov/projectile
+[url:quelpa]: https://github.com/quelpa/quelpa
+[url:quickrun]: https://github.com/syohex/emacs-quickrun
+[url:ripgrep]: https://github.com/BurntSushi/ripgrep
+[url:the_silver_searcher]: https://github.com/ggreer/the_silver_searcher
+[url:use-package]: https://github.com/jwiegley/use-package
+[url:wgrep]: https://github.com/mhayashi1120/Emacs-wgrep