/.emacs.d

Centaur Emacs - A Fancy and Fast Emacs Configuration

Primary LanguageEmacs LispGNU General Public License v3.0GPL-3.0

Centaur Emacs

Build Status Release Tag License Windows Linux macOS

Centaur Emacs

Table of Contents

This is an Emacs distribution that aims to enhance the default Emacs experience. It alters a lot of the default settings, bundles a plethora of additional packages and adds its own core library to the mix. The final product offers an easy to use Emacs configuration for Emacs newcomers and lots of additional power for Emacs power users.

It's able to run on Windows, GNU Linux and macOS. It is compatible ONLY with GNU Emacs 26.1 and above. In general you're advised to always run with the latest stable release - currently 28.1.

Features

  • Out of box.
  • Clean and Fast.
  • Quick fuzzy search.
  • Better Org/Markdown support.
  • Support multiple programming languages
    • C/C++/Object-C/C#/Java
    • Python/Ruby/Perl/PHP/Shell/Powershell/Bat
    • JavaScript/Typescript/JSON/YAML
    • HTML/CSS/XML
    • Golang/Swift/Rust/Dart/Elixir
    • ...
  • Auto completion.
  • Fly syntax check.
  • Fly spell check.
  • Git integration.
  • Project/Workspace integration.
  • Pomodor integration.
  • MPD integration.
  • Support docker.
  • Better Chinese support:
    • Chinese calendar
    • Youdao dictionary
    • Google translation
    • Pinyin search

Prerequisite

OS

  • GNU Linux
  • macOS
  • Windows (Cygwin/MSYS)

GNU Emacs

Please refer to Installing Emacs.

Dotfiles

Recommend to use Centaur Dotfiles.

Quick Start

Install

mv ~/.emacs.d ~/.emacs.d.bak
git clone --depth 1 https://github.com/seagle0128/.emacs.d.git ~/.emacs.d

or download the zip package directly and extract to ~/.emacs.d.

If you are using Linux, you may prefer an XDG-compatible location, please use

# Please make sure ~/.emacs.d, ~/.emacs and ~/.emacs.el don't exist
git clone --depth 1 https://github.com/seagle0128/.emacs.d.git $XDG_CONFIG_HOME/emacs

or extract the zip package to $XDG_CONFIG_HOME/emacs directory.

Then start Emacs. Wait for a while to install packages at the first startup. Enjoy! 😄

Attention: It may take long time to download packages at the first startup. It's up to your network speed. If it takes too long time and no response, check the connection or use proxy.

Note: Start Emacs with the minimal configuration for fast startup and troubleshooting.

emacs -Q -l ~/.emacs.d/init-mini.el

Update

# Update Centaur Emacs, including configurations and packages
M-x centaur-update

# Update Emacs configurations only
M-x centaur-update-config

# Update ~/.dotfiles if it exists
M-x centaur-update-dotfiles

# Update packages only
M-x centaur-update-packages

# Update all including configurations, packages and dotfiles
M-x centaur-update-all

Trick: Update configurations and packages in shell.

alias upgrade_emacs='emacs -Q --batch -L "$HOME/.emacs.d/lisp/" -l "init-funcs.el" -l "init-package.el" --eval "(update-config-and-packages t)"'

Docker

cd ~/.emacs.d/Dockerfile
docker build -t centaur/emacs .
docker run -it centaur/emacs bash

Customization

Customize Group

M-x customize-group and select centaur. Set and save the configurations, then restart Emacs.

Manual

Add or change the configurations in custom.el, then restart Emacs.

For Example:

(setq centaur-logo nil)                        ; Logo file or nil (official logo)
(setq centaur-full-name "user name")           ; User full name
(setq centaur-mail-address "user@email.com")   ; Email address
(setq centaur-proxy "127.0.0.1:1087")          ; HTTP/HTTPS proxy
(setq centaur-socks-proxy "127.0.0.1:1086")    ; SOCKS proxy
(setq centaur-server t)                        ; Enable `server-mode' or not: t or nil
(setq centaur-icon t)                          ; Display icons or not: t or nil
(setq centaur-package-archives 'melpa)         ; Package repo: melpa, emacs-cn, netease, ustc, tencent or tuna
(setq centaur-theme 'auto)                     ; Color theme: auto, random, system, default, pro, dark, light, warm, cold, day or night
(setq centaur-completion-style 'minibuffer)    ; Completion display style: minibuffer or childframe
(setq centaur-dashboard nil)                   ; Display dashboard at startup or not: t or nil
(setq centaur-restore-frame-geometry nil)      ; Restore the frame's geometry at startup: t or nil
(setq centaur-lsp 'eglot)                      ; Set LSP client: lsp-mode, eglot or nil
(setq centaur-lsp-format-on-save-ignore-modes '(c-mode c++-mode python-mode markdown-mode)) ; Ignore format on save for some languages
(setq centaur-tree-sitter t)                   ; Enable `tree-sitter' or not: t or nil
(setq centaur-chinese-calendar nil)            ; Support Chinese calendar or not: t or nil
(setq centaur-player t)                        ; Enable players or not: t or nil
(setq centaur-prettify-symbols-alist nil)      ; Alist of symbol prettifications. Nil to use font supports ligatures.
(setq centaur-prettify-org-symbols-alist nil)  ; Alist of symbol prettifications for `org-mode'

The default package archives is melpa. You can change it in custom.el, or set manually via M-x set-package-archives anytime.

For the personal configurations, you could put to ~/.emacs.d/custom-post.org or~/.emacs.d/custom-post.el.

Hydra

Name Scope Keybinding Description
toggles-hydra global <f6> Global option toggles
window-hydra global C-c w/C-x o w Window management
doom-modeline-hydra doom-modeline-mode C-<f6> Mode-line options and actions
hydra-ivy minibuffer, ivy-mode C-o Additional key bindings for Ivy
ivy-hydra-read-action minibuffer, ivy-mode M-o Actions forivy-dispatching-done
hydra-dired-qick-sort dired S Options for dired-quick-sort
org-hydra org-mode < Org template
dashboard-hydra dashboard-mode h/? Actions for the dashboard
dumb-jump-hydra global C-M-j Jump to definition
youdao-dictionay-hydra youdao-dictionay-mode h/? Actions for youdao-dictionary
ztreediff-hydra zreediff-mode C-<f5> Actions for text mode directory tree
git-messenger-hydra global C-x v p Actions for git-messenger
smerge-mode-hydra smerge-mode C-c m Actions for smerge-mode
rect-hydra text-mode, prog-mode C-<return> Actions for Rectangle
rect-hydra org-mode S-<return> Actions for Rectangle
hideshow-hydra prog-mode C-~ Actions for hideshow
lsp-ui-hydra lsp-ui-mode M-<f6> Actions for lsp-ui
dap-hydra dap-mode M-<f5> Actions for dap-debug
elfeed-hydra elfeed ? Actions for RSS reader elfeed
xwidget-hydra xwidget-webkit-mode ? Actions for embedded webkit browser

Screenshots

Dashboard

color_icons

markdown_magit

org_classic

main_light

FAQ

  1. How to display icons correctly in Centaur Emacs?

    Generally you just use M-x centaur-install-fonts to install all necessary fonts. The manual steps are below.

    all-the-icons are necessary. Run M-x all-the-icons-install-fonts to install the resource fonts. On Windows, the fonts should be installed manually. all-the-icons only support GUI. If you don't like color icons, (setq all-the-icons-color-icons nil) to disable it. Please refer to all-the-icons.el for details.

    If the icons are not displayed correctly although all-the-icons fonts are installed correctly, please install the non-free font Symbola. This issue usually occurs on Windows. Refer to #121 for more details.

    If you are using cnfonts, it will conflict with all-the-icons. The workaround is here.

    For better experience, I don't recommend to use GUI with emacsclient in daemon mode. See #154.

  2. The packages cannot be installed, what should I do?

    Generally it's due to connection issue. Please refer to #98.

    • M-x package-refresh-contents and try again.
    • (setq gnutls-algorithm-priority "NORMAL:-VERS-TLS1.3").
    • Use other mirror of ELPA.
    • Change another network to retry.

  3. How to search Chinese via pinyin?

    In Emacs, C-s !. If you just want to search !, use C-s \!.

  4. How to use the Centaur Dashboard?

    If centaur-dashboard is non-nil the Centaur Dashboard will be opened at startup automatically. After startup, you could use F2 to reopen it anytime. In the dashboard, please press ? or h to get the help. You can easily jump to the sections or buttons with keybindings, e.g. Homepage(H), Session(R, L), Settings(S), Update(U), Recent Files (r), Bookmarks(m) and Projects(p).

  5. Does Centaur Emacs support Language Server Protocol (LSP)?

    The LSP feature is supported and enabled by default in Centaur Emacs. lsp-mode is the default client, and eglot is another choice. Use (setq centaur-lsp nil) to disable LSP if you don't like it.

    To use LSP you should install the language servers. Refer to lsp-mode: supported-languages or eglot: Connecting to a server for the details.

  6. How to enable plantuml in org-mode?

    Put (setq org-plantuml-jar-path "<path of plantumx.x.x.jar>") in custom.el.

  7. Why the Emacs environment variables and exec-path are different between GUI and terminal?

    Please refer to #33. You should instead set environment variables in startup files like .profile, .bash_profile or .zshenv, then Centaur Emacs is able to recognize and import the environment variables.

  8. How to use zoom-window in Centaur Emacs?

    See #169.

Donate

If you think the it's helpful for you, please consider paying a cup of coffee for me. Thank you! 😄

Alipay      Wechat Pay

PayPal      Buy Me A Coffee