doom-modeline

doom-modeline

Table of Contents

• Feature
• Screenshots
• Install
  • Manual
  • Use-package
• Customize
• FAQ
• Donate

A fancy and fast mode-line inspired by minimalism design.

It’s integrated into Centaur Emacs, Doom Emacs and Spacemacs.

Feature

The doom-modeline was designed for minimalism, and offers:

• A match count panel (for anzu, visual-replace, iedit, multiple-cursors, symbol-overlay, and evil-search, etc.)
• An indicator for recording a macro
• Current environment version (e.g. python, ruby, go, etc.) in the major-mode
• A customizable mode-line height (see doom-modeline-height)
• A minor modes segment which is compatible with minions
• An error/warning count segment for flymake/flycheck
• A workspace name segment for eyebrowse/tab-bar-mode
• A perspective name segment for persp-mode
• A window number segment for ace-window, winum and window-numbering
• An indicator for modal editing state, including evil, overwrite, god, ryo and xah-fly-keys, etc.
• An indicator for battery status
• An indicator for current input method
• An indicator for debug state
• An indicator for remote host
• An indicator for Kubernetes state with kele.el
• An indicator for LSP state with lsp-mode or eglot
• An indicator for GitHub notifications
• An indicator for unread emails with mu4e-alert and gnus
• An indicator for IRC notifications with circe, rcirc or erc
• An indicator for buffer position which is compatible with nyan-mode or poke-line
• An indicator for party parrot
• An indicator for PDF page number with pdf-tools
• An indicator for markdown/org preview with grip
• An indicator for keycast events when keycast-invisible-mode is on.
• An indicator for minibuffer-depth when > 1
• Truncated file name, file icon, buffer state and project name in buffer information segment, which is compatible with project, projectile and find-file-in-project.
• New mode-line for Info-mode buffers
• New package mode-line for paradox
• New mode-line for helm buffers
• New mode-line for git-timemachine buffers

Screenshots

Install

Manual

From melpa, M-x package-install RET doom-modeline RET.

In init.el,

(require 'doom-modeline)
(doom-modeline-mode 1)

Use-package

(use-package doom-modeline
  :ensure t
  :init (doom-modeline-mode 1))

This package is able to display icons if nerd-icons package and required fonts are installed. Run M-x nerd-icons-install-fonts to install the necessary fonts. Please refer to the installation guide.

Strongly recommend to use doom-themes at the same time.

Customize

Run M-x customize-group RET doom-modeline RET or set the variables.

;; If non-nil, cause imenu to see `doom-modeline' declarations.
;; This is done by adjusting `lisp-imenu-generic-expression' to
;; include support for finding `doom-modeline-def-*' forms.
;; Must be set before loading doom-modeline.
(setq doom-modeline-support-imenu t)

;; How tall the mode-line should be. It's only respected in GUI.
;; If the actual char height is larger, it respects the actual height.
(setq doom-modeline-height 25)

;; How wide the mode-line bar should be. It's only respected in GUI.
(setq doom-modeline-bar-width 4)

;; Whether to use hud instead of default bar. It's only respected in GUI.
(setq doom-modeline-hud nil)

;; Width in pixels of the \"thumb\" hud. It's only respected in GUI.
(setq doom-modeline-hud-width 8)

;; Minimum height in pixels of the \"thumb\" of the hud.
;; It's only respected in GUI."
(setq doom-modeline-hud-min-height 2)

;; The limit of the window width.
;; If `window-width' is smaller than the limit, some information won't be
;; displayed. It can be an integer or a float number. `nil' means no limit."
(setq doom-modeline-window-width-limit 85)

;; Override attributes of the face used for padding.
;; If the space character is very thin in the modeline, for example if a
;; variable pitch font is used there, then segments may appear unusually close.
;; To use the space character from the `fixed-pitch' font family instead, set
;; this variable to `(list :family (face-attribute 'fixed-pitch :family))'.
(setq doom-modeline-spc-face-overrides nil)

;; How to detect the project root.
;; nil means to use `default-directory'.
;; The project management packages have some issues on detecting project root.
;; e.g. `projectile' doesn't handle symlink folders well, while `project' is unable
;; to handle sub-projects.
;; You can specify one if you encounter the issue.
(setq doom-modeline-project-detection 'auto)

;; Determines the style used by `doom-modeline-buffer-file-name'.
;;
;; Given ~/Projects/FOSS/emacs/lisp/comint.el
;;   auto => emacs/l/comint.el (in a project) or comint.el
;;   truncate-upto-project => ~/P/F/emacs/lisp/comint.el
;;   truncate-from-project => ~/Projects/FOSS/emacs/l/comint.el
;;   truncate-with-project => emacs/l/comint.el
;;   truncate-except-project => ~/P/F/emacs/l/comint.el
;;   truncate-upto-root => ~/P/F/e/lisp/comint.el
;;   truncate-all => ~/P/F/e/l/comint.el
;;   truncate-nil => ~/Projects/FOSS/emacs/lisp/comint.el
;;   relative-from-project => emacs/lisp/comint.el
;;   relative-to-project => lisp/comint.el
;;   file-name => comint.el
;;   file-name-with-project => FOSS|comint.el
;;   project => FOSS
;;   buffer-name => comint.el<2> (uniquify buffer name)
;;
;; If you are experiencing the laggy issue, especially while editing remote files
;; with tramp, please try `file-name' style.
;; Please refer to https://github.com/bbatsov/projectile/issues/657.
(setq doom-modeline-buffer-file-name-style 'auto)

;; Whether display icons in the mode-line.
;; While using the server mode in GUI, should set the value explicitly.
(setq doom-modeline-icon t)

;; Whether display the icon for `major-mode'. It respects option `doom-modeline-icon'.
(setq doom-modeline-major-mode-icon t)

;; Whether display the colorful icon for `major-mode'.
;; It respects `nerd-icons-color-icons'.
(setq doom-modeline-major-mode-color-icon t)

;; Whether display the icon for the buffer state. It respects option `doom-modeline-icon'.
(setq doom-modeline-buffer-state-icon t)

;; Whether display the modification icon for the buffer.
;; It respects option `doom-modeline-icon' and option `doom-modeline-buffer-state-icon'.
(setq doom-modeline-buffer-modification-icon t)

;; Whether display the lsp icon. It respects option `doom-modeline-icon'.
(setq doom-modeline-lsp-icon t)

;; Whether display the time icon. It respects option `doom-modeline-icon'.
(setq doom-modeline-time-icon t)

;; Whether display the live icons of time.
;; It respects option `doom-modeline-icon' and option `doom-modeline-time-icon'.
(setq doom-modeline-time-live-icon t)

;; Whether to use an analogue clock svg as the live time icon.
;; It respects options `doom-modeline-icon', `doom-modeline-time-icon', and `doom-modeline-time-live-icon'.
(setq doom-modeline-time-analogue-clock t)

;; The scaling factor used when drawing the analogue clock.
(setq doom-modeline-time-clock-size 0.7)

;; Whether to use unicode numbers.
(setq doom-modeline-unicode-number t)

;; Whether to use unicode as a fallback (instead of ASCII) when not using icons.
(setq doom-modeline-unicode-fallback nil)

;; Whether display the buffer name.
(setq doom-modeline-buffer-name t)

;; Whether highlight the modified buffer name.
(setq doom-modeline-highlight-modified-buffer-name t)

;; When non-nil, mode line displays column numbers zero-based.
;; See `column-number-indicator-zero-based'.
(setq doom-modeline-column-zero-based t)

;; Specification of \"percentage offset\" of window through buffer.
;; See `mode-line-percent-position'.
(setq doom-modeline

提示：代码过长已自动截断

Programmatic Customization

You can programmatically define segments and modelines, and add segments to existing modelines.

Defining Custom Segments

Use doom-modeline-def-segment to define a new segment:

(doom-modeline-def-segment segment-name
  "Docstring describing the segment."
  ;; Body that returns the segment string
  (when some-condition
    (format "output: %s" value)))

Example:

(doom-modeline-def-segment evil-state
  "Display evil state."
  (when (bound-and-true-p evil-mode)
    (format "[%s]" (symbol-name evil-state))))

Defining Custom Modelines

Use doom-modeline-def-modeline to define a new modeline:

(doom-modeline-def-modeline modeline-name
  '(left-hand-side segments)
  '(right-hand-side segments))

Example:

(doom-modeline-def-modeline 'my-simple-line
  '(bar window-number buffer-info)
  '(major-mode time))

;; Set as the default modeline
(add-hook 'doom-modeline-mode-hook
          (lambda ()
            (doom-modeline-set-modeline 'my-simple-line t)))

;; Configure other mode-lines based on major modes
(add-to-list 'doom-modeline-mode-alist '(my-mode . my-simple-line))

;; Or disable other mode-lines
(setq 'doom-modeline-mode-alist nil)

Adding Segments to Existing Modelines

• If the information is simple, add to mode-line-misc-info or global-mode-string.
• Use doom-modeline-add-segment to add a segment to modelines:

;; Exclude certain modelines from automatic modification
(setq doom-modeline-excluded-modelines '(speedbar))

;; Add segment to all modelines (after anchor segment)
(doom-modeline-add-segment 'evil-state 'window-number)

;; Add segment before anchor
(doom-modeline-add-segment 'evil-state 'window-number :before)

;; Add segment to a specific modeline only
(doom-modeline-add-segment 'evil-state 'window-number :after 'main)

Function: doom-modeline-add-segment SEGMENT ANCHOR &optional POSITION MODELINE

• SEGMENT: The segment name to add (a symbol)
• ANCHOR: The segment name to anchor to (a symbol)
• POSITION: Can be :before or :after (default: :after)
• MODELINE: A modeline name (symbol) to add to a specific modeline, or nil/'all to add to all modelines (respecting doom-modeline-excluded-modelines)

Removing Segments from Modelines

• Use doom-modeline-remove-segment to remove a segment from modelines:

;; Remove segment from all modelines
(doom-modeline-remove-segment 'evil-state)

;; Remove segment from a specific modeline only
(doom-modeline-remove-segment 'evil-state 'main)

Function: doom-modeline-remove-segment SEGMENT &optional MODELINE

• SEGMENT: The segment name to remove (a symbol)
• MODELINE: A modeline name (symbol) to remove from a specific modeline, or nil/'all to remove from all modelines (respecting doom-modeline-excluded-modelines)

FAQ

1. How to display icons correctly?

   nerd-icons are necessary. Then run M-x nerd-icons-install-fonts to install the resource fonts. On Windows, the fonts should be installed manually. nerd-icons supports both GUI and TUI.

   If you don’t like color icons, (setq nerd-icons-color-icons nil) to disable it. Please refer to nerd-icons.el for details.

   If you prefer all-the-icons, please use release 3.4.0. It hasn’t been supported since 4.0.0.

2. I am experiencing the laggy issue, how to resolve it?

   Add this configuration into your init file:

   ;; Don’t compact font caches during GC.
   (setq inhibit-compacting-font-caches t)
   

3. A ridiculous path is displayed on the mode-line while visiting a symbolink.

   It’s the default behaviors of Vanilla Emacs. If you want to display the real names, please put this into your init file.

   (setq find-file-visit-truename t)
   

   If the file is controlled by vc, refer to the documentation of vc-follow-symlinks.

4. Why doesn’t change of branch reflect in modeline?

   Actually it’s related to magit and vc-mode.

   • Workaround:
     • Revert the buffers manually.
     • (setq auto-revert-check-vc-info t) brings the performance issue.
   • Refer to:
     • The mode-line information isn’t always up-to-date
     • Maybe provide an alternative to VC’s mode-line information

5. How to specify font family and size in modeline?

   For example:

   (setq doom-modeline-height 1) ; optional
   (if (facep 'mode-line-active)
       (set-face-attribute 'mode-line-active nil :family "Noto Sans" :height 100) ; For 29+
     (set-face-attribute 'mode-line nil :family "Noto Sans" :height 100))
   (set-face-attribute 'mode-line-inactive nil :family "Noto Sans" :height 100)
   

   or

   (setq doom-modeline-height 1) ; optional
   (custom-set-faces
     '(mode-line ((t (:family "Noto Sans" :height 0.9))))
     '(mode-line-active ((t (:family "Noto Sans" :height 0.9)))) ; For 29+
     '(mode-line-inactive ((t (:family "Noto Sans" :height 0.9)))))
   

   Please refer to #189 and #301.

6. The right side of the modeline is cut off. How to fix it?

   • Tweak nerd-icons-scale-factor. e.g. (setq nerd-icons-scale-factor 1.1)
   • Use another font family or size. See above.

7. How to disable symbolic links expanding in mode-line?

   If you encounter the issue like this

   

   please try this:

   ;; built-in `project' on 26+
   (setq doom-modeline-project-detection 'project)
   ;; or `find-in-project' if it's installed
   (setq doom-modeline-project-detection 'ffip)
   

   For more details, refer to #209 and #224.

8. Is doom-modeline able to show match count while search with evil-search?

   Yes. For better experience, should enable anzu-mode and load evil-anzu.

9. How to show that the R is running in inferior ess R mode?

   The ess R mode modifies mode-line-buffer-identification directly to display the status. To display the status in doom-modeline, you can add the status to mode-line-process or global-mode-string as below.

   (add-hook 'inferior-ess-mode-hook
         (lambda ()
           (add-to-list 'mode-line-process '(:eval (nth ess--busy-count ess-busy-strings)))))
   

10. How to display company mode-line information?

    Enable doom-modeline-minor-modes or (add-to-list 'global-mode-string company-lighter).

11. How to display LaTeX compilation information in the mode line?

    Use process package. Please refer to #387 for more details.

    (require 'procress)
    (procress-load-default-svg-images)
    (add-hook 'LaTeX-mode-hook #'procress-auctex-mode)
    

12. How to prevent mode-line aligning with fill column in visual-fill-column-mode?

    Use (setq mode-line-right-align-edge 'right-fringe). Please refer to #672 for more details.

13. How to display match counts in visual-replace?

    It respects visual-replace-display-total, so you should use (setq visual-replace-display-total t) to display.

14. Why am I unable to get the GitHub notifications even though I enable doom-modeline-github?

    The functionality requires the async and ghub packages, and make sure the token has permission to access the Github repositories.

15. How to filter irc notifications to only mentions or keywords?

    Use doom-modeline-irc-priority-only to enable and set up your filters with rcirc-keyword for rcirc and tracking-faces-priorities for circe. ERC support is not yet available see #820.

Donate

If you think it’s helpful for you, please consider paying a cup of coffee for me. Thank you! :smile: