:experimental:

Several aspects of Newsboat can be configured via a _config_ file,
which is stored next to the _urls_ file.
A configuration line looks like this in general:

    <config-command> <arg1> ...

The configuration file can contain comments, which start with the `+#+` character and go as
far as the end of line.

****
*User contrib* Newsboat also comes with user contributed content like scripts and color
themes. The user contributed content can be found in
`/usr/share/doc/newsboat/contrib/`. End users are encouraged to take a look as
they may find something useful.
****

=== Example

An example configuration looks like this

----
# a comment
max-items        100 # such comments are possible, too
browser          links
show-read-feeds  no

unbind-key       R
bind             ^R feedlist reload-all
----

=== Splitting long lines into multiple ones

Settings such as <<_macro_support,macros>> and
<<ignore-article,`ignore-article`>> can be quite lengthy. A long line can be
broken into multiple ones using backslashes. A backslash must be the last
character on the line and will immediately concatenate it with the following
line. It's important that _nothing_ follows the `{backslash}` on the same line,
otherwise the `{backslash}` character is treated "as is". For example:

----
macro p open; \
reload; quit; \
quit;         \
quit -- "Opens, reloads then makes sure to quit newsboat"
----

Please note that a backslash only makes Newsboat ignore the following newline.
It doesn't do _anything_ else at all. For example, this nicely formatted
option:

----
ignore-article \
    "*" \
    "author =~ \"(\
        John Doe| \
        Mary Sue \
    )\""
----

_does not_ turn into this:

----
ignore-article "*" "author =~ \"(John Doe|Mary Sue)\""
----

Instead, as only newlines are removed, it turns to this:

----
ignore-article     "*"     "author =~ \"(        John Doe|         Mary Sue     )\""
----

For this reason, be conscious of where you're splitting the lines, because it
might matter.

=== Using Double Quotes

****
*TL;DR* Use double quotes for strings that contain spaces or double quotes.
Escape double quotes (use \") and backslashes (use \\). Don't escape stuff
outside of double quotes, and don't use single quotes for quoting — Newsboat
doesn't support that.
****

Many of Newsboat's options expect strings as arguments, be it commands,
passwords, dialog titles, URLs etc. Some options even take _multiple_ strings
at once. These strings can contain spaces, which might confuse Newsboat since
it already uses spaces to separate option names from option arguments.

To help Newsboat understand your intent, put such strings into double quotes:

    browser "firefox --new-tab %u"

What if you need a double quote inside a string? Escape it with a backslash:

    ocnews-password "UnbalancedQuotes\"AreSoFun!"

And what about the backslash itself? Escape it, too! Suppose you have a program
called `my favourite pager`, and you want to view articles with it. Newsboat
ultimately passes commands to the shell, and shell expects spaces to be escaped
if you want them preserved. But since Newsboat interprets backslashes, you have
to add _another_ layer of escaping. Thus, you end up with a command like this:

    pager "/usr/bin/my\\ favourite\\ pager"

=== Shell Evaluation

It is also possible to integrate the output of external commands
into the configuration. The text between two `{backtick}` backticks is evaluated
as shell command, and its output is used. This works like backtick evaluation in
Bourne-compatible shells and allows users to use external information from the
system within the configuration.

=== Escaping

Backticks and `+#+` characters can be escaped with a backslash
(e.g. `{backslash}{backtick}` and `{backslash}#`).
In this case, they are replaced with literal `{backtick}` or `+#+` in the
configuration.

=== Key Bindings

_New style key bindings described here are supported since Newsboat 2.39._

You can bind a key (or sequence of keys) to an operation (or a list of operations)
with the <<bind,`bind`>> configuration command.

The syntax for a binding looks like this:

    bind <key-sequence> <dialog>[,<dialog>] <operation-list> [-- "<description>"]


[WARNING]
.Limitations
====
Bindings that share a prefix must all have the same length; otherwise, only the
last binding is created.

For example:

```
bind ab everywhere …
bind abc everywhere …
```

will only create a binding for `abc`. Re-ordering the commands will create
a binding for `ab`.

This avoids ambiguity when `ab` is typed and Newsboat doesn't know if it should
run the binding for `ab` already or the user is going to press `c` next,
triggering the other binding.

To have both bindings, either:

* rename them to have different prefixes (e.g. `ab` and `bcd`), or

* make them the same length (e.g. rename `ab` to `abd` to match the length of
  `abc`).
====

*Key Sequence*

Lowercase keys, uppercase keys and special characters are written literally.

Key combinations with kbd:[Ctrl] are written using the caret `^`.
For instance kbd:[Ctrl+R] equals to `^R`.
Please be aware that all kbd:[Ctrl]-related key combinations need to be written in uppercase.

Alternatively, key combinations using kbd:[Shift] or kbd:[Ctrl] can be written like
`<S-a>` and `<C-a>`, for kbd:[Shift+A] and kbd:[Ctrl+A] respectively.
Note that this alternative syntax only works with the <<bind,`bind`>> command.
It is not supported with the older <<bind-key,`bind-key`>> command.

The following identifiers for special keys are supported:

- `<ENTER>` (Enter key)
- `<BACKSPACE>` (backspace key)
- `<LEFT>` (left cursor)
- `<RIGHT>` (right cursor)
- `<UP>` (up cursor)
- `<DOWN>` (down cursor)
- `<PPAGE>` (page up cursor)
- `<NPAGE>` (page down cursor)
- `<HOME>` (cursor to beginning of list/article)
- `<END>` (cursor to end of list/article)
- `<ESC>` (Esc key)
- `<TAB>` (Tab key)
- `<LT>` (`<` key)
- `<GT>` (`>` key)
- `<^>` (`^` key, can also be specified as just `^` if it is not followed by a letter)
- `<F1>` to `<F12>` (F1 key to F12 key)

Multiple keys can be placed in sequence. For example `gg` means pressing
kbd:[g] twice and `^O<ENTER>` means pressing kbd:[Ctrl+O] followed by
kbd:[Enter].
Pressing kbd:[Esc] will cancel a multi-key input.

*Dialog*

A dialog is a context in which the key binding is active.
Available dialogs are:

* `everywhere`
* `feedlist`
* `filebrowser`
* `help`
* `articlelist`
* `article`
* `tagselection`
* `filterselection`
* `urlview`
* `podboat`
* `dirbrowser`
* `searchresultslist`

Multiple dialogs can be specified with a comma in between. For example:

    bind k feedlist,articlelist,urlview up
    bind j feedlist,articlelist,urlview down

or using `everywhere` to apply the binding in all dialogs:

    bind k everywhere up
    bind j everywhere down

*Operation List*

Operations get executed when pressing the corresponding sequence of keys.
For a complete list of available operations see <<_newsboat_operations>> and <<_podboat_operations>>.

Multiple operations can be specified by writing them down separated by a semicolon.
Some operations allow specifying an argument, e.g. `set <config option> <config value>`
can be used to change a configuration option.

A sequence with two dashes followed by text between double quotes can be used
to add a description to a binding (e.g. `-- "some description"`). If present,
the description is shown in the help dialog.

In combination, this might look like:

    bind of everywhere set browser "firefox" ; open-in-browser -- "Open in Firefox"

The above example means that pressing kbd:[o] followed by kbd:[f] will change
the configured browser to `firefox` and then run the <<open-in-browser,`open-in-browser`>>
command to open the feed/article in the configured browser.

`bind` is similar to <<_macro_support,macros>> but is more flexible.
Macros are configured globally, whereas `bind` can be applied to specific dialogs.
Additionally, macros always require pressing 2 keys (<<macro-prefix,`macro-prefix`>>
followed by a key specific to the macro) while `bind` can specify a key-sequence of
any length.

=== Old Style Key Bindings

You can bind a single key to a single operation with the <<bind-key,`bind-key`>>
configuration command. This is an older, more limited form of keybinding syntax.
You can specify an optional dialog. This is the context in which the key binding is active.

The syntax for an old style key binding looks like this:

    bind-key <key> <operation> [<dialog>]

*Key*

Lowercase keys, uppercase keys and special characters are written literally.

Key combinations with kbd:[Ctrl] are written using the caret `^`.
For instance kbd:[Ctrl+R] equals to `^R`.
Please be aware that all kbd:[Ctrl]-related key combinations need to be written in uppercase.

The following identifiers for special keys are supported:

- `ENTER` (Enter key)
- `BACKSPACE` (backspace key)
- `LEFT` (left cursor)
- `RIGHT` (right cursor)
- `UP` (up cursor)
- `DOWN` (down cursor)
- `PPAGE` (page up cursor)
- `NPAGE` (page down cursor)
- `HOME` (cursor to beginning of list/article)
- `END` (cursor to end of list/article)
- `ESC` (Esc key)
- `TAB` (Tab key)
- `F1` to `F12` (F1 key to F12 key)

*Operation*

An operation gets executed when pressing the corresponding key.
For a complete list of available operations see <<_newsboat_operations>> and <<_podboat_operations>>.

*Dialog*

A dialog is a context in which the key binding is active.
Available dialogs are:

* `all` (default if not specified)
* `feedlist`
* `filebrowser`
* `help`
* `articlelist`
* `article`
* `tagselection`
* `filterselection`
* `urlview`
* `podboat`
* `dirbrowser`
* `searchresultslist`

=== Colors

It is possible to configure custom color settings in Newsboat. The basic configuration
syntax is:

	color <element> <foreground color> <background color> [<attribute> ...]

This means that if you configure colors for a certain element, you need to provide
a foreground color and a background color as a minimum. The following colors are
supported:

- `black`
- `red`
- `green`
- `yellow`
- `blue`
- `magenta`
- `cyan`
- `white`
- `default`
- `color<n>`, e.g. `color123`

The `default` color means that the terminal's default color will be used. The
`color<n>` color name (where `<n>` is a decimal number *not* starting with zero)
can be used if your terminal supports 256 colors (e.g. `gnome-terminal`, or `xterm`
with `TERM` set to `xterm-256color`). Newsboat contains support for 256 color
terminals since version 2.1. For a complete chart of colors and their
corresponding numbers, please see
https://www.calmar.ws/vim/256-xterm-24bit-rgb-color-chart.html[].

Optionally, you can also add one or more attributes. The following attributes are
supported:

- `standout`
- `underline`
- `reverse`
- `blink`
- `dim`
- `bold`
- `protect`
- `invis`

Currently, the following elements are supported:

- `background`: the application background
- `listnormal`: a normal list item
- `listfocus`: the currently selected list item
- `listnormal_unread`: an unread list item
- `listfocus_unread`: the currently selected unread list item
- `title` (_added in 2.25_): current dialog's title, which is usually at the
  top of the screen (but see <<show-title-bar,`show-title-bar`>> and
  <<swap-title-and-hints,`swap-title-and-hints`>>). If you don't specify
  a style for this element, then the `info` style is used
- `info`: the hints bar, which is usually at the bottom of the screen (but see
  <<show-keymap-hint,`show-keymap-hint`>> and
  <<swap-title-and-hints,`swap-title-and-hints`>>)
- `hint-key` (_added in 2.25_): a key in the hints bar. If you don't specify
  a style for this element, then the `info` style is used
- `hint-keys-delimiter` (_added in 2.25_): the comma that separates keys in the
  hints bar. If you don't specify a style for this element, then the `info`
  style is used
- `hint-separator` (_added in 2.25_): the colon separating keys from their
  descriptions in the hints bar. If you don't specify a style for this element,
  then the `info` style is used
- `hint-description` (_added in 2.25_): a description of a key in the hints
  bar. If you don't specify a style for this element, then the `info` style is
  used
- `article`: the article text
- `end-of-text-marker`: filler lines (~) below blocks of text

The default color configuration of Newsboat looks like this:

	color background          white   black
	color listnormal          white   black
	color listfocus           yellow  blue   bold
	color listnormal_unread   white   black  bold
	color listfocus_unread    yellow  blue   bold
	color title               yellow  blue   bold
	color info                yellow  blue   bold
	color hint-key            yellow  blue   bold
	color hint-keys-delimiter white   blue
	color hint-separator      white   blue   bold
	color hint-description    white   blue
	color article             white   black
