@@ -225,6 +225,20 @@ script as a wrapper, for example:
225225less --tabs 4 -RF "$@"
226226```
227227
228+## Troubleshooting
229+
230+### Terminals & colors
231+
232+`bat` handles terminals *with* and *without* truecolor support. However, the colors in the syntax
233+highlighting themes are not optimized for 8-bit colors and it is therefore strongly recommended
234+that you use a terminal with 24-bit truecolor support (`terminator`, `konsole`, `iTerm2`, ...).
235+See [this article](https://gist.github.com/XVilka/8346728) for more details and a full list of
236+terminals with truecolor support.
237+
238+Make sure that your truecolor terminal sets the `COLORTERM` variable to either `truecolor` or
239+`24bit`. Otherwise, `bat` will not be able to determine whether or not 24-bit escape sequences
240+are supported (and fall back to 8-bit colors).
241+
228242## Development
229243
230244```bash