.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "POLYBAR" "5" "May 06, 2022" "3.6.3" "Polybar User Manual"
.SH NAME
polybar \- configuration file for polybar(1)
.SH DESCRIPTION
.sp
The polybar configuration file defines the behavior and look of polybar. It uses
a variant of the \fI\%INI\fP file format.
The exact syntax is described below but first a small snippet to get familiar
with the syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[section_name]
; A comment
# Another comment

background = #ff992a
width = 90%
monitor = HDMI\-0

screenchange\-reload = false

; Use double quotes if you want to keep the surrounding space.
text = " Some text "
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When started \fBpolybar\fP will search for the config file in one of several
places in the following order:
.INDENT 0.0
.IP \(bu 2
If the \fB\-c\fP or \fB\-\-config\fP command line argument is specified, it will use
the path given there.
.IP \(bu 2
\fB$XDG_CONFIG_HOME/polybar/config\fP
.IP \(bu 2
\fB$XDG_CONFIG_HOME/polybar/config.ini\fP
.IP \(bu 2
\fB$HOME/.config/polybar/config\fP
.IP \(bu 2
\fB$HOME/.config/polybar/config.ini\fP
.IP \(bu 2
\fB$XDG_CONFIG_DIRS/polybar/config.ini\fP
.IP \(bu 2
\fB/etc/xdg/polybar/config.ini\fP (only if \fBXDG_CONFIG_DIRS\fP is not set)
.IP \(bu 2
\fB/etc/polybar/config.ini\fP
.UNINDENT
.SH SYNTAX
.sp
The entire config is line\-based so everything is constrained to a single line.
This means there are no multiline values or other multiline constructs (except
for sections).
Each line has one of four types:
.INDENT 0.0
.IP \(bu 2
Empty
.IP \(bu 2
Comment
.IP \(bu 2
Section Header
.IP \(bu 2
Key
.UNINDENT
.sp
Spaces at the beginning and end of each line will be ignored.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
In this context "spaces" include the regular space character as well as the
tab character and any other character for which \fBisspace(3)\fP returns
\fBtrue\fP (e.g. \fB\er\fP).
.UNINDENT
.UNINDENT
.sp
Any line that doesn\(aqt fit into one of these four types is a syntax error.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
It is recommended that \fIsection header\fP names and \fIkey\fP names only use
alphanumeric characters as well as dashes (\fB\-\fP), underscores (\fB_\fP) and
forward slashes (\fB/\fP).
.sp
In practice all characters are allowed except for spaces and any of these:
\fB"\(aq=;#[](){}:.$\e%\fP
.UNINDENT
.UNINDENT
.SS Section Headers
.sp
Sections are used to group config options together. For example each module is
defined in its own section.
.sp
A section is defined by placing the name of the section in square brackets
(\fB[\fP and \fB]\fP). For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[module/wm]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This declares a section with the name \fBmodule/wm\fP and all keys defined after
this line will belong to that section until a new section is declared.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
The first non\-empty and non\-comment line in the main config file must be a
section header. It cannot be a key because that key would not belong to any
section.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The following section names are reserved and cannot be used inside the config:
\fBself\fP, \fBroot\fP, and \fBBAR\fP\&.
.UNINDENT
.UNINDENT
.SS Keys
.sp
Keys are defined by assigning a value to a name like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
name = value
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This assigns \fBvalue\fP to the key \fBname\fP in whatever section this line is in.
Key names need to be unique per section.
If the value is enclosed by double\-quotes (\fB"\fP), the quotes will be ignored.
So the following still assigns \fBvalue\fP to \fBname\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
name = "value"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Spaces around the equal sign are ignored, the following are all equivalent:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
name=value
name = value
name =      value
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Because spaces at the beginning and end of the line are also ignored, if you
want your value to begin and/or end with a space, the value needs to be enclosed
in double\-quotes:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
name = " value "
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Here the value of the \fBname\fP key has a leading and trailing whitespace.
.sp
To treat characters with special meaning as literal characters, you need to
prepend them with the backslash (\fB\e\fP) escape character:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
name = "value\e\evalue\e\evalue"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Value of this key \fBname\fP results in \fBvalue\evalue\evalue\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The only character with a special meaning right now is the backslash character
(\fB\e\fP), which serves as the escape character.
More will be added in the future.
.UNINDENT
.UNINDENT
.SS Empty Lines & Comments
.sp
Empty lines and comment lines are ignored when reading the config file, they do
not affect polybar\(aqs behavior. Comment lines start with either the \fB;\fP or the
\fB#\fP character.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Inline comments are not supported. For example the following line does not end
with a comment, the value of \fBname\fP is actually set to \fBvalue ; comment\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
name = value ; comment
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH AUTHORS
.nf
Polybar was created by Michael Carlberg and is currently maintained by Patrick Ziegler.
Contributors can be listed on GitHub.
.fi
.sp
.SH SEE ALSO
.sp
\fBpolybar\fP(1),
\fBpolybar\-msg\fP(1)
.SH COPYRIGHT
2016-2022, Michael Carlberg & contributors
.\" Generated by docutils manpage writer.
.