Llewellyn/conky
1
0
Fork 0
mirror of https://github.com/Llewellynvdm/conky.git synced 2024-12-26 04:17:33 +00:00
Code Issues Releases Activity

Refactor docs.

Browse Source
This commit is contained in:
Brenden Matthews 2022-09-30 17:20:17 -05:00 committed by Brenden Matthews
parent d80e9832a0
commit 5d22723937
10 changed files with 3131 additions and 3081 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

977
doc/config_settings.yaml
View File

@ -10,486 +10,501 @@
# * `args`: optional list of arguments
# * `default`: an optional default value, if applicable
---
- name: alignment
desc: |-
Aligned position on screen, may be top_left, top_right,
top_middle, bottom_left, bottom_right, bottom_middle, middle_left,
middle_middle, middle_right, or none (also can be abbreviated as tl,
tr, tm, bl, br, bm, ml, mm, mr). See also gap_x and gap_y.
- name: append_file
desc: Append the file given as argument.
- name: background
desc: |-
Boolean value, if true, Conky will be forked to background
when started.
- name: border_inner_margin
desc: |-
Inner border margin in pixels (the margin between the border
and text).
- name: border_outer_margin
desc: |-
Outer border margin in pixels (the margin between the border
and the edge of the window).
- name: border_width
desc: Border width in pixels.
- name: colorN
desc: |-
Predefine a color for use inside conky.text segments.
Substitute N by a digit between 0 and 9, inclusively. When specifying
the color value in hex, omit the leading hash (#).
- name: console_bar_fill
desc: "A character to fill the console bars."
default: "#"
- name: console_bar_unfill
desc: "A character to unfill the console bars."
default: "."
- name: console_graph_ticks
desc: |-
A comma-separated list of strings to use as the bars of a
graph output to console/shell. The first list item is used for the
minimum bar height and the last item is used for the maximum, e.g. \"
,_,=,#\".
- name: cpu_avg_samples
desc: The number of samples to average for CPU monitoring.
- name: default_bar_height
desc: |-
Specify a default height for bars.
default: 6
- name: default_bar_width
desc: |-
Specify a default width for bars. If not specified, the
default value is 0, which causes the bar to expand to fit the width of
your Conky window. If you set out_to_console = true, the default value
will be 10 for the text version of the bar.
default: 0
- name: default_color
desc: Default color and border color.
- name: default_gauge_height
desc: |-
Specify a default height for gauges.
default: 25
- name: default_gauge_width
desc: |-
Specify a default width for gauges.
default: 40
- name: default_graph_height
desc: |-
Specify a default height for graphs.
default: 25
- name: default_graph_width
desc: |-
Specify a default width for graphs. If not specified, the
default value is 0, which causes the graph to expand to fit the width
of your Conky window. If you set out_to_console = true, the text
version of the graph will actually have no width and you will need to
set a sensible default or set the height and width of each graph
individually.
default: 0
- name: default_outline_color
desc: Default outline color.
- name: default_shade_color
desc: Default shading color and border's shading color.
- name: detect_battery
desc: |-
One or more batteries to check in order to use
update_interval_on_battery (comma separated).
default: BAT0
- name: disable_auto_reload
desc: |-
Enable to disable the inotify-based auto config reload
feature.
- name: diskio_avg_samples
desc: The number of samples to average for disk I/O monitoring.
- name: display
desc: Specify an X display to connect to.
- name: double_buffer
desc: |-
Use the Xdbe extension? (eliminates flicker) It is highly
recommended to use own window with this one so double buffer won't be
so big.
- name: draw_blended
desc: |-
Boolean, blend when rendering drawn image? Some images blend
incorrectly breaking alpha with ARBG visuals. This provides a possible
work around by disabling blending.
default: yes
- name: draw_borders
desc: Draw borders around text.
- name: draw_graph_borders
desc: Draw borders around graphs.
- name: draw_outline
desc: Draw outlines.
- name: draw_shades
desc: Draw shades.
- name: extra_newline
desc: |-
Put an extra newline at the end when writing to stdout,
useful for writing to awesome's wiboxes.
- name: font
desc: Font name in X, xfontsel can be used to get a nice font.
- name: fontN
desc: |-
Predefine a font to be used in conky.text segments.
Substitute N by a number between 0 and 9 inclusive. Use the same
format as a font variable.
- name: forced_redraw
desc: Boolean value, if true, Conky will redraw everything when you switch the workspace. This may cause delays/flickering on some WMs.
- name: format_human_readable
desc: |-
If enabled, values which are in bytes will be printed in
human readable format (i.e., KiB, MiB, etc). If disabled, the number
of bytes is printed instead.
- name: gap_x
desc: |-
Gap, in pixels, between right or left border of screen, same
as passing -x at command line, e.g. gap_x 10. For other position
related stuff, see 'alignment'.
- name: gap_y
desc: |-
Gap, in pixels, between top or bottom border of screen, same
as passing -y at command line, e.g. gap_y 10. For other position
related stuff, see 'alignment'.
- name: github_token
desc: |-
Specify API token for GitHub notifications.
desc: |-
This is a listing of global configuration options for Conky. These are placed
in the `conky.config` section of your configuration file, before `conky.text`.
Create an API token at
https://github.com/settings/tokens/new?scopes=notifications&description=conky.
- name: hddtemp_host
desc: |-
Hostname to connect to for hddtemp objects.
default: "127.0.0.1"
- name: hddtemp_port
desc: Port to use for hddtemp connections.
default: 7634
- name: http_port
desc: |-
Port to listen to for HTTP connections. Default value is
10080, but is blocked by Firefox and Chrome, so you really want to
change it.
default: 10080
- name: http_refresh
desc: |-
When this is set the page generated with out_to_http will
automatically refresh each interval.
default: no
- name: if_up_strictness
desc: |-
How strict should if_up be when testing an interface for
being up? The value is one of up, link or address, to check for the
interface being solely up, being up and having link or being up,
having link and an assigned IP address.
- name: imap
desc: |-
Default global IMAP server. Default port is 143, default folder is 'INBOX',
default interval is 5 minutes, and default number of retries before giving
up is 5. If the password is supplied as '*', you will be prompted to enter
the password when Conky starts.
args:
- host
- user
- pass
- [-i interval (in seconds)]
- [-f 'folder']
- [-p port]
- [-e 'command']
- [-r retries]
- name: imlib_cache_flush_interval
desc: Interval (in seconds) to flush Imlib2 cache.
- name: imlib_cache_size
desc: |-
Imlib2 image cache size, in bytes. Increase this value if you use $image
lots. Set to 0 to disable the image cache.
default: 4194304
- name: lowercase
desc: Boolean value, if true, text is rendered in lower case.
- name: lua_draw_hook_post
desc: |-
This function, if defined, will be called by Conky through
each iteration after drawing to the window. Requires X support. Takes
any number of optional arguments. Use this hook for drawing things on
top of what Conky draws. Conky puts 'conky_' in front of function_name
to prevent accidental calls to the wrong function unless you place
'conky_' in front of it yourself.
args:
- function_name
- [function arguments]
- name: lua_draw_hook_pre
desc: |-
This function, if defined, will be called by Conky through
each iteration before drawing to the window. Requires X support. Takes
any number of optional arguments. Use this hook for drawing things on
top of what Conky draws. Conky puts 'conky_' in front of function_name
to prevent accidental calls to the wrong function unless you place
'conky_' in front of it yourself.
args:
- function_name
- [function arguments]
- name: lua_load
desc: Loads the Lua scripts separated by spaces.
- name: lua_shutdown_hook
desc: |-
This function, if defined, will be called by Conky at
shutdown or when the configuration is reloaded. Use this hook to clean
up after yourself, such as freeing memory which has been allocated by
external libraries via Lua. Conky puts 'conky_' in front of
function_name to prevent accidental calls to the wrong function unless
you place 'conky_' in front of it yourself.
args:
- function_name
- [function arguments]
- name: lua_startup_hook
desc: |-
This function, if defined, will be called by Conky at
startup or when the configuration is reloaded. Use this hook to
initialize values, or for any run-once applications. Conky puts
'conky_' in front of function_name to prevent accidental calls to the
wrong function unless you place 'conky_' in front of it yourself.
args:
- function_name
- [function arguments]
- name: mail_spool
desc: Mail spool for mail checking.
- name: max_port_monitor_connections
desc: |-
Allow each port monitor to track at most this many
connections.
default: 256
- name: max_text_width
desc: |-
When a line in the output contains 'width' chars and the end
isn't reached, the next char will start on a new line. If you want to
make sure that lines don't get broken, set 'width' to 0.
args:
- seconds
- name: max_user_text
desc: |-
Maximum size of user text buffer in bytes, i.e. text inside
conky.text section in config file.
default: 16384
args:
- seconds
- name: maximum_width
desc: Maximum width of window.
args:
- seconds
- name: minimum_height
desc: Minimum height of the window.
args:
- seconds
- name: minimum_width
desc: Minimum width of window.
args:
- seconds
- name: mpd_host
desc: Host of MPD server.
- name: mpd_password
desc: MPD server password.
- name: mpd_port
desc: Port of MPD server.
- name: music_player_interval
desc: |-
Music player thread update interval.
default: update interval
- name: mysql_db
desc: MySQL database to use.
default: mysql
- name: mysql_host
desc: Host of MySQL server
default: localhost
- name: mysql_password
desc: |-
Password of the MySQL user. Place it between \"-chars. When
this is not set there is no password used.
- name: mysql_port
desc: Port of MySQL server.
default: 0
- name: mysql_user
desc: |-
MySQL user name to use when connecting to the server.
Defaults to your username.
- name: net_avg_samples
desc: The number of samples to average for net data.
- name: no_buffers
desc: Subtract (file system) buffers from used memory.
- name: nvidia_display
desc: |-
The display that the nvidia variable will used.
default: $DISPLAY
- name: out_to_console
desc: Print text to stdout.
- name: out_to_http
desc: Let conky act as a small http-server serving its text.
- name: out_to_ncurses
desc: |-
Print text in the console, but use ncurses so that conky can
print the text of a new update over the old text. (In the future this
will provide more useful things).
- name: out_to_stderr
desc: Print text to stderr.
- name: out_to_x
desc: |-
When set to no, there will be no output in X (useful when
you also use things like out_to_console). If you set it to no, make
sure that it's placed before all other X-related setting (take the
first line of your configfile to be sure).
default: yes
- name: override_utf8_locale
desc: Force UTF8. Requires XFT.
- name: overwrite_file
desc: Overwrite the file given as argument.
- name: own_window
desc: Boolean, create own window to draw.
- name: own_window_argb_value
desc: |-
When ARGB visuals are enabled, this use this to modify the
alpha value used. Valid range is 0-255, where 0 is 0% opacity, and 255
is 100% opacity.
- name: own_window_argb_visual
desc: |-
Boolean, use ARGB visual? ARGB can be used for real
transparency, note that a composite manager is required for real
transparency. This option will not work as desired (in most cases) in
conjunction with 'own_window_type override'.
- name: own_window_class
desc: Manually set the WM_CLASS name.
default: Conky
- name: own_window_colour
desc: |-
If own_window_transparent no, set a specified background
colour. Takes either a hex value (e.g. '#ffffff'),
a shorthand hex value (e.g. '#fff'), or a valid RGB name (see `/usr/lib/X11/rgb.txt`).
default: black
args:
- seconds
- name: own_window_hints
desc: |-
If own_window is yes, you may use these window manager hints
to affect the way Conky displays. Notes: Use own_window_type desktop
as another way to implement many of these hints implicitly. If you use
own_window_type override, window manager hints have no meaning and are
ignored.
args:
- seconds
- name: own_window_title
desc: |-
Manually set the window name.
default: "conky (<hostname>)"
- name: own_window_transparent
desc: |-
Boolean, set transparency? If ARGB visual is enabled, sets
background opacity to 0%.
- name: own_window_type
desc: |-
if own_window is yes, you may specify type normal, desktop,
dock, panel or override. Desktop windows are special
windows that have no window decorations; are always visible on your
desktop; do not appear in your pager or taskbar; and are sticky across
all workspaces. Panel windows reserve space along a desktop edge, just
like panels and taskbars, preventing maximized windows from
overlapping them. The edge is chosen based on the alignment option.
Override windows are not under the control of the window manager.
Hints are ignored. This type of window can be useful for certain
situations.
default: normal
- name: pad_percents
desc: Pad percentages to this many decimals (0 = no padding).
- name: pop3
desc: |-
Default global POP3 server. Arguments are: \"host user pass
[-i interval (in seconds)] [-p port] [-e 'command'] [-r retries]\".
Default port is 110, default interval is 5 minutes, and default number
of retries before giving up is 5. If the password is supplied as '*',
you will be prompted to enter the password when Conky starts.
args:
- host
- user
- pass
- [-i interval (in seconds)]
- [-p port]
- [-e 'command']
- [-r retries]
- name: short_units
desc: |-
Shortens units to a single character (kiB->k, GiB->G,
etc.).
default: no
- name: show_graph_range
desc: Shows the time range covered by a graph.
- name: show_graph_scale
desc: Shows the maximum value in scaled graphs.
- name: stippled_borders
desc: Border stippling (dashing) in pixels.
- name: temperature_unit
desc: |-
Desired output unit of all objects displaying a temperature.
Parameters are either `fahrenheit` or `celsius`.
default: celsius
- name: templateN
desc: |-
Define a template for later use inside conky.text segments.
Substitute N by a digit between 0 and 9, inclusively. The value of the
variable is being inserted into the stuff inside conky.text at the
corresponding position, but before some substitutions are applied:
The default configuration file location is `~/.config/conky/conky.conf` or
`${sysconfdir}/conky/conky.conf`. On most systems, `$sysconfdir` is `/etc`,
and you can find the sample config file there in
`/etc/conky/conky.conf`.
* `\\n` -> newline
* `\\` -> backslash
* `\\ ` -> space
* `\\N` -> template argument N (starting from 1)
- name: text_buffer_size
desc: |-
Size of the standard text buffer (default is 256 bytes).
This buffer is used for intermediary text, such as individual lines,
output from $exec vars, and various other variables. Increasing the
size of this buffer can drastically reduce Conky's performance, but
will allow for more text display per variable. The size of this buffer
cannot be smaller than the default value of 256 bytes.
args:
- seconds
- name: times_in_seconds
desc: |-
If true, variables that output times output a number that
represents seconds. This doesn't affect $time, $tztime and $utime.
- name: top_cpu_separate
desc: |-
If true, cpu in top will show usage of one processor's
power. If false, cpu in top will show the usage of all processors'
power combined.
- name: top_name_verbose
desc: |-
If true, top name shows the full command line of each
process, including arguments (whenever possible). Otherwise, only the
basename is displayed. Default value is false.
- name: top_name_width
desc: Width for $top name value (defaults to 15 characters).
- name: total_run_times
desc: |-
Total number of times for Conky to update before quitting.
Zero makes Conky run forever.
- name: units_spacer
desc: String to place between values and units.
default: ""
- name: update_interval
desc: Update interval.
args:
- seconds
- name: update_interval_on_battery
desc: Update interval when running on battery power.
args:
- seconds
- name: uppercase
desc: Boolean value, if true, text is rendered in upper case.
- name: use_spacer
desc: |-
Adds spaces around certain objects to stop them from moving
other things around. Arguments are left, right, and none (default).
The old true/false values are deprecated and default to right/none
respectively. Note that this only helps if you are using a mono font,
such as Bitstream Vera Sans Mono.
default: none
- name: use_xft
desc: Use Xft (anti-aliased font and stuff).
- name: xftalpha
desc: Alpha of Xft font. Must be a value at or between 1 and 0.
- name: xinerama_head
desc: Specify a Xinerama head.
You might want to copy the default config to `~/.config/conky/conky.conf` and
then start modifying it. Other configs can be found at
https://github.com/brndnmtthws/conky.
Optional arguments are generally denoted with paretheses (i.e., `(optional)`).
values:
- name: alignment
desc: |-
Aligned position on screen, may be top_left, top_right,
top_middle, bottom_left, bottom_right, bottom_middle, middle_left,
middle_middle, middle_right, or none (also can be abbreviated as tl,
tr, tm, bl, br, bm, ml, mm, mr). See also gap_x and gap_y.
- name: append_file
desc: Append the file given as argument.
- name: background
desc: |-
Boolean value, if true, Conky will be forked to background
when started.
- name: border_inner_margin
desc: |-
Inner border margin in pixels (the margin between the border
and text).
- name: border_outer_margin
desc: |-
Outer border margin in pixels (the margin between the border
and the edge of the window).
- name: border_width
desc: Border width in pixels.
- name: colorN
desc: |-
Predefine a color for use inside conky.text segments.
Substitute N by a digit between 0 and 9, inclusively. When specifying
the color value in hex, omit the leading hash (#).
- name: console_bar_fill
desc: "A character to fill the console bars."
default: "#"
- name: console_bar_unfill
desc: "A character to unfill the console bars."
default: "."
- name: console_graph_ticks
desc: |-
A comma-separated list of strings to use as the bars of a
graph output to console/shell. The first list item is used for the
minimum bar height and the last item is used for the maximum, e.g. \"
,_,=,#\".
- name: cpu_avg_samples
desc: The number of samples to average for CPU monitoring.
- name: default_bar_height
desc: |-
Specify a default height for bars.
default: 6
- name: default_bar_width
desc: |-
Specify a default width for bars. If not specified, the
default value is 0, which causes the bar to expand to fit the width of
your Conky window. If you set out_to_console = true, the default value
will be 10 for the text version of the bar.
default: 0
- name: default_color
desc: Default color and border color.
- name: default_gauge_height
desc: |-
Specify a default height for gauges.
default: 25
- name: default_gauge_width
desc: |-
Specify a default width for gauges.
default: 40
- name: default_graph_height
desc: |-
Specify a default height for graphs.
default: 25
- name: default_graph_width
desc: |-
Specify a default width for graphs. If not specified, the
default value is 0, which causes the graph to expand to fit the width
of your Conky window. If you set out_to_console = true, the text
version of the graph will actually have no width and you will need to
set a sensible default or set the height and width of each graph
individually.
default: 0
- name: default_outline_color
desc: Default outline color.
- name: default_shade_color
desc: Default shading color and border's shading color.
- name: detect_battery
desc: |-
One or more batteries to check in order to use
update_interval_on_battery (comma separated).
default: BAT0
- name: disable_auto_reload
desc: |-
Enable to disable the inotify-based auto config reload
feature.
- name: diskio_avg_samples
desc: The number of samples to average for disk I/O monitoring.
- name: display
desc: Specify an X display to connect to.
- name: double_buffer
desc: |-
Use the Xdbe extension? (eliminates flicker) It is highly
recommended to use own window with this one so double buffer won't be
so big.
- name: draw_blended
desc: |-
Boolean, blend when rendering drawn image? Some images blend
incorrectly breaking alpha with ARBG visuals. This provides a possible
work around by disabling blending.
default: yes
- name: draw_borders
desc: Draw borders around text.
- name: draw_graph_borders
desc: Draw borders around graphs.
- name: draw_outline
desc: Draw outlines.
- name: draw_shades
desc: Draw shades.
- name: extra_newline
desc: |-
Put an extra newline at the end when writing to stdout,
useful for writing to awesome's wiboxes.
- name: font
desc: Font name in X, xfontsel can be used to get a nice font.
- name: fontN
desc: |-
Predefine a font to be used in conky.text segments.
Substitute N by a number between 0 and 9 inclusive. Use the same
format as a font variable.
- name: forced_redraw
desc: Boolean value, if true, Conky will redraw everything when you switch the workspace. This may cause delays/flickering on some WMs.
- name: format_human_readable
desc: |-
If enabled, values which are in bytes will be printed in
human readable format (i.e., KiB, MiB, etc). If disabled, the number
of bytes is printed instead.
- name: gap_x
desc: |-
Gap, in pixels, between right or left border of screen, same
as passing -x at command line, e.g. gap_x 10. For other position
related stuff, see 'alignment'.
- name: gap_y
desc: |-
Gap, in pixels, between top or bottom border of screen, same
as passing -y at command line, e.g. gap_y 10. For other position
related stuff, see 'alignment'.
- name: github_token
desc: |-
Specify API token for GitHub notifications.
Create an API token at
https://github.com/settings/tokens/new?scopes=notifications&description=conky.
- name: hddtemp_host
desc: |-
Hostname to connect to for hddtemp objects.
default: "127.0.0.1"
- name: hddtemp_port
desc: Port to use for hddtemp connections.
default: 7634
- name: http_port
desc: |-
Port to listen to for HTTP connections. Default value is
10080, but is blocked by Firefox and Chrome, so you really want to
change it.
default: 10080
- name: http_refresh
desc: |-
When this is set the page generated with out_to_http will
automatically refresh each interval.
default: no
- name: if_up_strictness
desc: |-
How strict should if_up be when testing an interface for
being up? The value is one of up, link or address, to check for the
interface being solely up, being up and having link or being up,
having link and an assigned IP address.
- name: imap
desc: |-
Default global IMAP server. Default port is 143, default folder is 'INBOX',
default interval is 5 minutes, and default number of retries before giving
up is 5. If the password is supplied as '*', you will be prompted to enter
the password when Conky starts.
args:
- host
- user
- pass
- [-i interval (in seconds)]
- [-f 'folder']
- [-p port]
- [-e 'command']
- [-r retries]
- name: imlib_cache_flush_interval
desc: Interval (in seconds) to flush Imlib2 cache.
- name: imlib_cache_size
desc: |-
Imlib2 image cache size, in bytes. Increase this value if you use $image
lots. Set to 0 to disable the image cache.
default: 4194304
- name: lowercase
desc: Boolean value, if true, text is rendered in lower case.
- name: lua_draw_hook_post
desc: |-
This function, if defined, will be called by Conky through
each iteration after drawing to the window. Requires X support. Takes
any number of optional arguments. Use this hook for drawing things on
top of what Conky draws. Conky puts 'conky_' in front of function_name
to prevent accidental calls to the wrong function unless you place
'conky_' in front of it yourself.
args:
- function_name
- [function arguments]
- name: lua_draw_hook_pre
desc: |-
This function, if defined, will be called by Conky through
each iteration before drawing to the window. Requires X support. Takes
any number of optional arguments. Use this hook for drawing things on
top of what Conky draws. Conky puts 'conky_' in front of function_name
to prevent accidental calls to the wrong function unless you place
'conky_' in front of it yourself.
args:
- function_name
- [function arguments]
- name: lua_load
desc: Loads the Lua scripts separated by spaces.
- name: lua_shutdown_hook
desc: |-
This function, if defined, will be called by Conky at
shutdown or when the configuration is reloaded. Use this hook to clean
up after yourself, such as freeing memory which has been allocated by
external libraries via Lua. Conky puts 'conky_' in front of
function_name to prevent accidental calls to the wrong function unless
you place 'conky_' in front of it yourself.
args:
- function_name
- [function arguments]
- name: lua_startup_hook
desc: |-
This function, if defined, will be called by Conky at
startup or when the configuration is reloaded. Use this hook to
initialize values, or for any run-once applications. Conky puts
'conky_' in front of function_name to prevent accidental calls to the
wrong function unless you place 'conky_' in front of it yourself.
args:
- function_name
- [function arguments]
- name: mail_spool
desc: Mail spool for mail checking.
- name: max_port_monitor_connections
desc: |-
Allow each port monitor to track at most this many
connections.
default: 256
- name: max_text_width
desc: |-
When a line in the output contains 'width' chars and the end
isn't reached, the next char will start on a new line. If you want to
make sure that lines don't get broken, set 'width' to 0.
args:
- seconds
- name: max_user_text
desc: |-
Maximum size of user text buffer in bytes, i.e. text inside
conky.text section in config file.
default: 16384
args:
- seconds
- name: maximum_width
desc: Maximum width of window.
args:
- seconds
- name: minimum_height
desc: Minimum height of the window.
args:
- seconds
- name: minimum_width
desc: Minimum width of window.
args:
- seconds
- name: mpd_host
desc: Host of MPD server.
- name: mpd_password
desc: MPD server password.
- name: mpd_port
desc: Port of MPD server.
- name: music_player_interval
desc: |-
Music player thread update interval.
default: update interval
- name: mysql_db
desc: MySQL database to use.
default: mysql
- name: mysql_host
desc: Host of MySQL server
default: localhost
- name: mysql_password
desc: |-
Password of the MySQL user. Place it between \"-chars. When
this is not set there is no password used.
- name: mysql_port
desc: Port of MySQL server.
default: 0
- name: mysql_user
desc: |-
MySQL user name to use when connecting to the server.
Defaults to your username.
- name: net_avg_samples
desc: The number of samples to average for net data.
- name: no_buffers
desc: Subtract (file system) buffers from used memory.
- name: nvidia_display
desc: |-
The display that the nvidia variable will used.
default: $DISPLAY
- name: out_to_console
desc: Print text to stdout.
- name: out_to_http
desc: Let conky act as a small http-server serving its text.
- name: out_to_ncurses
desc: |-
Print text in the console, but use ncurses so that conky can
print the text of a new update over the old text. (In the future this
will provide more useful things).
- name: out_to_stderr
desc: Print text to stderr.
- name: out_to_x
desc: |-
When set to no, there will be no output in X (useful when
you also use things like out_to_console). If you set it to no, make
sure that it's placed before all other X-related setting (take the
first line of your configfile to be sure).
default: yes
- name: override_utf8_locale
desc: Force UTF8. Requires XFT.
- name: overwrite_file
desc: Overwrite the file given as argument.
- name: own_window
desc: Boolean, create own window to draw.
- name: own_window_argb_value
desc: |-
When ARGB visuals are enabled, this use this to modify the
alpha value used. Valid range is 0-255, where 0 is 0% opacity, and 255
is 100% opacity.
- name: own_window_argb_visual
desc: |-
Boolean, use ARGB visual? ARGB can be used for real
transparency, note that a composite manager is required for real
transparency. This option will not work as desired (in most cases) in
conjunction with 'own_window_type override'.
- name: own_window_class
desc: Manually set the WM_CLASS name.
default: Conky
- name: own_window_colour
desc: |-
If own_window_transparent no, set a specified background
colour. Takes either a hex value (e.g. '#ffffff'),
a shorthand hex value (e.g. '#fff'), or a valid RGB name (see `/usr/lib/X11/rgb.txt`).
default: black
args:
- seconds
- name: own_window_hints
desc: |-
If own_window is yes, you may use these window manager hints
to affect the way Conky displays. Notes: Use own_window_type desktop
as another way to implement many of these hints implicitly. If you use
own_window_type override, window manager hints have no meaning and are
ignored.
args:
- seconds
- name: own_window_title
desc: |-
Manually set the window name.
default: "conky (<hostname>)"
- name: own_window_transparent
desc: |-
Boolean, set transparency? If ARGB visual is enabled, sets
background opacity to 0%.
- name: own_window_type
desc: |-
if own_window is yes, you may specify type normal, desktop,
dock, panel or override. Desktop windows are special
windows that have no window decorations; are always visible on your
desktop; do not appear in your pager or taskbar; and are sticky across
all workspaces. Panel windows reserve space along a desktop edge, just
like panels and taskbars, preventing maximized windows from
overlapping them. The edge is chosen based on the alignment option.
Override windows are not under the control of the window manager.
Hints are ignored. This type of window can be useful for certain
situations.
default: normal
- name: pad_percents
desc: Pad percentages to this many decimals (0 = no padding).
- name: pop3
desc: |-
Default global POP3 server. Arguments are: `host user pass
[-i interval (in seconds)] [-p port] [-e 'command'] [-r retries]\".
Default port is 110, default interval is 5 minutes, and default number
of retries before giving up is 5. If the password is supplied as '*',
you will be prompted to enter the password when Conky starts.
args:
- host
- user
- pass
- [-i interval (in seconds)]
- [-p port]
- [-e 'command']
- [-r retries]
- name: short_units
desc: |-
Shortens units to a single character (kiB->k, GiB->G,
etc.).
default: no
- name: show_graph_range
desc: Shows the time range covered by a graph.
- name: show_graph_scale
desc: Shows the maximum value in scaled graphs.
- name: stippled_borders
desc: Border stippling (dashing) in pixels.
- name: temperature_unit
desc: |-
Desired output unit of all objects displaying a temperature.
Parameters are either `fahrenheit` or `celsius`.
default: celsius
- name: templateN
desc: |-
Define a template for later use inside conky.text segments.
Substitute N by a digit between 0 and 9, inclusively. The value of the
variable is being inserted into the stuff inside conky.text at the
corresponding position, but before some substitutions are applied:
* `\\n` -> newline
* `\\` -> backslash
* `\\ ` -> space
* `\\N` -> template argument N (starting from 1)
- name: text_buffer_size
desc: |-
Size of the standard text buffer (default is 256 bytes).
This buffer is used for intermediary text, such as individual lines,
output from $exec vars, and various other variables. Increasing the
size of this buffer can drastically reduce Conky's performance, but
will allow for more text display per variable. The size of this buffer
cannot be smaller than the default value of 256 bytes.
args:
- seconds
- name: times_in_seconds
desc: |-
If true, variables that output times output a number that
represents seconds. This doesn't affect $time, $tztime and $utime.
- name: top_cpu_separate
desc: |-
If true, cpu in top will show usage of one processor's
power. If false, cpu in top will show the usage of all processors'
power combined.
- name: top_name_verbose
desc: |-
If true, top name shows the full command line of each
process, including arguments (whenever possible). Otherwise, only the
basename is displayed. Default value is false.
- name: top_name_width
desc: Width for $top name value (defaults to 15 characters).
- name: total_run_times
desc: |-
Total number of times for Conky to update before quitting.
Zero makes Conky run forever.
- name: units_spacer
desc: String to place between values and units.
default: ""
- name: update_interval
desc: Update interval.
args:
- seconds
- name: update_interval_on_battery
desc: Update interval when running on battery power.
args:
- seconds
- name: uppercase
desc: Boolean value, if true, text is rendered in upper case.
- name: use_spacer
desc: |-
Adds spaces around certain objects to stop them from moving
other things around. Arguments are left, right, and none (default).
The old true/false values are deprecated and default to right/none
respectively. Note that this only helps if you are using a mono font,
such as Bitstream Vera Sans Mono.
default: none
- name: use_xft
desc: Use Xft (anti-aliased font and stuff).
- name: xftalpha
desc: Alpha of Xft font. Must be a value at or between 1 and 0.
- name: xinerama_head
desc: Specify a Xinerama head.

200
doc/lua.yaml
View File

@ -10,94 +10,114 @@
# * `args`: optional list of arguments
# * `default`: an optional default value, if applicable
---
- name: cairo_font_extents_t:create()
desc: |-
Call this function to return a new cairo_font_extents_t
structure. A creation function for this structure is not provided
by the cairo API. After calling this, you should use
tolua.takeownership() on the return value to ensure ownership is
passed properly.
- name: cairo_font_extents_t:destroy(structure)
desc: |-
Call this function to free memory allocated by
cairo_font_extents_t:create.
- name: cairo_matrix_t:create()
desc: |-
Call this function to return a new cairo_matrix_t structure.
A creation function for this structure is not provided by the
cairo API. After calling this, you should use
tolua.takeownership() on the return value to ensure ownership is
passed properly.
- name: cairo_matrix_t:destroy(structure)
desc: |-
Call this function to free memory allocated by
cairo_matrix_t:create.
- name: cairo_text_extents_t:create()
desc: |-
Call this function to return a new cairo_text_extents_t
structure. A creation function for this structure is not provided
by the cairo API. After calling this, you should use
tolua.takeownership() on the return value to ensure ownership is
passed properly.
- name: cairo_text_extents_t:destroy(structure)
desc: |-
Call this function to free memory allocated by
cairo_text_extents_t:create.
- name: conky_build_arch
desc: |-
A string containing the build architecture for this
particular instance of Conky.
- name: conky_build_date
desc: |-
A string containing the build date for this particular
instance of Conky.
- name: conky_build_info
desc: |-
A string containing the build info for this particular
instance of Conky, including the version, build date, and
architecture.
- name: conky_config
desc: |-
A string containing the path of the current Conky
configuration file.
- name: conky_info
desc: |-
This table contains some information about Conky's internal
data. The following table describes the values contained:
desc: |-
Conky features a Lua Programming API, and also ships with Lua bindings
for some useful libraries. Note that the bindings require tolua++, which
currently only compiles against Lua 5.1.
| Key | Value |
|-----------------|---------------------------------------|
| update_interval | Conky's update interval (in seconds). |
- name: conky_parse(string)
desc: |-
This function takes a string that is evaluated as per
Conky's TEXT section, and then returns a string with the
result.
- name: conky_set_update_interval(number)
desc: |-
Sets Conky's update interval (in seconds) to
'number'.
- name: conky_version
desc: |-
A string containing the version of the current instance of
Conky.
- name: conky_window
desc: |-
This table contains some information about Conky's window.
The following table describes the values contained:
NOTE: This table is only defined when X support is
enabled.
| Key | Value |
|---------------------|---------------------------------------------------------------------------------|
| drawable | Window's drawable (Xlib Drawable), requires Lua extras enabled at compile time. |
| visual | Window's visual (Xlib Visual), requires Lua extras enabled at compile time. |
| display | Window's display (Xlib Display), requires Lua extras enabled at compile time. |
| width | Window width (in pixels). |
| height | Window height (in pixels). |
| border_inner_margin | Window's inner border margin (in pixels). |
| border_outer_margin | Window's outer border margin (in pixels). |
| border_width | Window's border width (in pixels). |
| text_start_x | The x component of the starting coordinate of text drawing. |
| text_start_y | The y component of the starting coordinate of text drawing. |
| text_width | The width of the text drawing region. |
| text_height | The height of the text drawing region. |
To use Lua Conky, you first need to make sure you have a version of
Conky with Lua support enabled (`conky -v` will report this).
Conky defines certain global functions and variables which can be
accessed from Lua code running in Conky. Scripts must first be loaded
using the lua_load configuration option. You then call functions in Lua
via Conky's $lua, $lua_read, and Lua hooks.
Be careful when creating threaded objects through the Lua API. You could
wind up with a whole bunch of threads running if a thread is created
with each iteration.
NOTE: In order to accommodate certain features in the cairo library's
API, Conky will export a few additional functions for the creation of
certain structures. These are documented below.
values:
- name: cairo_font_extents_t:create()
desc: |-
Call this function to return a new cairo_font_extents_t
structure. A creation function for this structure is not provided
by the cairo API. After calling this, you should use
tolua.takeownership() on the return value to ensure ownership is
passed properly.
- name: cairo_font_extents_t:destroy(structure)
desc: |-
Call this function to free memory allocated by
cairo_font_extents_t:create.
- name: cairo_matrix_t:create()
desc: |-
Call this function to return a new cairo_matrix_t structure.
A creation function for this structure is not provided by the
cairo API. After calling this, you should use
tolua.takeownership() on the return value to ensure ownership is
passed properly.
- name: cairo_matrix_t:destroy(structure)
desc: |-
Call this function to free memory allocated by
cairo_matrix_t:create.
- name: cairo_text_extents_t:create()
desc: |-
Call this function to return a new cairo_text_extents_t
structure. A creation function for this structure is not provided
by the cairo API. After calling this, you should use
tolua.takeownership() on the return value to ensure ownership is
passed properly.
- name: cairo_text_extents_t:destroy(structure)
desc: |-
Call this function to free memory allocated by
cairo_text_extents_t:create.
- name: conky_build_arch
desc: |-
A string containing the build architecture for this
particular instance of Conky.
- name: conky_build_date
desc: |-
A string containing the build date for this particular
instance of Conky.
- name: conky_build_info
desc: |-
A string containing the build info for this particular
instance of Conky, including the version, build date, and
architecture.
- name: conky_config
desc: |-
A string containing the path of the current Conky
configuration file.
- name: conky_info
desc: |-
This table contains some information about Conky's internal
data. The following table describes the values contained:
| Key | Value |
|-----------------|---------------------------------------|
| update_interval | Conky's update interval (in seconds). |
- name: conky_parse(string)
desc: |-
This function takes a string that is evaluated as per
Conky's TEXT section, and then returns a string with the
result.
- name: conky_set_update_interval(number)
desc: |-
Sets Conky's update interval (in seconds) to
'number'.
- name: conky_version
desc: |-
A string containing the version of the current instance of
Conky.
- name: conky_window
desc: |-
This table contains some information about Conky's window.
The following table describes the values contained:
NOTE: This table is only defined when X support is
enabled.
| Key | Value |
|---------------------|---------------------------------------------------------------------------------|
| drawable | Window's drawable (Xlib Drawable), requires Lua extras enabled at compile time. |
| visual | Window's visual (Xlib Visual), requires Lua extras enabled at compile time. |
| display | Window's display (Xlib Display), requires Lua extras enabled at compile time. |
| width | Window width (in pixels). |
| height | Window height (in pixels). |
| border_inner_margin | Window's inner border margin (in pixels). |
| border_outer_margin | Window's outer border margin (in pixels). |
| border_width | Window's border width (in pixels). |
| text_start_x | The x component of the starting coordinate of text drawing. |
| text_start_y | The y component of the starting coordinate of text drawing. |
| text_width | The width of the text drawing region. |
| text_height | The height of the text drawing region. |

48
doc/man.md.j2
View File

@ -182,16 +182,9 @@ file.
# CONFIGURATION SETTINGS
Default configuration file location is *\~/.config/conky/conky.conf* or
*\${sysconfdir}/conky/conky.conf*. On most systems, sysconfdir is /etc,
and you can find the sample config file there in
*/etc/conky/conky.conf*.
{{ config_settings['desc'] }}
You might want to copy it to *\~/.config/conky/conky.conf* and then
start modifying it. Other configs can be found at
*https://github.com/brndnmtthws/conky*.
{% for item in config_settings %}
{% for item in config_settings['values'] %}
**{{ item.name }}** {% if item.args %}**{{ item.args | join(" ") }}**{% endif %}
: {{ item.desc | indent(width=4) }}
@ -203,18 +196,9 @@ start modifying it. Other configs can be found at
# OBJECTS/VARIABLES
Colours are parsed using XParsecolor(), there might be a list of them:
*/usr/share/X11/rgb.txt*. Colour can be also in #rrggbb format (hex).
{{ variables['desc'] }}
Some objects may create threads, and sometimes these threads will not be
destroyed until Conky terminates. There is no way to destroy or clean up
threads while Conky is running. For example, if you use an MPD variable,
the MPD thread will keep running until Conky dies. Some threaded objects
will use one of the parameters as a \'key\', so that you only have 1
relevant thread running (for example, the \$curl, \$rss and \$weather
objects launch one thread per URI).
{% for item in variables %}
{% for item in variables['values'] %}
**{{ item.name }}** {% if item.args %}**{{ item.args | join(" ") }}**{% endif %}
: {{ item.desc | indent(width=4) }}
@ -226,29 +210,9 @@ objects launch one thread per URI).
# LUA API
Conky features a Lua Programming API, and also ships with Lua bindings
for some useful libraries. Note that the bindings require tolua++, which
currently only compiles against Lua 5.1.
{{ lua['desc'] }}
To use Lua Conky, you first need to make sure you have a version of
Conky with Lua support enabled (\`\`conky -v\'\' will report this).
Conky defines certain global functions and variables which can be
accessed from Lua code running in Conky. Scripts must first be loaded
using the lua_load configuration option. You then call functions in Lua
via Conky\'s \$lua, \$lua_read, and Lua hooks.
Be careful when creating threaded objects through the Lua API. You could
wind up with a whole bunch of threads running if a thread is created
with each iteration.
At this time, the Lua API should not be considered stable and may change
drastically from one release to another as it matures.
NOTE: In order to accommodate certain features in the cairo library\'s
API, Conky will export a few additional functions for the creation of
certain structures. These are documented below.
{% for item in lua %}
{% for item in lua['values'] %}
**{{ item.name }}** {% if item.args %}**{{ item.args | join(" ") }}**{% endif %}
: {{ item.desc | indent(width=4) }}

4839
doc/variables.yaml
View File

File diff suppressed because it is too large Load Diff

83
web/components/Docs.tsx
View File

@ -1,42 +1,69 @@
import { Doc } from '../utils/doc-utils'
import { Documentation } from '../utils/doc-utils'
import { Link } from 'react-feather'
export interface DocsProps {
docs: Doc[]
docs: Documentation
braces: boolean
assign: boolean
}
export default function Docs({ docs }: DocsProps) {
export default function Docs({ docs, braces, assign }: DocsProps) {
return (
<div className="prose dark:prose-invert prose-lg lg:prose-xl">
{docs.map((doc) => (
<div
id={doc.name}
key={doc.name}
className="scroll-mt-16 target:bg-rose-300 target:dark:bg-rose-900 hover:bg-slate-100 dark:hover:bg-slate-800 my-4"
>
<div className="flex">
<div className="p-2">
<a href={`#${doc.name}`}>
<Link size={16} />
</a>
</div>
<div className="flex-col p-1">
<code className="text-lg p-1 bg-fuchsia-200 dark:bg-fuchsia-900 font-bold">
{doc.name}
</code>
<div
className="py-2"
dangerouslySetInnerHTML={{ __html: doc.desc }}
/>
{doc.default && (
<div dangerouslySetInnerHTML={{ __html: docs.desc }} />
<div>
{docs.values.map((doc) => (
<div
id={doc.name}
key={doc.name}
className="scroll-mt-16 target:bg-rose-300 target:dark:bg-rose-900 hover:bg-slate-100 dark:hover:bg-slate-800 my-4"
>
<div className="flex">
<div className="px-2 py-3">
<a href={`#${doc.name}`}>
<Link size={20} />
</a>
</div>
<div className="flex-col p-1">
<div>
Default: <code>{doc.default}</code>
{braces && <code>$&#123;</code>}
<code className="text-lg p-1 mx-1 bg-fuchsia-200 dark:bg-fuchsia-900 font-bold">
{doc.name}
</code>
{typeof doc.args != 'undefined' && doc.args.length > 0 && (
<>
{assign && <code>=</code>}
<em>
{doc.args.map((arg) => (
<code
className="text-lg p-1 mx-1 bg-slate-200 dark:bg-slate-800"
key={arg}
>
{arg}
</code>
))}
</em>
</>
)}
{braces && <code>&#125;</code>}
</div>
)}
<div
className="py-2"
dangerouslySetInnerHTML={{ __html: doc.desc }}
/>
{typeof doc.default != 'undefined' && (
<div>
Default:{' '}
<code className="px-1 mx-1 bg-slate-200 dark:bg-slate-800">
{doc.default}
</code>
</div>
)}
</div>
</div>
</div>
</div>
))}
))}
</div>
</div>
)
}

26
web/documents/about.mdx
View File

@ -3,17 +3,17 @@ title: About
description: What's Conky all about?
---
Conky is a system monitor for X originally based on torsmo. Since its
inception, Conky has changed significantly from its predecessor, while
maintaining simplicity and configurability. Conky can display just about
anything, either on your root desktop or in its own window. Not only
does Conky have many built-in objects, it can also display just about
any piece of information by using scripts and other external programs.
Conky is a system monitor for X. Conky can display just about anything, either
on your root desktop or in its own window. Not only does Conky have many
built-in objects, it can also display just about any piece of information by
using scripts and other external programs.
Conky has more than 250 built in objects, including support for a
plethora of OS stats (uname, uptime, CPU usage, mem usage, disk usage,
\"top\" like process stats, and network monitoring, just to name a few),
built in IMAP and POP3 support, built in support for many popular music
players (MPD, XMMS2, Audacious), and much much more. Conky can display
this info either as text, or using simple progress bars and graph
widgets, with different fonts and colours.
Conky has more than 250 built in objects, including support for a plethora of OS
stats (uname, uptime, CPU usage, mem usage, disk usage, `top` like process
stats, and network monitoring, just to name a few), built in IMAP and POP3
support, built in support for many popular music players (MPD, XMMS2,
Audacious), and much much more. Conky can display this info either as text, or
using simple progress bars and graph widgets, with different fonts and colours.
If you'd like to get involved, please visit the project on GitHub at
https://github.com/brndnmtthws/conky.

6
web/pages/config_settings.tsx
View File

@ -1,10 +1,10 @@
import Layout from '../components/Layout'
import SEO from '../components/SEO'
import { Doc, getConfigSettings } from '../utils/doc-utils'
import { getConfigSettings, Documentation } from '../utils/doc-utils'
import Docs from '../components/Docs'
export interface ConfigSettingsProps {
config_settings: Doc[]
config_settings: Documentation
}
export default function ConfigSettings(props: ConfigSettingsProps) {
@ -18,7 +18,7 @@ export default function ConfigSettings(props: ConfigSettingsProps) {
<div>
<h1 className="text-2xl">Configuration settings</h1>
</div>
<Docs docs={props.config_settings} />
<Docs docs={props.config_settings} braces={false} assign={true} />
</main>
</Layout>
)

6
web/pages/lua.tsx
View File

@ -1,10 +1,10 @@
import Layout from '../components/Layout'
import SEO from '../components/SEO'
import { getLua, Doc } from '../utils/doc-utils'
import { getLua, Documentation } from '../utils/doc-utils'
import Docs from '../components/Docs'
export interface LuaProps {
lua: Doc[]
lua: Documentation
}
export default function Lua(props: LuaProps) {
@ -15,7 +15,7 @@ export default function Lua(props: LuaProps) {
<div>
<h1 className="text-2xl">Lua API</h1>
</div>
<Docs docs={props.lua} />
<Docs docs={props.lua} braces={false} assign={false} />
</main>
</Layout>
)

6
web/pages/variables.tsx
View File

@ -1,10 +1,10 @@
import Layout from '../components/Layout'
import SEO from '../components/SEO'
import { getVariables, Doc } from '../utils/doc-utils'
import { getVariables, Documentation } from '../utils/doc-utils'
import Docs from '../components/Docs'
export interface VariablesProps {
variables: Doc[]
variables: Documentation
}
export default function Variables(props: VariablesProps) {
@ -18,7 +18,7 @@ export default function Variables(props: VariablesProps) {
<div>
<h1 className="text-2xl">Variables</h1>
</div>
<Docs docs={props.variables} />
<Docs docs={props.variables} braces={true} assign={false} />
</main>
</Layout>
)

21
web/utils/doc-utils.ts
View File

@ -9,32 +9,39 @@ import rehypeStringify from 'rehype-stringify'
const DOC_PATH = path.join(process.cwd(), '..', 'doc')
export interface Doc {
export interface Documentation {
desc: string
values: DocItem[]
}
export interface DocItem {
name: string
desc: string
default: string | undefined
args: string[]
}
function getDocumentation(source: string): Doc[] {
function getDocumentation(source: string): Documentation {
const configSettingsFile = fs.readFileSync(
path.join(DOC_PATH, source),
'utf-8'
)
const parsed = yaml.load(configSettingsFile.toString()) as Doc[]
const docs = parsed.map((c) => ({ ...c, desc: processMarkdown(c.desc) }))
const parsed = yaml.load(configSettingsFile.toString()) as Documentation
const docs = {
desc: processMarkdown(parsed.desc),
values: parsed.values.map((c) => ({ ...c, desc: processMarkdown(c.desc) })),
}
return docs
}
export function getConfigSettings(): Doc[] {
export function getConfigSettings(): Documentation {
return getDocumentation('config_settings.yaml')
}
export function getVariables(): Doc[] {
export function getVariables(): Documentation {
return getDocumentation('variables.yaml')
}
export function getLua(): Doc[] {
export function getLua(): Documentation {
return getDocumentation('lua.yaml')
}