This minor mode highlights indentation levels via
font-lock. Indent widths are
dynamically discovered, which means this correctly highlights in any mode,
regardless of indent width, even in languages with non-uniform indentation such
as Haskell. By default, this mode also inspects your theme dynamically, and
automatically chooses appropriate colors for highlighting. This mode works
properly around hard tabs and mixed indentation, and it behaves well in large
(setq highlight-indent-guides-method ...)
To install from Melpa, use M-x
package-install RET highlight-indent-guides RET. Otherwise, download
highlight-indent-guides.el and put it in your load path.
Once the mode is installed, do M-x highlight-indent-guides-mode to enable it. To enable it automatically in most programming modes, use the following:
(add-hook 'prog-mode-hook 'highlight-indent-guides-mode)
This mode supports three display methods. To change the display method,
highlight-indent-guides-method, and set it to one of the following:
fill: The default method. All whitespace used for indentation is highlighted. The color of each level of indentation alternates between
fill, but only the first column of each level of indentation is highlighted.
character: The first column of each level of indentation is drawn using a column of characters. The character to draw with is specified by
highlight-indent-guides-character, and it is drawn using the face
(setq highlight-indent-guides-method 'character)
To change the character used for drawing guide lines with the
display method, customize
(setq highlight-indent-guides-character ?\|)
By default, this mode dynamically chooses colors that look acceptable with the loaded theme. It does this by altering the luminosity of the theme's background color by a given percentage. These percentages can be tweaked, to make the colors more intense or subtle.
(setq highlight-indent-guides-auto-odd-face-perc 15) (setq highlight-indent-guides-auto-even-face-perc 15) (setq highlight-indent-guides-auto-character-face-perc 20)
To set the colors manually, disable this feature and customize the faces directly.
(setq highlight-indent-guides-auto-enabled nil) (set-face-background 'highlight-indent-guides-odd-face "darkgray") (set-face-background 'highlight-indent-guides-even-face "dimgray") (set-face-foreground 'highlight-indent-guides-character-face "dimgray")
Responsive guides allow you to visualize not only the indentation itself, but
your place in it. To enable this feature, customize
highlight-indent-guides-responsive, and set it to one of the following:
nil: The default. Responsive guides are disabled.
top: Use a different color to highlight the "current" guide (the indentation block of the line that the cursor is on). This changes as the cursor moves.
top, but also use a third color for all "ancestor" guides of the current guide. Again, this will change as the cursor moves around.
By default, responsive guides are not updated immediately every time the cursor
moves. Instead, guides only update after the cursor stops moving for a certain
period of time (one tenth of a second, by default). If you would like to change
this behavior, customize
highlight-indent-guides-delay, and set it to the
number of seconds to wait. For example, to disable the delay entirely:
(setq highlight-indent-guides-delay 0)
Enabling this feature provides more highlight faces, as well as more color modifiers for the dynamic colors feature. These are specified in the following table:
Custom Highlighter Function
The highlighter function is the function that calculates which faces to use to
display each guide character. If the default highlighter function isn't doing it
for you, you can write your own by customizing
highlight-indent-guides-highlighter-function. A custom highlighter takes three
level: The indent level this guide character exists at, starting at
responsive: The responsive class of this guide character. This can be
display: The display method setting. One of
A custom highlighter should return the face to use to color the given guide
character. Alternatively, it may return
nil to specify that the guide should
not be displayed at all.
The highlighter function is called once for each indentation character, each time a section of the buffer is re-highlighted. To speed things up a little, the results of the highlighter function are memoized per-character, and are reused when possible. Because of this, a custom highlighter should run quickly, and should not have side-effects (i.e. it should not depend on or change external values that might differ from one call to the next). A custom highlighter can return custom faces, but those faces will not be recognized by the dynamic color feature, and will need to be defined and colored manually.
The following example highlighter will highlight normally, except that it will not highlight the first two levels of indentation:
(defun my-highlighter (level responsive display) (if (> 2 level) nil (highlight-indent-guides--highlighter-default level responsive display))) (setq highlight-indent-guides-highlighter-function 'my-highlighter)
To display the
character method guides, and to highlight tab characters
correctly, this mode controls the
display text property of some characters via
font-lock. Therefore, this mode may or may not play well with other modes that
display text property. This mode may also interfere with modes that
use a display table to modify how whitespace is drawn, e.g., the
Currently, with the way this mode is designed, there is no good way to display indent guides on empty lines.
|Package Name||Widths||Hard Tabs||Other Notes|
|indent-guide.el||Dynamic||Supported||Fairly slow, jittery|
|hl-indent.el||Dynamic||Unsupported||Slow for large files|
|visual-indentation-mode.el||Fixed||Unsupported||Fast and slim|