chore(docs): improve configuration docs (#656)

Improve the configuration documentation in `configs/conf.yml` (#656).
This commit is contained in:
Christopher Allen Lane 2022-08-26 13:11:15 -04:00
parent d773383f70
commit 5c5ed7344f
2 changed files with 78 additions and 54 deletions

View File

@ -28,34 +28,46 @@ formatter: terminal256
# 'more' is recommended on Windows # 'more' is recommended on Windows
pager: PAGER_PATH pager: PAGER_PATH
# The paths at which cheatsheets are available. Tags associated with a cheatpath # Cheatpaths are paths at which cheatsheets are available on your local
# are automatically attached to all cheatsheets residing on that path. # filesystem.
# #
# Whenever cheatsheets share the same title (like 'tar'), the most local # It is useful to sort cheatsheets into different cheatpaths for organizational
# cheatsheets (those which come later in this file) take precedent over the # purposes. For example, you might want one cheatpath for community
# less local sheets. This allows you to create your own "overides" for # cheatsheets, one for personal cheatsheets, one for cheatsheets pertaining to
# "upstream" cheatsheets. # your day job, one for code snippets, etc.
# #
# But what if you want to view the "upstream" cheatsheets instead of your own? # Cheatpaths are scoped, such that more "local" cheatpaths take priority over
# Cheatsheets may be filtered via 'cheat -t <tag>' in combination with other # more "global" cheatpaths. (The most global cheatpath is listed first in this
# commands. So, if you want to view the 'tar' cheatsheet that is tagged as # file; the most local is listed last.) For example, if there is a 'tar'
# 'community' rather than your own, you can use: cheat tar -t community # cheatsheet on both global and local paths, you'll be presented with the local
cheatpaths: # one by default. ('cheat -p' can be used to view cheatsheets from alternative
# Paths that come earlier are considered to be the most "global", and will # cheatpaths.)
# thus be overridden by more local cheatsheets. That being the case, you
# should probably list community cheatsheets first.
# #
# Note that the paths and tags listed below are placeholders. You may freely # Cheatpaths can also be tagged as "read only". This instructs cheat not to
# change them to suit your needs. # automatically create cheatsheets on a read-only cheatpath. Instead, when you
# would like to edit a read-only cheatsheet using 'cheat -e', cheat will
# perform a copy-on-write of that cheatsheet from a read-only cheatpath to a
# writeable cheatpath.
#
# This is very useful when you would like to maintain, for example, a
# "pristine" repository of community cheatsheets on one cheatpath, and an
# editable personal reponsity of cheatsheets on another cheatpath.
#
# Cheatpaths can be also configured to automatically apply tags to cheatsheets
# on certain paths, which can be useful for querying purposes.
# Example: 'cheat -t work jenkins'.
# #
# Community cheatsheets must be installed separately, though you may have # Community cheatsheets must be installed separately, though you may have
# downloaded them automatically when installing 'cheat'. If not, you may # downloaded them automatically when installing 'cheat'. If not, you may
# download them here: # download them here:
# #
# https://github.com/cheat/cheatsheets # https://github.com/cheat/cheatsheets
# cheatpaths:
# Once downloaded, ensure that 'path' below points to the location at which # Cheatpath properties mean the following:
# you downloaded the community cheatsheets. # 'name': the name of the cheatpath (view with 'cheat -d', filter with 'cheat -p')
# 'path': the filesystem path of the cheatsheet directory (view with 'cheat -d')
# 'tags': tags that should be automatically applied to sheets on this path
# 'readonly': shall user-created ('cheat -e') cheatsheets be saved here?
- name: community - name: community
path: COMMUNITY_PATH path: COMMUNITY_PATH
tags: [ community ] tags: [ community ]
@ -69,13 +81,13 @@ cheatpaths:
readonly: false readonly: false
# While it requires no configuration here, it's also worth noting that # While it requires no configuration here, it's also worth noting that
# 'cheat' will automatically append directories named '.cheat' within the # cheat will automatically append directories named '.cheat' within the
# current working directory to the 'cheatpath'. This can be very useful if # current working directory to the 'cheatpath'. This can be very useful if
# you'd like to closely associate cheatsheets with, for example, a directory # you'd like to closely associate cheatsheets with, for example, a directory
# containing source code. # containing source code.
# #
# Such "directory-scoped" cheatsheets will be treated as the most "local" # Such "directory-scoped" cheatsheets will be treated as the most "local"
# cheatsheets, and will override less "local" cheatsheets. Likewise, # cheatsheets, and will override less "local" cheatsheets. Similarly,
# directory-scoped cheatsheets will always be editable ('readonly: false'). # directory-scoped cheatsheets will always be editable ('readonly: false').
`) `)
} }

View File

@ -19,34 +19,46 @@ formatter: terminal256
# 'more' is recommended on Windows # 'more' is recommended on Windows
pager: PAGER_PATH pager: PAGER_PATH
# The paths at which cheatsheets are available. Tags associated with a cheatpath # Cheatpaths are paths at which cheatsheets are available on your local
# are automatically attached to all cheatsheets residing on that path. # filesystem.
# #
# Whenever cheatsheets share the same title (like 'tar'), the most local # It is useful to sort cheatsheets into different cheatpaths for organizational
# cheatsheets (those which come later in this file) take precedent over the # purposes. For example, you might want one cheatpath for community
# less local sheets. This allows you to create your own "overides" for # cheatsheets, one for personal cheatsheets, one for cheatsheets pertaining to
# "upstream" cheatsheets. # your day job, one for code snippets, etc.
# #
# But what if you want to view the "upstream" cheatsheets instead of your own? # Cheatpaths are scoped, such that more "local" cheatpaths take priority over
# Cheatsheets may be filtered via 'cheat -t <tag>' in combination with other # more "global" cheatpaths. (The most global cheatpath is listed first in this
# commands. So, if you want to view the 'tar' cheatsheet that is tagged as # file; the most local is listed last.) For example, if there is a 'tar'
# 'community' rather than your own, you can use: cheat tar -t community # cheatsheet on both global and local paths, you'll be presented with the local
cheatpaths: # one by default. ('cheat -p' can be used to view cheatsheets from alternative
# Paths that come earlier are considered to be the most "global", and will # cheatpaths.)
# thus be overridden by more local cheatsheets. That being the case, you
# should probably list community cheatsheets first.
# #
# Note that the paths and tags listed below are placeholders. You may freely # Cheatpaths can also be tagged as "read only". This instructs cheat not to
# change them to suit your needs. # automatically create cheatsheets on a read-only cheatpath. Instead, when you
# would like to edit a read-only cheatsheet using 'cheat -e', cheat will
# perform a copy-on-write of that cheatsheet from a read-only cheatpath to a
# writeable cheatpath.
#
# This is very useful when you would like to maintain, for example, a
# "pristine" repository of community cheatsheets on one cheatpath, and an
# editable personal reponsity of cheatsheets on another cheatpath.
#
# Cheatpaths can be also configured to automatically apply tags to cheatsheets
# on certain paths, which can be useful for querying purposes.
# Example: 'cheat -t work jenkins'.
# #
# Community cheatsheets must be installed separately, though you may have # Community cheatsheets must be installed separately, though you may have
# downloaded them automatically when installing 'cheat'. If not, you may # downloaded them automatically when installing 'cheat'. If not, you may
# download them here: # download them here:
# #
# https://github.com/cheat/cheatsheets # https://github.com/cheat/cheatsheets
# cheatpaths:
# Once downloaded, ensure that 'path' below points to the location at which # Cheatpath properties mean the following:
# you downloaded the community cheatsheets. # 'name': the name of the cheatpath (view with 'cheat -d', filter with 'cheat -p')
# 'path': the filesystem path of the cheatsheet directory (view with 'cheat -d')
# 'tags': tags that should be automatically applied to sheets on this path
# 'readonly': shall user-created ('cheat -e') cheatsheets be saved here?
- name: community - name: community
path: COMMUNITY_PATH path: COMMUNITY_PATH
tags: [ community ] tags: [ community ]
@ -60,11 +72,11 @@ cheatpaths:
readonly: false readonly: false
# While it requires no configuration here, it's also worth noting that # While it requires no configuration here, it's also worth noting that
# 'cheat' will automatically append directories named '.cheat' within the # cheat will automatically append directories named '.cheat' within the
# current working directory to the 'cheatpath'. This can be very useful if # current working directory to the 'cheatpath'. This can be very useful if
# you'd like to closely associate cheatsheets with, for example, a directory # you'd like to closely associate cheatsheets with, for example, a directory
# containing source code. # containing source code.
# #
# Such "directory-scoped" cheatsheets will be treated as the most "local" # Such "directory-scoped" cheatsheets will be treated as the most "local"
# cheatsheets, and will override less "local" cheatsheets. Likewise, # cheatsheets, and will override less "local" cheatsheets. Similarly,
# directory-scoped cheatsheets will always be editable ('readonly: false'). # directory-scoped cheatsheets will always be editable ('readonly: false').