diff --git a/hledger.conf.sample b/hledger.conf.sample
index 90249cea2..a6b3119ef 100644
--- a/hledger.conf.sample
+++ b/hledger.conf.sample
@@ -1,72 +1,77 @@
-# An example hledger config file for you to customise.
-# This declares extra options/arguments to be added to your hledger commands.
-# Save as ~/.hledger.conf, or ~/.config/hledger/hledger.conf, or hledger.conf
-# in or above your current directory, and hledger will use it automatically.
-# Or you can choose a config file with --conf.
-# Or you can turn a config file like this one into a script, by adding
-# a shebang line like `#!/usr/bin/env -S hledger --conf` at the top.
-#
-# Automatic config files are convenient, but have a cost: it's easy to confuse
-# yourself, disrupt reports, or break scripts/applications which use hledger.
-# If you choose to use one, be careful about what you put in it.
-# If a command is not working as expected, run it with `--debug` to troubleshoot.
-# To avoid using a config file, run with `-n` (short for `--no-conf`).
+# Here's a (verbose) hledger config file, providing extra options/arguments.
+# You can try it with --conf CONFFILE, or save it as ~/.hledger.conf
+# (or ~/.config/hledger/hledger.conf, or hledger.conf in/above current directory),
+# and hledger will use it automatically.
+# Note automatic config files are convenient, but it's easy to confuse yourself,
+# disrupt reports, or break hledger-using scripts/applications.
+# If a command is not working as expected, try it with -n to disable config files,
+# or run it with --debug or --debug=8 to troubleshoot.
+# https://hledger.org/dev/hledger.html#config-files
 
 
 # 1. General options. These will be used with all commands which support them.
 
-# Show prettier tables in reports.
-# Recommended unless your font doesn't support box drawing characters.
---pretty
+# https://hledger.org/dev/hledger.html#output
+# If you need to turn off any of these, I'd like to hear details:
+--pretty     # Show prettier tables in reports ? Recommended on most systems.
+#--color=no  # Disable ANSI color and font styling in the terminal ?
+#--pager=no  # Disable paging of long output in the terminal ?
 
-# Postpone balance assertions until you use -s or `hledger check assertions`.
-# This means there's less need to add -I while piping or fixing problems.
---ignore-assertions
+# Postpone balance assertions until you use -s or `hledger check assertions` ?
+# It means less need to add -I while piping or fixing problems.
+--ignore-assertions    # https://hledger.org/hledger.html#balance-assertions
 
 # Always infer these things ? Why not.
---infer-costs
+# https://hledger.org/hledger.html#--infer-market-prices-market-prices-from-transactions
+# https://hledger.org/hledger.html#equity-conversion-postings
+# https://hledger.org/hledger.html#inferring-equity-conversion-postings
 --infer-market-prices
-
+--infer-costs
 #--infer-equity
-# If you use hledger check accounts or hledger check -s with this flag enabled,
-# you may see that some extra account declarations are needed in your journal, like
+#
+# If you enable --infer-equity and use hledger check accounts or hledger check -s,
+# you might need to add account declarations to your journal, something like:
 # account equity:conversion:CUR1-CUR2:CUR1
 # account equity:conversion:CUR1-CUR2:CUR2
 
 
 # 2. Command-specific options.
 
+# https://hledger.org/hledger.html#print
 [print]
 --explicit     # show inferred amounts
 --show-costs   # show inferred costs
 
+# https://hledger.org/hledger.html#help
 [help]
 #--man          # if you prefer man over info
 
-# Set your preferred options for the balance commands.
+# Set some defaults for the balance commands ?
 # You can override these by adding more options on the command line.
-# [balance]            --tree --depth 3 --layout=bare
-# [balancesheet]       --tree --depth 3 --layout=bare
-# [balancesheetequity] --tree --depth 3 --layout=bare
-# [cashflow]           --tree --depth 3 --layout=bare
-# [incomestatement]    --tree --depth 3 --layout=bare
+# [balance]            --layout=bare --tree --depth 3
+# [balancesheet]       --layout=bare --tree --depth 3
+# [balancesheetequity] --layout=bare --tree --depth 3
+# [cashflow]           --layout=bare --tree --depth 3
+# [incomestatement]    --layout=bare --tree --depth 3
 
 
-# You can also set options for add-on commands (run by `hledger ADDONCMD`).
-# The -- argument needed at command line is not needed here.
+# You can also set options for add-on commands here. This works only if
+# you run them with hledger (`hledger ui ...`, not `hledger-ui ...`).
+# Note they will also respect the general options above
+# (hledger-ui and hledger-web will, at least).
 
-# Some defaults for hledger-ui: start in the Cash accounts screen,
-# watch for file changes, set a depth limit, hide zeros and equity accounts.
-[ui] --cash --watch -3 -E not:type:e
-# need to repeat this here
---ignore-assertions
+# https://hledger.org/hledger-ui.html
+# Start in the "Cash accounts" screen, with a depth limit,
+# hiding zeros and equity accounts, and watch for file changes.
+[ui] --cash -3 -E not:type:e --watch
 
+# https://hledger.org/hledger-web.html
 [web] --port 5050 --allow edit
-# and here
---ignore-assertions
 
+# https://hledger.org/scripts.html#hledger-iadd
 [iadd] --date-format %Y-%m-%d
 
+# https://hledger.org/scripts.html#hledger-interest
 #[interest]
 # --annual 0.05
 # --30-360