limelight.vim: dimming everything but the paragraph you are writing

What limelight.vim actually does to your buffer

The plugin implements one idea: while you write, the paragraph under the cursor stays at full contrast and everything around it is dimmed. The README calls this "hyperfocus-writing in Vim", and the effect is produced by highlight groups rather than by hiding text. Nothing is deleted, folded or moved. You can still scroll, search and select the dimmed regions; they simply stop competing for attention. The audience is narrow and specific: people who draft long prose in Vim, README files, articles, documentation, and who find a full screen of equally bright text distracting. It is not a code-reading aid, and the README gives no indication that it was designed for that. The plugin works on a 256-color terminal or in GVim, which is a real constraint rather than a footnote. On a plain 8-color terminal the dimming calculation has nothing to work with.

How the dimming is calculated, and where it breaks

Limelight does not pick a fixed gray. It reads the foreground color of the text around the cursor and computes a dimmed variant of it, which is why the README warns that "for some color schemes, Limelight may not be able to calculate the color for dimming down the surrounding paragraphs". When that happens the fix is manual: you declare the color yourself through g:limelight_conceal_ctermfg for terminals or g:limelight_conceal_guifg for GUI Vim. The option accepts either a color name or a numeric value, so both of these are valid and mean the same thing in different spaces.

let g:limelight_conceal_ctermfg = 'gray'
let g:limelight_conceal_ctermfg = 240
let g:limelight_conceal_guifg = 'DarkGray'
let g:limelight_conceal_guifg = '#777777'

Paragraph boundaries are not hardcoded either. The defaults assume blank lines separate paragraphs, and g:limelight_bop and g:limelight_eop let you redefine the beginning and end patterns for indented text with no blank line between blocks. That is a genuine design decision: the plugin treats paragraph structure as configuration, not as a fixed rule, which is more flexible than most writing plugins but also means you have to know your own document format. The dimming is applied as a highlight with priority 10 by default. The README notes that setting g:limelight_priority to -1 stops it from overruling hlsearch, which tells you the default behaviour does exactly that: search matches inside dimmed paragraphs are dimmed along with them.

Installing limelight.vim with vim-plug and turning it on

The README points at plugin managers rather than a manual install path, and gives vim-plug as the worked example. Add the line to your Vim configuration file, source it, then install.

Plug 'junegunn/limelight.vim'

:source %
:PlugInstall

After installation, :Limelight turns the effect on, :Limelight! turns it off, and :Limelight!! toggles between the two. An optional argument between 0.0 and 1.0 sets the dimming coefficient, so :Limelight 0.7 is dimmer than the default. If you would rather bind it to a key, the README offers plug mappings for both normal and visual mode, which also lets you apply the effect to a selected range only.

nmap <Leader>l <Plug>(Limelight)
xmap <Leader>l <Plug>(Limelight)

The default coefficient is 0.5, but you can change it globally with g:limelight_default_coefficient, shown in the README as 0.7. The other tuning knob worth knowing early is g:limelight_paragraph_span, default 0, which controls how many preceding and following paragraphs stay bright. Setting it to 1 keeps the neighbouring paragraphs visible instead of dimming everything except the current one.

The Goyo.vim pairing, and why the two are usually installed together

The README states that limelight.vim is "best served with Goyo.vim", another plugin by the same author. Goyo removes the surrounding interface, and Limelight removes the surrounding text. The documented integration is two autocommands that tie the dimming to Goyo's enter and leave events, so the effect switches on when you enter distraction-free mode and off when you leave.

autocmd! User GoyoEnter Limelight
autocmd! User GoyoLeave Limelight!

This is the intended workflow rather than an optional extra, and it shapes how the plugin should be judged. Used alone, Limelight dims text inside a normal Vim window full of splits and status lines. Used with Goyo, it dims text inside a window that has already been stripped down. The second arrangement is the one the author documents. If you do not want Goyo, Limelight still functions, but you are using it outside the configuration its README describes.

Where limelight.vim is the wrong tool

The most concrete limitation is the one the README admits: color calculation depends on your color scheme, and the fallback is manual configuration. That means a new user can install the plugin, run :Limelight, and see either no visible change or text that has become unreadable, with the README's only guidance being to define a conceal color. There is no diagnostic command documented for finding out which color scheme value failed. The second limitation follows from the default priority. Because Limelight overrules hlsearch unless you set g:limelight_priority to -1, search results inside dimmed paragraphs lose their highlight. If your writing workflow involves jumping between search matches in a long document, the default configuration works against you. Third, the plugin is aimed at prose. Paragraph detection based on blank lines or indentation patterns is a poor fit for source files where indentation carries meaning, and the README offers no guidance for that case. Finally, the 256-color or GVim requirement rules out minimal terminals and some remote sessions, and there is no documented grayscale fallback for them.

How it compares with simply editing in a narrow window

The obvious alternative is not another plugin but a different approach: open a second window or a split sized to the width of your text and ignore everything outside it. That costs nothing to install and works on any terminal, including 8-color ones. The difference in mechanism matters. A narrow split physically removes other text from view; Limelight leaves the whole buffer visible and reduces its contrast instead. That means you can still glance at surrounding paragraphs without moving the cursor, which is useful when you are revising rather than drafting, and it means your window layout stays untouched. The trade-off is that a narrow split gives a guaranteed result on any color scheme, while Limelight's result depends on the scheme being readable at reduced contrast. For editing code, the split approach also avoids the paragraph-detection problem entirely. The two are not mutually exclusive, and the README's own pairing with Goyo suggests the author expects Limelight to be layered on top of an already-reduced interface rather than used as the only form of focus.

Maintenance, licence and what an upgrade costs you

The repository is not archived, and the last push was on 2026-03-09. The project is MIT licensed, which permits use, modification and redistribution provided the copyright notice and permission notice are retained; that is a statement about the licence text, not legal advice, and anyone embedding the plugin in a distributed product should read the LICENSE file in the repository root themselves. There are no retrieved releases, so installation through a plugin manager tracks the master branch rather than a tagged version. In practice that means an upgrade is whatever the branch contains at the moment you run your manager's update command, and there is no version number to pin against. For a plugin of this size, with a documented option set that has stayed small, that is a manageable risk, but it is a real difference from a project that publishes releases. The configuration surface you own is the set of g:limelight_ variables plus the two autocommands, and those are the things to re-check after an update.

Editorial conclusion

Adopt limelight.vim if you write prose in Vim and your color scheme exposes usable foreground colors, or you are willing to set g:limelight_conceal_ctermfg or g:limelight_conceal_guifg by hand. Skip it if you work mostly in code, if you rely on hlsearch highlighting, or if you are on a terminal without 256-color support. Before committing, open a long document, run :Limelight 0.7, and check that the dimmed paragraphs are still legible rather than invisible.

Frequently asked questions

Official sources

1. Issues
2. junegunn/limelight.vim on GitHub
3. License: MIT
4. README