:editor word-wrap

Soft wrapping with language-aware indent

1. Description

This module adds a minor-mode +word-wrap-mode, which intelligently wraps long lines in the buffer without modifying the buffer content.

1.1. Maintainers

This module has no dedicated maintainers. Become a maintainer?

1.2. Module flags

This module has no flags.

1.3. Packages

1.4. Hacks

No hacks documented for this module.

2. Prerequisites

This module has no external prerequisites.

3. Usage

Word wrapping is not enabled by default.

Wrapping can be toggled in the current buffer with M-x +word-wrap-mode. The default doom bindings bind this to SPC t w for evil users.

To enable wrapping in a specific mode, add it to the appropriate hook in your config.el:

;; enable word-wrap in C/C++/ObjC/Java
(add-hook 'c-mode-common-hook #'+word-wrap-mode)

To customize the behaviour in a specific mode:

;; use a single indent in json-mode
(add-hook! 'json-mode-hook
  (setq-local +word-wrap-extra-indent 'single)
  (+word-wrap-mode +1))

To turn on word wrapping (almost) everywhere:

;; enable word-wrap (almost) everywhere
(+global-word-wrap-mode +1)

To disable global word-wrapping in a specific mode:

;; disable global word-wrap in emacs-lisp-mode
(add-to-list '+word-wrap-disabled-modes 'emacs-lisp-mode)

4. Configuration

Wrapped lines will be indented to match the preceding line. In code buffers, lines which are not inside a string or comment will have extra indentation as determined by +word-wrap-extra-indent. The default is to increase the indent by twice the major-mode indent.

The +word-wrap-extra-indent variable supports the following values:

  • double: indent by twice the major-mode indentation
  • single: indent by the major-mode indentation
  • a positive integer: indent by this fixed amount
  • a negative integer: dedent by this fixed amount
  • nil: no extra indent

This module also includes a global minor-mode +global-word-wrap-mode to automatically enable wrapping in most buffers. Wrapping will not be enabled in buffers whose major mode is marked “special”, or are listed in +word-wrap-disabled-modes.

The +word-wrap-text-modes variable lists modes which shouldn’t have any extra indentation, regardless of the +word-wrap-extra-indent setting. This is useful for modes which are primarily text, such as text-mode and markdown-mode.

The +word-wrap-visual-modes variable lists modes which should only enable visual-line-mode and not provide any prefix indentation. This is useful for modes like org-mode which handle prefix indentation themselves.

5. Troubleshooting

There are no known problems with this module. Report one?

6. TODO Appendix

This module has no appendix yet. Write one?