git.sur5r.net Git - i3/i3.github.io/blob - docs/user-contributed/py3status.html.mako

   1 <%!
   2         section = "docs"
   3 %>
   4 <%inherit file="_templates/i3.mako" />
   5 <div id="content" class="usergen">
   6 <h1>User-contributed article: enhanced and extensible i3bar with py3status</h1>
   7
   8 <p>
   9 In the i3 documentation, the recommended tool for <a
  10 href="http://i3wm.org/docs/userguide.html#_displaying_a_status_line">displaying
  11 a status line is to use i3status</a> combined with i3bar.
  12 </p>
  13
  14 <p>
  15 While i3status is very efficient at what it does, it is by design limited to
  16 a few modules and does not allow you to inject your own scripts output on your
  17 i3bar. This is said pretty clearly on the i3status man page:
  18 </p>
  19
  20 <pre><tt>In i3status, we don’t want to implement process management again.
  21 Therefore, there is no module to run arbitrary scripts or commands.
  22 Instead, you should use your shell.</tt></pre>
  23
  24 <h2>Introducing py3status</h2>
  25
  26 <p>
  27 The goal of py3status is to fill this gap by allowing users to simply extend
  28 their i3bar while preserving their current i3status configuration. The main idea
  29 is to rely on i3status' strengths without adding any configuration on the user's
  30 side. py3status is thus a wrapper script for i3status and you can
  31 <a href="https://github.com/ultrabug/py3status/wiki"> read more on the wiki</a>.
  32 </p>
  33
  34 <h2>Requirements</h2>
  35
  36 <p>
  37 To achieve this, py3status uses the <a
  38 href="http://i3wm.org/docs/i3bar-protocol.html">i3bar protocol</a> so your
  39 i3status.conf should specify this as its output_format.
  40 </p>
  41
  42 <pre><tt>general {
  43     output_format = "i3bar"
  44 }</tt></pre>
  45
  46 <h2>Usage</h2>
  47
  48 <p>
  49 Using py3status is easy, no need to multi-pipe your scripts after i3status.
  50 Instead, just replace i3status in your current status_command by py3status.
  51 For example, if you're using your own i3status.conf, you need to change your
  52 i3 config file with:
  53 </p>
  54
  55 <pre><tt>status_command py3status -c ~/.i3/i3status.conf</tt></pre>
  56
  57 <h2>Display your own stuff</h2>
  58
  59 <p>
  60 py3status features a simple and straightforward plugin system which you can use
  61 to get your own output displayed on your i3bar. You can read more and view some
  62 examples <a
  63 href="https://github.com/ultrabug/py3status/wiki/Write-your-own-modules"> on the
  64 wiki</a>.
  65 </p>
  66
  67 <h2>Documentation</h2>
  68
  69 <p>
  70 You can read the full and up to date documentation on the <a
  71 href="https://github.com/ultrabug/py3status">py3status home page</a>.
  72 </p>