]> git.sur5r.net Git - i3/i3/blobdiff - docs/userguide
Smart option added to hide_edge_borders config param (#2191) (#2191)
[i3/i3] / docs / userguide
index c98c25f9d98039772c4e92c53ff1d0a518cc3d5c..9abdd5b0cea8a631dfd45e89dc8f5306803073e0 100644 (file)
@@ -4,8 +4,9 @@ Michael Stapelberg <michael@i3wm.org>
 March 2013
 
 This document contains all the information you need to configure and use the i3
-window manager. If it does not, please check http://faq.i3wm.org/ first, then
-contact us on IRC (preferred) or post your question(s) on the mailing list.
+window manager. If it does not, please check https://www.reddit.com/r/i3wm/
+first, then contact us on IRC (preferred) or post your question(s) on the
+mailing list.
 
 == Default keybindings
 
@@ -33,15 +34,15 @@ above, just decline i3-config-wizard’s offer and base your config on
 == Using i3
 
 Throughout this guide, the keyword +$mod+ will be used to refer to the
-configured modifier. This is the Alt key (Mod1) by default, with the Windows
-key (Mod4) being a popular alternative.
+configured modifier. This is the Alt key (+Mod1+) by default, with the Windows
+key (+Mod4+) being a popular alternative.
 
 === Opening terminals and moving around
 
 One very basic operation is opening a new terminal. By default, the keybinding
-for this is $mod+Enter, that is Alt+Enter in the default configuration. By
-pressing $mod+Enter, a new terminal will be opened.  It will fill the whole
-space available on your screen.
+for this is +$mod+Enter+, that is Alt+Enter (+Mod1+Enter+) in the default
+configuration. By pressing +$mod+Enter+, a new terminal will be opened.  It
+will fill the whole space available on your screen.
 
 image:single_terminal.png[Single terminal]
 
@@ -55,9 +56,9 @@ image:two_terminals.png[Two terminals]
 To move the focus between the two terminals, you can use the direction keys
 which you may know from the editor +vi+. However, in i3, your homerow is used
 for these keys (in +vi+, the keys are shifted to the left by one for
-compatibility with most keyboard layouts). Therefore, +$mod+J+ is left, +$mod+K+
-is down, +$mod+L+ is up and `$mod+;` is right. So, to switch between the
-terminals, use +$mod+K+ or +$mod+L+. Of course, you can also use the arrow keys.
+compatibility with most keyboard layouts). Therefore, +$mod+j+ is left, +$mod+k+
+is down, +$mod+l+ is up and `$mod+;` is right. So, to switch between the
+terminals, use +$mod+k+ or +$mod+l+. Of course, you can also use the arrow keys.
 
 At the moment, your workspace is split (it contains two terminals) in a
 specific direction (horizontal by default). Every window can be split
@@ -114,7 +115,7 @@ create a keybinding for starting the application directly. See the section
 === Closing windows
 
 If an application does not provide a mechanism for closing (most applications
-provide a menu, the escape key or a shortcut like +Control+W+ to close), you
+provide a menu, the escape key or a shortcut like +Control+w+ to close), you
 can press +$mod+Shift+q+ to kill a window. For applications which support
 the WM_DELETE protocol, this will correctly close the application (saving
 any modifications or doing other cleanup). If the application doesn’t support
@@ -149,8 +150,10 @@ it does not yet exist.
 The easiest way to resize a container is by using the mouse: Grab the border
 and move it to the wanted size.
 
-See <<resizingconfig>> for how to configure i3 to be able to resize
-columns/rows with your keyboard.
+You can also use <<binding_modes>> to define a mode for resizing via the
+keyboard. To see an example for this, look at the
+https://github.com/i3/i3/blob/next/i3.config.keycodes[default config] provided
+by i3.
 
 === Restarting i3 inplace
 
@@ -177,7 +180,8 @@ around. By grabbing the borders and moving them you can resize the window. You
 can also do that by using the <<floating_modifier>>. Another way to resize
 floating windows using the mouse is to right-click on the titlebar and drag.
 
-For resizing floating windows with your keyboard, see <<resizingconfig>>.
+For resizing floating windows with your keyboard, see the resizing binding mode
+provided by the i3 https://github.com/i3/i3/blob/next/i3.config.keycodes[default config].
 
 Floating windows are always on top of tiling windows.
 
@@ -202,9 +206,8 @@ like this:
 image::tree-layout2.png["layout2",float="right"]
 image::tree-shot4.png["shot4",title="Two terminals on standard workspace"]
 
-=== Orientation and Split Containers
-
 [[OrientationSplit]]
+=== Orientation and Split Containers
 
 It is only natural to use so-called +Split Containers+ in order to build a
 layout when using a tree as data structure. In i3, every +Container+ has an
@@ -288,7 +291,7 @@ with a text editor.
 
 On first start (and on all following starts, unless you have a configuration
 file), i3 will offer you to create a configuration file. You can tell the
-wizard to use either Alt (Mod1) or Windows (Mod4) as modifier in the config
+wizard to use either Alt (+Mod1+) or Windows (+Mod4+) as modifier in the config
 file. Also, the created config file will use the key symbols of your current
 keyboard layout. To start the wizard, use the command +i3-config-wizard+.
 Please note that you must not have +~/.i3/config+, otherwise the wizard will
@@ -306,7 +309,6 @@ a # and can only be used at the beginning of a line:
 -------------------
 
 [[fonts]]
-
 === Fonts
 
 i3 has support for both X core fonts and FreeType fonts (through Pango) to
@@ -339,7 +341,6 @@ font pango:Terminus 11px
 --------------------------------------------------------------
 
 [[keybindings]]
-
 === Keyboard bindings
 
 A keyboard binding makes i3 execute a command (see below) upon pressing a
@@ -404,7 +405,6 @@ corresponding group. For backwards compatibility, the group “Mode_switch” is
 alias for Group2.
 
 [[mousebindings]]
-
 === Mouse bindings
 
 A mouse binding makes i3 execute a command upon pressing a specific mouse
@@ -441,8 +441,59 @@ bindsym button9 move left
 bindsym button8 move right
 --------------------------------
 
-[[floating_modifier]]
+[[binding_modes]]
+=== Binding modes
+
+You can have multiple sets of bindings by using different binding modes. When
+you switch to another binding mode, all bindings from the current mode are
+released and only the bindings defined in the new mode are valid for as long as
+you stay in that binding mode. The only predefined binding mode is +default+,
+which is the mode i3 starts out with and to which all bindings not defined in a
+specific binding mode belong.
+
+Working with binding modes consists of two parts: defining a binding mode and
+switching to it. For these purposes, there are one config directive and one
+command, both of which are called +mode+. The directive is used to define the
+bindings belonging to a certain binding mode, while the command will switch to
+the specified mode.
+
+It is recommended to use binding modes in combination with <<variables>> in
+order to make maintenance easier. Below is an example of how to use a binding
+mode.
+
+Note that it is advisable to define bindings for switching back to the default
+mode.
+
+Note that it is possible to use <<pango_markup>> for binding modes, but you
+need to enable it explicitly by passing the +--pango_markup+ flag to the mode
+definition.
+
+*Syntax*:
+----------------------------
+# config directive
+mode [--pango_markup] <name>
+
+# command
+mode <name>
+----------------------------
+
+*Example*:
+------------------------------------------------------------------------
+# Press $mod+o followed by either f, t, Esc or Return to launch firefox,
+# thunderbird or return to the default mode, respectively.
+set $mode_launcher Launch: [f]irefox [t]hunderbird
+bindsym $mod+o mode "$mode_launcher"
+
+mode "$mode_launcher" {
+    bindsym f exec firefox
+    bindsym t exec thunderbird
+
+    bindsym Esc mode "default"
+    bindsym Return mode "default"
+}
+------------------------------------------------------------------------
 
+[[floating_modifier]]
 === The floating modifier
 
 To move floating windows with your mouse, you can either grab their titlebar
@@ -554,15 +605,18 @@ new_window pixel 3
 ---------------------
 
 
-=== Hiding vertical borders
+[[_hiding_vertical_borders]]
+=== Hiding borders adjacent to the screen edges
 
-You can hide vertical borders adjacent to the screen edges using
+You can hide container borders adjacent to the screen edges using
 +hide_edge_borders+. This is useful if you are using scrollbars, or do not want
-to waste even two pixels in displayspace. Default is none.
+to waste even two pixels in displayspace. The "smart" setting hides borders on
+workspaces with only one window visible, but keeps them on workspaces with
+multiple windows visible. Default is none.
 
 *Syntax*:
 -----------------------------------------------
-hide_edge_borders none|vertical|horizontal|both
+hide_edge_borders none|vertical|horizontal|both|smart
 -----------------------------------------------
 
 *Example*:
@@ -570,9 +624,8 @@ hide_edge_borders none|vertical|horizontal|both
 hide_edge_borders vertical
 ----------------------
 
-=== Arbitrary commands for specific windows (for_window)
-
 [[for_window]]
+=== Arbitrary commands for specific windows (for_window)
 
 With the +for_window+ command, you can let i3 execute any command when it
 encounters a specific window. This can be used to set windows to floating or to
@@ -599,9 +652,8 @@ for_window [title="x200: ~/work"] floating enable
 
 The valid criteria are the same as those for commands, see <<command_criteria>>.
 
-=== Don't focus window upon opening
-
 [[no_focus]]
+=== Don't focus window upon opening
 
 When a new window appears, it will be focused. The +no_focus+ directive allows preventing
 this from happening and must be used in combination with <<command_criteria>>.
@@ -624,6 +676,7 @@ no_focus <criteria>
 no_focus [window_role="pop-up"]
 -------------------------------
 
+[[variables]]
 === Variables
 
 As you learned in the section about keyboard bindings, you will have
@@ -649,9 +702,40 @@ absolutely no plans to change this. If you need a more dynamic configuration
 you should create a little script which generates a configuration file and run
 it before starting i3 (for example in your +~/.xsession+ file).
 
-=== Automatically putting clients on specific workspaces
+Also see <<xresources>> to learn how to create variables based on resources
+loaded from the X resource database.
+
+[[xresources]]
+=== X resources
+
+<<variables>> can also be created using a value configured in the X resource
+database. This is useful, for example, to avoid configuring color values within
+the i3 configuration. Instead, the values can be configured, once, in the X
+resource database to achieve an easily maintainable, consistent color theme
+across many X applications.
+
+Defining a resource will load this resource from the resource database and
+assign its value to the specified variable. A fallback must be specified in
+case the resource cannot be loaded from the database.
+
+*Syntax*:
+----------------------------------------------------
+set_from_resource $<name> <resource_name> <fallback>
+----------------------------------------------------
+
+*Example*:
+----------------------------------------------------------------------------
+# The ~/.Xresources should contain a line such as
+#     *color0: #121212
+# and must be loaded properly, e.g., by using
+#     xrdb ~/.Xresources
+# This value is picked up on by other applications (e.g., the URxvt terminal
+# emulator) and can be used in i3 like this:
+set_from_resource $black i3wm.color0 #000000
+----------------------------------------------------------------------------
 
 [[assign_workspace]]
+=== Automatically putting clients on specific workspaces
 
 To automatically make a specific window show up on a specific workspace, you
 can use an *assignment*. You can match windows by using any criteria,
@@ -736,7 +820,7 @@ keyword. These commands will be run in order.
 
 See <<command_chaining>> for details on the special meaning of +;+ (semicolon)
 and +,+ (comma): they chain commands together in i3, so you need to use quoted
-strings if they appear in your command.
+strings (as shown in <<exec_quoting>>) if they appear in your command.
 
 *Syntax*:
 ---------------------------------------
@@ -756,7 +840,6 @@ exec --no-startup-id urxvt
 The flag --no-startup-id is explained in <<exec>>.
 
 [[workspace_screen]]
-
 === Automatically putting workspaces on specific screens
 
 If you assign clients to workspaces, it might be handy to put the
@@ -788,9 +871,9 @@ workspace "2: vim" output VGA1
 You can change all colors which i3 uses to draw the window decorations.
 
 *Syntax*:
-------------------------------------------------------
-<colorclass> <border> <background> <text> <indicator>
-------------------------------------------------------
+--------------------------------------------------------------------
+<colorclass> <border> <background> <text> <indicator> <child_border>
+--------------------------------------------------------------------
 
 Where colorclass can be one of:
 
@@ -815,20 +898,20 @@ client.background::
 Colors are in HTML hex format (#rrggbb), see the following example:
 
 *Examples (default colors)*:
----------------------------------------------------------
-# class                 border  backgr. text    indicator
-client.focused          #4c7899 #285577 #ffffff #2e9ef4
-client.focused_inactive #333333 #5f676a #ffffff #484e50
-client.unfocused        #333333 #222222 #888888 #292d2e
-client.urgent           #2f343a #900000 #ffffff #900000
-client.placeholder      #000000 #0c0c0c #ffffff #000000
+----------------------------------------------------------------------
+# class                 border  backgr. text    indicator child_border
+client.focused          #4c7899 #285577 #ffffff #2e9ef4   #285577
+client.focused_inactive #333333 #5f676a #ffffff #484e50   #5f676a
+client.unfocused        #333333 #222222 #888888 #292d2e   #222222
+client.urgent           #2f343a #900000 #ffffff #900000   #900000
+client.placeholder      #000000 #0c0c0c #ffffff #000000   #0c0c0c
 
 client.background       #ffffff
----------------------------------------------------------
+----------------------------------------------------------------------
 
 Note that for the window decorations, the color around the child window is the
-background color, and the border color is only the two thin lines at the top of
-the window.
+"child_border", and "border" color is only the two thin lines around the
+titlebar.
 
 The indicator color is used for indicating where a new window will be opened.
 For horizontal split containers, the right border will be painted in indicator
@@ -1015,9 +1098,8 @@ force_display_urgency_hint <timeout> ms
 force_display_urgency_hint 500 ms
 ---------------------------------
 
-=== Focus on window activation
-
 [[focus_on_window_activation]]
+=== Focus on window activation
 
 If a window is activated, e.g., via +google-chrome www.google.com+, it may request
 to take focus. Since this may not preferable, different reactions can be configured.
@@ -1042,6 +1124,7 @@ focus::
 none::
     The window will neither be focused, nor be marked urgent.
 
+[[show_marks]]
 === Drawing marks on window decoration
 
 If activated, marks on windows are drawn in their window decoration. However,
@@ -1061,17 +1144,20 @@ show_marks yes
 --------------
 
 [[line_continuation]]
-
 === Line continuation
 
 Config files support line continuation, meaning when you end a line in a
 backslash character (`\`), the line-break will be ignored by the parser. This
 feature can be used to create more readable configuration files.
+Commented lines are not continued.
 
 *Examples*:
 -------------------
 bindsym Mod1+f \
 fullscreen toggle
+
+# this line is not continued \
+bindsym Mod1+F fullscreen toggle
 -------------------
 
 == Configuring i3bar
@@ -1190,7 +1276,7 @@ the windows key). The default value for the hidden_state is hide.
 -------------------------
 mode dock|hide|invisible
 hidden_state hide|show
-modifier <Modifier>
+modifier <Modifier>|none
 ------------------------
 
 *Example*:
@@ -1202,7 +1288,8 @@ bar {
 }
 ----------------
 
-Available modifiers are Mod1-Mod5, Shift, Control (see +xmodmap(1)+).
+Available modifiers are Mod1-Mod5, Shift, Control (see +xmodmap(1)+). You can
+also use "none" if you don't want any modifier to trigger this behavior.
 
 === Mouse button commands
 
@@ -1323,6 +1410,11 @@ NetworkManager, VLC, Pidgin, etc. can place little icons.
 You can configure on which output (monitor) the icons should be displayed or
 you can turn off the functionality entirely.
 
+You can use multiple +tray_output+ directives in your config to specify a list
+of outputs on which you want the tray to appear. The first available output in
+that list as defined by the order of the directives will be used for the tray
+output.
+
 *Syntax*:
 ---------------------------------
 tray_output none|primary|<output>
@@ -1455,8 +1547,8 @@ bar {
 
 Specifies whether the current binding mode indicator should be shown or not.
 This is useful if you want to hide the workspace buttons but still be able
-to see the current binding mode indicator.
-For an example of a +mode+ definition, see <<resizingconfig>>.
+to see the current binding mode indicator. See <<binding_modes>> to learn what
+modes are and how to use them.
 
 The default is to show the mode indicator.
 
@@ -1483,6 +1575,15 @@ statusline::
        Text color to be used for the statusline.
 separator::
        Text color to be used for the separator.
+focused_background::
+       Background color of the bar on the currently focused monitor output. If
+       not used, the color will be taken from +background+.
+focused_statusline::
+       Text color to be used for the statusline on the currently focused
+       monitor output. If not used, the color will be taken from +statusline+.
+focused_separator::
+       Text color to be used for the separator on the currently focused
+       monitor output. If not used, the color will be taken from +separator+.
 focused_workspace::
        Border, background and text color for a workspace button when the workspace
        has focus.
@@ -1584,25 +1685,25 @@ The criteria which are currently implemented are:
 
 class::
        Compares the window class (the second part of WM_CLASS). Use the
-       special value +__focused__+ to match all windows having the same window
+       special value +\_\_focused__+ to match all windows having the same window
        class as the currently focused window.
 instance::
        Compares the window instance (the first part of WM_CLASS). Use the
-       special value +__focused__+ to match all windows having the same window
+       special value +\_\_focused__+ to match all windows having the same window
        instance as the currently focused window.
 window_role::
        Compares the window role (WM_WINDOW_ROLE). Use the special value
-       +__focused__+ to match all windows having the same window role as the
+       +\_\_focused__+ to match all windows having the same window role as the
        currently focused window.
 window_type::
        Compare the window type (_NET_WM_WINDOW_TYPE). Possible values are
        +normal+, +dialog+, +utility+, +toolbar+, +splash+, +menu+, +dropdown_menu+,
-       +popup_menu+ and +tooltip+.
+       +popup_menu+, +tooltip+ and +notification+.
 id::
        Compares the X11 window ID, which you can get via +xwininfo+ for example.
 title::
-       Compares the X11 window title (_NET_WM_NAME or WM_NAME as fallback).
-       Use the special value +__focused__+ to match all windows having the
+       Compares the X11 window title (\_NET_WM_NAME or WM_NAME as fallback).
+       Use the special value +\_\_focused__+ to match all windows having the
        same window title as the currently focused window.
 urgent::
        Compares the urgent state of the window. Can be "latest" or "oldest".
@@ -1610,20 +1711,22 @@ urgent::
        (The following aliases are also available: newest, last, recent, first)
 workspace::
        Compares the workspace name of the workspace the window belongs to. Use
-       the special value +__focused__+ to match all windows in the currently
+       the special value +\_\_focused__+ to match all windows in the currently
        focused workspace.
 con_mark::
-       Compares the mark set for this container, see <<vim_like_marks>>.
+        Compares the marks set for this container, see <<vim_like_marks>>. A
+        match is made if any of the container's marks matches the specified
+        mark.
 con_id::
        Compares the i3-internal container ID, which you can get via the IPC
-       interface. Handy for scripting.
+       interface. Handy for scripting. Use the special value +\_\_focused__+
+       to match only the currently focused window.
 
 The criteria +class+, +instance+, +role+, +title+, +workspace+ and +mark+ are
 actually regular expressions (PCRE). See +pcresyntax(3)+ or +perldoc perlre+ for
 information on how to use them.
 
 [[exec]]
-
 === Executing applications (exec)
 
 What good is a window manager if you can’t actually start any applications?
@@ -1633,7 +1736,7 @@ searched in your +$PATH+.
 
 See <<command_chaining>> for details on the special meaning of +;+ (semicolon)
 and +,+ (comma): they chain commands together in i3, so you need to use quoted
-strings if they appear in your command.
+strings (as shown in <<exec_quoting>>) if they appear in your command.
 
 *Syntax*:
 --------------------------------
@@ -1657,6 +1760,27 @@ launching. So, if an application is not startup-notification aware (most GTK
 and Qt using applications seem to be, though), you will end up with a watch
 cursor for 60 seconds.
 
+[[exec_quoting]]
+If the command to be executed contains a +;+ (semicolon) and/or a +,+ (comma),
+the entire command must be quoted. For example, to have a keybinding for the
+shell command +notify-send Hello, i3+, you would add an entry to your
+configuration file like this:
+
+*Example*:
+------------------------------
+# Execute a command with a comma in it
+bindsym $mod+p exec "notify-send Hello, i3"
+------------------------------
+
+If however a command with a comma and/or semicolon itself requires quotes, you
+must escape the internal quotation marks with double backslashes, like this:
+
+*Example*:
+------------------------------
+# Execute a command with a comma, semicolon and internal quotes
+bindsym $mod+p exec "notify-send \\"Hello, i3; from $USER\\""
+------------------------------
+
 === Splitting containers
 
 The split command makes the current window a split container. Split containers
@@ -1666,20 +1790,24 @@ get placed below the current one (splitv).
 
 If you apply this command to a split container with the same orientation,
 nothing will happen. If you use a different orientation, the split container’s
-orientation will be changed (if it does not have more than one window). Use
-+layout toggle split+ to change the layout of any split container from splitv
-to splith or vice-versa.
+orientation will be changed (if it does not have more than one window).
+The +toggle+ option will toggle the orientation of the split container if it
+contains a single window. Otherwise it makes the current window a split
+container with opposite orientation compared to the parent container.
+Use +layout toggle split+ to change the layout of any split container from
+splitv to splith or vice-versa.
 
 *Syntax*:
--------------------------
-split vertical|horizontal
--------------------------
+--------------------------------
+split vertical|horizontal|toggle
+--------------------------------
 
 *Example*:
-------------------------------
+-------------------------------
 bindsym $mod+v split vertical
 bindsym $mod+h split horizontal
-------------------------------
+bindsym $mod+t split toggle
+-------------------------------
 
 === Manipulating layout
 
@@ -1721,7 +1849,6 @@ bindsym $mod+t floating toggle
 --------------
 
 [[_focusing_moving_containers]]
-
 === Focusing containers
 
 To change focus, you can use the +focus+ command. The following options are
@@ -1837,8 +1964,11 @@ for_window [instance=notepad] sticky enable
 === Changing (named) workspaces/moving to workspaces
 
 To change to a specific workspace, use the +workspace+ command, followed by the
-number or name of the workspace. To move containers to specific workspaces, use
-+move container to workspace+.
+number or name of the workspace. Pass the optional flag
++--no-auto-back-and-forth+ to disable <<back_and_forth>> for this specific call
+only.
+
+To move containers to specific workspaces, use +move container to workspace+.
 
 You can also switch to the next and previous workspace with the commands
 +workspace next+ and +workspace prev+, which is handy, for example, if you have
@@ -1866,16 +1996,16 @@ back_and_forth+; likewise, you can move containers to the previously focused
 workspace using +move container to workspace back_and_forth+.
 
 *Syntax*:
------------------------------------
+--------------------------------------------------------------------------------
 workspace next|prev|next_on_output|prev_on_output
 workspace back_and_forth
-workspace <name>
-workspace number <name>
+workspace [--no-auto-back-and-forth] <name>
+workspace [--no-auto-back-and-forth] number <name>
 
-move [window|container] [to] workspace <name>
-move [window|container] [to] workspace number <name>
+move [--no-auto-back-and-forth] [window|container] [to] workspace <name>
+move [--no-auto-back-and-forth] [window|container] [to] workspace number <name>
 move [window|container] [to] workspace prev|next|current
------------------------------------
+--------------------------------------------------------------------------------
 
 *Examples*:
 -------------------------
@@ -1957,9 +2087,8 @@ bindsym $mod+r exec i3-input -F 'rename workspace to "%s"' -P 'New name: '
 See <<move_to_outputs>> for how to move a container/workspace to a different
 RandR output.
 
-=== Moving containers/workspaces to RandR outputs
-
 [[move_to_outputs]]
+=== Moving containers/workspaces to RandR outputs
 
 To move a container to another RandR output (addressed by names like +LVDS1+ or
 +VGA1+) or to a RandR output identified by a specific direction (like +left+,
@@ -1981,7 +2110,7 @@ bindsym $mod+x move workspace to output right
 bindsym $mod+x move container to output VGA1
 --------------------------------------------------------
 
-=== Moving containers/workspaces to marks
+=== Moving containers/windows to marks
 
 To move a container to another container with a specific mark (see <<vim_like_marks>>),
 you can use the following command.
@@ -2002,7 +2131,6 @@ for_window [instance="tabme"] move window to mark target
 --------------------------------------------------------
 
 [[resizingconfig]]
-
 === Resizing containers/windows
 
 If you want to resize containers/windows using your keyboard, you can use the
@@ -2023,38 +2151,12 @@ many percentage points a *tiling container* should be grown or shrunk (the
 default is 10 percentage points). Note that +resize set+ will only work for
 floating containers.
 
-I recommend using the resize command inside a so called +mode+:
+It is recommended to define bindings for resizing in a dedicated binding mode.
+See <<binding_modes>> and the example in the i3
+https://github.com/i3/i3/blob/next/i3.config.keycodes[default config] for more
+context.
 
-.Example: Configuration file, defining a mode for resizing
-----------------------------------------------------------------------
-mode "resize" {
-        # These bindings trigger as soon as you enter the resize mode
-
-        # Pressing left will shrink the window’s width.
-        # Pressing right will grow the window’s width.
-        # Pressing up will shrink the window’s height.
-        # Pressing down will grow the window’s height.
-        bindsym j           resize shrink width 10 px or 10 ppt
-        bindsym k           resize grow height 10 px or 10 ppt
-        bindsym l           resize shrink height 10 px or 10 ppt
-        bindsym semicolon   resize grow width 10 px or 10 ppt
-
-        # same bindings, but for the arrow keys
-        bindsym Left        resize shrink width 10 px or 10 ppt
-        bindsym Down        resize grow height 10 px or 10 ppt
-        bindsym Up          resize shrink height 10 px or 10 ppt
-        bindsym Right       resize grow width 10 px or 10 ppt
-
-        # back to normal: Enter or Escape
-        bindsym Return mode "default"
-        bindsym Escape mode "default"
-}
-
-# Enter resize mode
-bindsym $mod+r mode "resize"
-----------------------------------------------------------------------
-
-*Example 2 - setting urxvt size to 640x480:*
+*Example*:
 ------------------------------------------------
 for_window [class="urxvt"] resize set 640 480
 ------------------------------------------------
@@ -2080,9 +2182,8 @@ with criteria for that.
 bindsym $mod+a [class="urxvt" title="VIM"] focus
 ------------------------------------------------
 
-=== VIM-like marks (mark/goto)
-
 [[vim_like_marks]]
+=== VIM-like marks (mark/goto)
 
 This feature is like the jump feature: It allows you to directly jump to a
 specific window (this means switching to the appropriate workspace and setting
@@ -2098,24 +2199,36 @@ for this purpose: It lets you input a command and sends the command to i3. It
 can also prefix this command and display a custom prompt for the input dialog.
 
 The additional +--toggle+ option will remove the mark if the window already has
-this mark, add it if the window has none or replace the current mark if it has
-another mark.
+this mark or add it otherwise. Note that you may need to use this in
+combination with +--add+ (see below) as any other marks will otherwise be
+removed.
+
+By default, a window can only have one mark. You can use the +--add+ flag to
+put more than one mark on a window.
 
-Refer to +show_marks+ if you don't want marks to be shown in the window decoration.
+Refer to <<show_marks>> if you don't want marks to be shown in the window decoration.
 
 *Syntax*:
-------------------------------
-mark [--toggle] <identifier>
+----------------------------------------------
+mark [--add|--replace] [--toggle] <identifier>
 [con_mark="identifier"] focus
 unmark <identifier>
-------------------------------
+----------------------------------------------
 
 *Example (in a terminal)*:
-------------------------------
-$ i3-msg mark irssi
-$ i3-msg '[con_mark="irssi"] focus'
-$ i3-msg unmark irssi
-------------------------------
+---------------------------------------------------------
+# marks the focused container
+mark irssi
+
+# focus the container with the mark "irssi"
+'[con_mark="irssi"] focus'
+
+# remove the mark "irssi" from whichever container has it
+unmark irssi
+
+# remove all marks on all firefox windows
+[class="(?i)firefox"] unmark
+---------------------------------------------------------
 
 ///////////////////////////////////////////////////////////////////
 TODO: make i3-input replace %s
@@ -2129,9 +2242,10 @@ bindsym $mod+g exec i3-input -p 'goto ' -l 1 -P 'Goto: '
 ---------------------------------------
 
 Alternatively, if you do not want to mess with +i3-input+, you could create
-seperate bindings for a specific set of labels and then only use those labels.
+separate bindings for a specific set of labels and then only use those labels.
 ///////////////////////////////////////////////////////////////////
 
+[[pango_markup]]
 === Window title format
 
 By default, i3 will simply print the X11 window title. Using +title_format+,
@@ -2141,7 +2255,10 @@ https://developer.gnome.org/pango/stable/PangoMarkupFormat.html[Pango markup]
 and the following placeholders which will be replaced:
 
 +%title+::
-    The X11 window title (_NET_WM_NAME or WM_NAME as fallback).
+    For normal windows, this is the X11 window title (_NET_WM_NAME or WM_NAME
+    as fallback). When used on containers without a window (e.g., a split
+    container inside a tabbed/stacked layout), this will be the tree
+    representation of the container (e.g., "H[xterm xterm]").
 +%class+::
     The X11 window class (second part of WM_CLASS). This corresponds to the
     +class+ criterion, see <<command_criteria>>.
@@ -2177,6 +2294,10 @@ and +border none+ to make the client borderless.
 
 There is also +border toggle+ which will toggle the different border styles.
 
+Note that "pixel" refers to logical pixel. On HiDPI displays, a logical pixel
+may be represented by multiple physical pixels, so +pixel 1+ might not
+necessarily translate into a single pixel row wide border.
+
 *Syntax*:
 -----------------------------------------------
 border normal|pixel [<n>]
@@ -2197,7 +2318,6 @@ bindsym $mod+u border none
 ----------------------------------------------
 
 [[shmlog]]
-
 === Enabling shared memory logging
 
 As described in http://i3wm.org/docs/debugging.html, i3 can log to a shared
@@ -2346,7 +2466,6 @@ bindsym $mod+Shift+b bar mode invisible bar-1
 ------------------------------------------------
 
 [[multi_monitor]]
-
 == Multiple monitors
 
 As you can see in the goal list on the website, i3 was specifically developed
@@ -2476,6 +2595,7 @@ position the window either at the top or at the bottom of the screen, depending
 on which hint the application sets. With i3bar, you can configure its position,
 see <<i3bar_position>>.
 
+[[presentations]]
 === Giving presentations (multi-monitor)
 
 When giving a presentation, you typically want the audience to see what you see
@@ -2484,7 +2604,6 @@ simple). For more complex presentations, you might want to have some notes
 which only you can see on your screen, while the audience can only see the
 slides.
 
-[[presentations]]
 ==== Case 1: everybody gets the same output
 This is the simple case. You connect your computer to the video projector,
 turn on both (computer and video projector) and configure your X server to