24.6.3 Customizing Search-Based Fontification

You can use font-lock-add-keywords to add additional search-based fontification rules to a major mode, and font-lock-remove-keywords to remove rules. You can also customize the font-lock-ignore option to selectively disable fontification rules for keywords that match certain criteria.

Function: font-lock-add-keywords mode keywords &optional how ¶

This function adds highlighting keywords, for the current buffer or for major mode mode. The argument keywords should be a list with the same format as the variable font-lock-keywords.

If mode is a symbol which is a major mode command name, such as c-mode, the effect is that enabling Font Lock mode in mode will add keywords to font-lock-keywords. Calling with a non-nil value of mode is correct only in your ~/.emacs file.

If mode is nil, this function adds keywords to font-lock-keywords in the current buffer. This way of calling font-lock-add-keywords is usually used in mode hook functions.

By default, keywords are added at the beginning of font-lock-keywords. If the optional argument how is set, they are used to replace the value of font-lock-keywords. If how is any other non-nil value, they are added at the end of font-lock-keywords.

Some modes provide specialized support you can use in additional highlighting patterns. See the variables c-font-lock-extra-types, c++-font-lock-extra-types, and java-font-lock-extra-types, for example.

Warning: Major mode commands must not call font-lock-add-keywords under any circumstances, either directly or indirectly, except through their mode hooks. (Doing so would lead to incorrect behavior for some minor modes.) They should set up their rules for search-based fontification by setting font-lock-keywords.

Function: font-lock-remove-keywords mode keywords ¶

This function removes keywords from font-lock-keywords for the current buffer or for major mode mode. As in font-lock-add-keywords, mode should be a major mode command name or nil. All the caveats and requirements for font-lock-add-keywords apply here too. The argument keywords must exactly match the one used by the corresponding font-lock-add-keywords.

For example, the following code adds two fontification patterns for C mode: one to fontify the word ‘FIXME’, even in comments, and another to fontify the words ‘and’, ‘or’ and ‘not’ as keywords.

(font-lock-add-keywords 'c-mode
 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
   ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face)))

This example affects only C mode proper. To add the same patterns to C mode and all modes derived from it, do this instead:

(add-hook 'c-mode-hook
 (lambda ()
  (font-lock-add-keywords nil
   '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
     ("\\<\\(and\\|or\\|not\\)\\>" .
      font-lock-keyword-face)))))

User Option: font-lock-ignore ¶

This option defines conditions for selectively disabling fontifications due to certain Font Lock keywords. If non-nil, its value is a list of elements of the following form:

(symbol condition …)

Here, symbol is a symbol, usually a major or minor mode. The subsequent conditions of a symbol’s list element will be in effect if symbol is bound and its value is non-nil. For a mode’s symbol, it means that the current major mode is derived from that mode, or that minor mode is enabled in the buffer. When a condition is in effect, any fontifications caused by font-lock-keywords elements that match the condition will be disabled.

Each condition can be one of the following:

a symbol

This condition matches any element of Font Lock keywords that references the symbol. This is usually a face, but can be any symbol referenced by an element of the font-lock-keywords list. The symbol can contain wildcards: * matches any string in the symbol’ss name, ? matches a single character, and [char-set], where char-set is a string of one or more characters, matches a single character from the set.

a string

This condition matches any element of Font Lock keywords whose matcher is a regexp which matches the string. In other words, this condition matches a Font Lock rule which highlights the string. Thus, the string could be a specific program keyword whose highlighting you want to disable.

(pred function)

This condition matches any element of Font Lock keywords for which function, when called with the element as the argument, returns non-nil.

(not condition)

This matches if condition doesn’t.

(and condition …)

This matches if each of the conditions matches.

(or condition …)

This matches if at least one of the conditions matches.

(except condition)

This condition can only be used at top level or inside an or clause. It undoes the effect of a previously matching condition on the same level.

As an example, consider the following setting:

(setq font-lock-ignore
      '((prog-mode font-lock-*-face
                   (except help-echo))
        (emacs-lisp-mode (except ";;;###autoload)")
        (whitespace-mode whitespace-empty-at-bob-regexp)
        (makefile-mode (except *))))

Line by line, this does the following:

1. In all programming modes, disable fontifications due to all font-lock keywords that apply one of the standard font-lock faces (excluding strings and comments, which are covered by syntactic Font Lock).
2. However, keep any keywords that add a help-echo text property.
3. In Emacs Lisp mode, also keep the highlighting of autoload cookies, which would have been excluded by the first condition.
4. When whitespace-mode (a minor mode) is enabled, also don’t highlight an empty line at beginning of buffer.
5. Finally, in Makefile mode, don’t apply any conditions.