More documentation updates based on section removal (#721).

docs/_includes/components/suggestion-link.html

@@ -1,5 +1,5 @@
 <h2>Improve this documentation</h2>
 
 <p>Have an idea on how to make this documentation even better? Use our <a
-href="https://projects.torsion.org/borgmatic-collective/borgmatic/issues">issue tracker</a> to send your
-feedback!</p>
+href="https://torsion.org/borgmatic/#support-and-contributing">issue
+tracker</a> to send your feedback!</p>

docs/how-to/add-preparation-and-cleanup-steps-to-backups.md

@@ -21,11 +21,10 @@ running backups, and specify `after_backup` hooks to perform cleanup steps
 afterwards. Here's an example:
 
 ```yaml
-hooks:
-    before_backup:
-        - mount /some/filesystem
-    after_backup:
-        - umount /some/filesystem
+before_backup:
+    - mount /some/filesystem
+after_backup:
+    - umount /some/filesystem
 ```
 
 If your command contains a special YAML character such as a colon, you may
@@ -33,11 +32,23 @@ need to quote the entire string (or use a [multiline
 string](https://yaml-multiline.info/)) to avoid an error:
 
 ```yaml
-hooks:
-    before_backup:
-        - "echo Backup: start"
+before_backup:
+    - "echo Backup: start"
 ```
 
+There are additional hooks that run before/after other actions as well. For
+instance, `before_prune` runs before a `prune` action for a repository, while
+`after_prune` runs after it.
+
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+these options in the `hooks:` section of your configuration.
+
+<span class="minilink minilink-addedin">New in version 1.7.0</span> The
+`before_actions` and `after_actions` hooks run before/after all the actions
+(like `create`, `prune`, etc.) for each repository. These hooks are a good
+place to run per-repository steps like mounting/unmounting a remote
+filesystem.
+
 <span class="minilink minilink-addedin">New in version 1.6.0</span> The
 `before_backup` and `after_backup` hooks each run once per repository in a
 configuration file. `before_backup` hooks runs right before the `create`
@@ -46,16 +57,6 @@ but not if an error occurs in a previous hook or in the backups themselves.
 (Prior to borgmatic 1.6.0, these hooks instead ran once per configuration file
 rather than once per repository.)
 
-There are additional hooks that run before/after other actions as well. For
-instance, `before_prune` runs before a `prune` action for a repository, while
-`after_prune` runs after it.
-
-<span class="minilink minilink-addedin">New in version 1.7.0</span> The
-`before_actions` and `after_actions` hooks run before/after all the actions
-(like `create`, `prune`, etc.) for each repository. These hooks are a good
-place to run per-repository steps like mounting/unmounting a remote
-filesystem.
-
 
 ## Variable interpolation
 
@@ -64,11 +65,13 @@ variables into the hook command. Here's an example that assumes you provide a
 separate shell script:
 
 ```yaml
-hooks:
-    after_prune:
-        - record-prune.sh "{configuration_filename}" "{repository}"
+after_prune:
+    - record-prune.sh "{configuration_filename}" "{repository}"
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 In this example, when the hook is triggered, borgmatic interpolates runtime
 values into the hook command: the borgmatic configuration filename and the
 paths of the current Borg repository. Here's the full set of supported
@@ -92,13 +95,15 @@ You can also use `before_everything` and `after_everything` hooks to perform
 global setup or cleanup:
 
 ```yaml
-hooks:
-    before_everything:
-        - set-up-stuff-globally
-    after_everything:
-        - clean-up-stuff-globally
+before_everything:
+    - set-up-stuff-globally
+after_everything:
+    - clean-up-stuff-globally
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+these options in the `hooks:` section of your configuration.
+
 `before_everything` hooks collected from all borgmatic configuration files run
 once before all configuration files (prior to all actions), but only if there
 is a `create` action. An error encountered during a `before_everything` hook
@@ -109,6 +114,7 @@ but only if there is a `create` action. It runs even if an error occurs during
 a backup or a backup hook, but not if an error occurs during a
 `before_everything` hook.
 
+
 ## Error hooks
 
 borgmatic also runs `on_error` hooks if an error occurs, either when creating
@@ -116,6 +122,7 @@ a backup or running a backup hook. See the [monitoring and alerting
 documentation](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/)
 for more information.
 
+
 ## Hook output
 
 Any output produced by your hooks shows up both at the console and in syslog
@@ -123,6 +130,7 @@ Any output produced by your hooks shows up both at the console and in syslog
 href="https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/">inspecting
 your backups</a>.
 
+
 ## Security
 
 An important security note about hooks: borgmatic executes all hook commands

docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md

@@ -62,11 +62,13 @@ the external `findmnt` utility to see whether the drive is mounted before
 proceeding.
 
 ```yaml
-hooks:
-    before_backup:
-      - findmnt /mnt/removable > /dev/null || exit 75
+before_backup:
+    - findmnt /mnt/removable > /dev/null || exit 75
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put this
+option in the `hooks:` section of your configuration.
+
 What this does is check if the `findmnt` command errors when probing for a
 particular mount point. If it does error, then it returns exit code 75 to
 borgmatic. borgmatic logs the soft failure, skips all further actions in that
@@ -89,19 +91,11 @@ before_backup:
     - ping -q -c 1 buddys-server.org > /dev/null || exit 75
 ```
 
-<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put the
-first two options in the `location:` section of your configuration and the
-`before_backup` option within the `hooks:` section.
-
-<span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
-the `path:` portion of the `repositories` list.
-
 Or to only run backups if the battery level is high enough:
 
 ```yaml
-hooks:
-    before_backup:
-      - is_battery_percent_at_least.sh 25
+before_backup:
+    - is_battery_percent_at_least.sh 25
 ```
 
 (Writing the battery script is left as an exercise to the reader.)

docs/how-to/backup-your-databases.md

@@ -18,31 +18,32 @@ prior to running backups. For example, here is everything you need to dump and
 backup a couple of local PostgreSQL databases and a MySQL/MariaDB database.
 
 ```yaml
-hooks:
-    postgresql_databases:
-        - name: users
-        - name: orders
-    mysql_databases:
-        - name: posts
+postgresql_databases:
+    - name: users
+    - name: orders
+mysql_databases:
+    - name: posts
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+these and other database options in the `hooks:` section of your
+configuration.
+
 <span class="minilink minilink-addedin">New in version 1.5.22</span> You can
 also dump MongoDB databases. For example:
 
 ```yaml
-hooks:
-    mongodb_databases:
-        - name: messages
+mongodb_databases:
+    - name: messages
 ```
 
 <span class="minilink minilink-addedin">New in version 1.7.9</span>
 Additionally, you can dump SQLite databases. For example:
 
 ```yaml
-hooks:
-    sqlite_databases:
-        - name: mydb
-          path: /var/lib/sqlite3/mydb.sqlite
+sqlite_databases:
+    - name: mydb
+      path: /var/lib/sqlite3/mydb.sqlite
 ```
 
 As part of each backup, borgmatic streams a database dump for each configured
@@ -54,7 +55,7 @@ temporary disk space.)
 
 To support this, borgmatic creates temporary named pipes in `~/.borgmatic` by
 default. To customize this path, set the `borgmatic_source_directory` option
-in the `location` section of borgmatic's configuration.
+in borgmatic's configuration.
 
 Also note that using a database hook implicitly enables both the
 `read_special` and `one_file_system` configuration settings (even if they're
@@ -64,35 +65,34 @@ See Limitations below for more on this.
 Here's a more involved example that connects to remote databases:
 
 ```yaml
-hooks:
-    postgresql_databases:
-        - name: users
-          hostname: database1.example.org
-        - name: orders
-          hostname: database2.example.org
-          port: 5433
-          username: postgres
-          password: trustsome1
-          format: tar
-          options: "--role=someone"
-    mysql_databases:
-        - name: posts
-          hostname: database3.example.org
-          port: 3307
-          username: root
-          password: trustsome1
-          options: "--skip-comments"
-    mongodb_databases:
-        - name: messages
-          hostname: database4.example.org
-          port: 27018
-          username: dbuser
-          password: trustsome1
-          authentication_database: mongousers
-          options: "--ssl"
-    sqlite_databases:
-        - name: mydb
-          path: /var/lib/sqlite3/mydb.sqlite
+postgresql_databases:
+    - name: users
+      hostname: database1.example.org
+    - name: orders
+      hostname: database2.example.org
+      port: 5433
+      username: postgres
+      password: trustsome1
+      format: tar
+      options: "--role=someone"
+mysql_databases:
+    - name: posts
+      hostname: database3.example.org
+      port: 3307
+      username: root
+      password: trustsome1
+      options: "--skip-comments"
+mongodb_databases:
+    - name: messages
+      hostname: database4.example.org
+      port: 27018
+      username: dbuser
+      password: trustsome1
+      authentication_database: mongousers
+      options: "--ssl"
+sqlite_databases:
+    - name: mydb
+      path: /var/lib/sqlite3/mydb.sqlite
 ```
 
 See your [borgmatic configuration
@@ -106,13 +106,12 @@ listing databases, restoring databases, etc.).
 If you want to dump all databases on a host, use `all` for the database name:
 
 ```yaml
-hooks:
-    postgresql_databases:
-        - name: all
-    mysql_databases:
-        - name: all
-    mongodb_databases:
-        - name: all
+postgresql_databases:
+    - name: all
+mysql_databases:
+    - name: all
+mongodb_databases:
+    - name: all
 ```
 
 Note that you may need to use a `username` of the `postgres` superuser for
@@ -120,6 +119,9 @@ this to work with PostgreSQL.
 
 The SQLite hook in particular does not consider "all" a special database name.
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+these options in the `hooks:` section of your configuration.
+
 <span class="minilink minilink-addedin">New in version 1.7.6</span> With
 PostgreSQL and MySQL, you can optionally dump "all" databases to separate
 files instead of one combined dump file, allowing more convenient restores of
@@ -127,13 +129,12 @@ individual databases. Enable this by specifying your desired database dump
 `format`:
 
 ```yaml
-hooks:
-    postgresql_databases:
-        - name: all
-          format: custom
-    mysql_databases:
-        - name: all
-          format: sql
+postgresql_databases:
+    - name: all
+      format: custom
+mysql_databases:
+    - name: all
+      format: sql
 ```
 
 ### Containers
@@ -143,15 +144,17 @@ problem—configure borgmatic to connect to the container's name on its exposed
 port. For instance:
 
 ```yaml
-hooks:
-    postgresql_databases:
-        - name: users
-          hostname: your-database-container-name
-          port: 5433
-          username: postgres
-          password: trustsome1
+postgresql_databases:
+    - name: users
+      hostname: your-database-container-name
+      port: 5433
+      username: postgres
+      password: trustsome1
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+these options in the `hooks:` section of your configuration.
+
 But what if borgmatic is running on the host? You can still connect to a
 database container if its ports are properly exposed to the host. For
 instance, when running the database container, you can specify `--publish
@@ -179,8 +182,7 @@ hooks:
           password: trustsome1
 ```
 
-You can alter the ports in these examples to suit your particular database
-system.
+Alter the ports in these examples to suit your particular database system.
 
 
 ### No source directories
@@ -428,10 +430,9 @@ You can add any additional flags to the `options:` in your database
 configuration. Here's an example:
 
 ```yaml
-hooks:
-    mysql_databases:
-        - name: posts
-          options: "--single-transaction --quick"
+mysql_databases:
+    - name: posts
+      options: "--single-transaction --quick"
 ```
 
 ### borgmatic hangs during backup

docs/how-to/deal-with-very-large-backups.md

@@ -65,19 +65,20 @@ configure borgmatic to run repository checks only. Configure this in the
 `consistency` section of borgmatic configuration:
 
 ```yaml
-consistency:
-    checks:
-        - name: repository
+checks:
+    - name: repository
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `consistency:` section of your configuration.
+
 <span class="minilink minilink-addedin">Prior to version 1.6.2</span> The
 `checks` option was a plain list of strings without the `name:` part, and
 borgmatic ran each configured check every time checks were run. For example:
 
 ```yaml
-consistency:
-    checks:
-        - repository
+checks:
+    - repository
 ```
 
 
@@ -103,14 +104,16 @@ optionally configure checks to run on a periodic basis rather than every time
 borgmatic runs checks. For instance:
 
 ```yaml
-consistency:
-    checks:
-        - name: repository
-          frequency: 2 weeks
-        - name: archives
-          frequency: 1 month
+checks:
+    - name: repository
+      frequency: 2 weeks
+    - name: archives
+      frequency: 1 month
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `consistency:` section of your configuration.
+
 This tells borgmatic to run the `repository` consistency check at most once
 every two weeks for a given repository and the `archives` check at most once a
 month. The `frequency` value is a number followed by a unit of time, e.g. "3
@@ -173,9 +176,8 @@ this option in the `consistency:` section of your configuration.
 was a plain list of strings without the `name:` part. For instance:
 
 ```yaml
-consistency:
-    checks:
-        - disabled
+checks:
+    - disabled
 ```
 
 If you have multiple repositories in your borgmatic configuration file,

docs/how-to/develop-on-borgmatic.md

@@ -7,7 +7,7 @@ eleventyNavigation:
 ---
 ## Source code
 
-To get set up to hack on borgmatic, first clone it via HTTPS or SSH:
+To get set up to develop on borgmatic, first clone it via HTTPS or SSH:
 
 ```bash
 git clone https://projects.torsion.org/borgmatic-collective/borgmatic.git
@@ -21,8 +21,8 @@ git clone ssh://git@projects.torsion.org:3022/borgmatic-collective/borgmatic.git
 
 Then, install borgmatic
 "[editable](https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs)"
-so that you can run borgmatic commands while you're hacking on them to
-make sure your changes work.
+so that you can run borgmatic actions during development to make sure your
+changes work.
 
 ```bash
 cd borgmatic

docs/how-to/inspect-your-backups.md

@@ -60,7 +60,7 @@ with `--format`. Refer to the [borg list --format
 documentation](https://borgbackup.readthedocs.io/en/stable/usage/list.html#the-format-specifier-syntax)
 for available values.
 
-*(No borgmatic `list` or `info` actions? Upgrade borgmatic!)*
+(No borgmatic `list` or `info` actions? Upgrade borgmatic!)
 
 <span class="minilink minilink-addedin">New in borgmatic version 1.7.0</span>
 There are also `rlist` and `rinfo` actions for displaying repository

docs/how-to/make-per-application-backups.md

@@ -104,11 +104,12 @@ to filter archives when running supported actions.
 For instance, let's say that you have this in your configuration:
 
 ```yaml
-storage:
-    ...
-    archive_name_format: {hostname}-user-data-{now}
+archive_name_format: {hostname}-user-data-{now}
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `storage:` section of your configuration.
+
 borgmatic considers `{now}` an emphemeral data placeholder that will probably
 change per archive, while `{hostname}` won't. So it turns the example value
 into `{hostname}-user-data-*` and applies it to filter down the set of
@@ -124,10 +125,8 @@ If this behavior isn't quite smart enough for your needs, you can use the
 filtering archives. For example:
 
 ```yaml
-storage:
-    ...
-    archive_name_format: {hostname}-user-data-{now}
-    match_archives: sh:myhost-user-data-*        
+archive_name_format: {hostname}-user-data-{now}
+match_archives: sh:myhost-user-data-*        
 ```
 
 For Borg 1.x, use a shell pattern for the `match_archives` value and see the
@@ -190,7 +189,7 @@ When a configuration include is a relative path, borgmatic loads it from either
 the current working directory or from the directory containing the file doing
 the including.
 
-Note that this form of include must be a YAML value rather than a key. For
+Note that this form of include must be a value rather than an option name. For
 example, this will not work:
 
 ```yaml
@@ -201,7 +200,7 @@ repositories:
 !include /etc/borgmatic/common_checks.yaml
 ```
 
-But if you do want to merge in a YAML key *and* its values, keep reading!
+But if you do want to merge in a option name *and* its values, keep reading!
 
 
 ## Include merging
@@ -238,11 +237,6 @@ Once this include gets merged in, the resulting configuration would have all
 of the options from the original configuration file *and* the options from the
 include.
 
-<span class="minilink minilink-addedin">Prior to version 1.6.0</span> When the
-same option appeared in both the local file and the merged include, the local
-file's value took precedence—meaning the included value was ignored in favor
-of the local one. But see below about deep merge in version 1.6.0+.
-
 Note that this `<<` include merging syntax is only for merging in mappings
 (configuration options and their values). But if you'd like to include a
 single value directly, please see the above about standard includes.
@@ -261,29 +255,30 @@ at all levels in the two configuration files. This allows you to include
 common configuration—up to full borgmatic configuration files—while overriding
 only the parts you want to customize.
 
-For instance, here's an example of a main configuration file that pulls in two
-retention options via an include and then overrides one of them locally:
+For instance, here's an example of a main configuration file that pulls in
+options via an include and then overrides one of them locally:
 
 ```yaml
 <<: !include /etc/borgmatic/common.yaml
 
-location:
-   ...
+constants:
+    hostname: myhostname
 
-retention:
-    keep_daily: 5
+repositories:
+    - path: repo.borg
 ```
 
 This is what `common.yaml` might look like:
 
 ```yaml
-retention:
-    keep_hourly: 24
-    keep_daily: 7
+constants:
+    prefix: myprefix
+    hostname: otherhost
 ```
 
 Once this include gets merged in, the resulting configuration would have a
-`keep_hourly` value of `24` and an overridden `keep_daily` value of `5`.
+`prefix` value of `myprefix` and an overridden `hostname` value of
+`myhostname`.
 
 When there's an option collision between the local file and the merged
 include, the local file's option takes precedence.
@@ -301,21 +296,22 @@ configuration file, you can omit it with an `!omit` tag. For instance:
 ```yaml
 <<: !include /etc/borgmatic/common.yaml
 
-location:
-   source_directories:
-     - !omit /home
-     - /var
+source_directories:
+    - !omit /home
+    - /var
 ```
 
 And `common.yaml` like this:
 
 ```yaml
-location:
-   source_directories:
-     - /home
-     - /etc
+source_directories:
+    - /home
+    - /etc
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `location:` section of your configuration.
+
 Once this include gets merged in, the resulting configuration will have a
 `source_directories` value of `/etc` and `/var`—with `/home` omitted.
 
@@ -328,16 +324,15 @@ an example of some things not to do:
 ```yaml
 <<: !include /etc/borgmatic/common.yaml
 
-location:
-   source_directories:
-     # Do not do this! It will not work. "!omit" belongs before "/home".
-     - /home !omit
+source_directories:
+    # Do not do this! It will not work. "!omit" belongs before "/home".
+    - /home !omit
 
-   # Do not do this either! "!omit" only works on scalar list items.
-   repositories: !omit
-     # Also do not do this for the same reason! This is a list item, but it's
-     # not a scalar.
-     - !omit path: repo.borg
+# Do not do this either! "!omit" only works on scalar list items.
+repositories: !omit
+    # Also do not do this for the same reason! This is a list item, but it's
+    # not a scalar.
+    - !omit path: repo.borg
 ```
 
 Additionally, the `!omit` tag only works in a configuration file that also
@@ -451,9 +446,6 @@ What this does is load your configuration files, and for each one, disregard
 the configured value for the `remote_path` option, and use the value of
 `/usr/local/bin/borg1` instead.
 
-<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Don't
-forget to specify the section (like `location:`) that any option is in.
-
 You can even override nested values or multiple values at once. For instance:
 
 ```bash

docs/how-to/monitor-your-backups.md

@@ -89,19 +89,20 @@ notifications or take other actions, so you can get alerted as soon as
 something goes wrong. Here's a not-so-useful example:
 
 ```yaml
-hooks:
-    on_error:
-        - echo "Error while creating a backup or running a backup hook."
+on_error:
+    - echo "Error while creating a backup or running a backup hook."
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 The `on_error` hook supports interpolating particular runtime variables into
 the hook command. Here's an example that assumes you provide a separate shell
 script to handle the alerting:
 
 ```yaml
-hooks:
-    on_error:
-        - send-text-message.sh "{configuration_filename}" "{repository}"
+on_error:
+    - send-text-message.sh "{configuration_filename}" "{repository}"
 ```
 
 In this example, when the error occurs, borgmatic interpolates runtime values
@@ -135,11 +136,13 @@ URL" for your project. Here's an example:
 
 
 ```yaml
-hooks:
-    healthchecks:
-        ping_url: https://hc-ping.com/addffa72-da17-40ae-be9c-ff591afb942a
+healthchecks:
+    ping_url: https://hc-ping.com/addffa72-da17-40ae-be9c-ff591afb942a
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 With this hook in place, borgmatic pings your Healthchecks project when a
 backup begins, ends, or errors. Specifically, after the <a
 href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
@@ -179,11 +182,13 @@ API URL" for your monitor. Here's an example:
 
 
 ```yaml
-hooks:
-    cronitor:
-        ping_url: https://cronitor.link/d3x0c1
+cronitor:
+    ping_url: https://cronitor.link/d3x0c1
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 With this hook in place, borgmatic pings your Cronitor monitor when a backup
 begins, ends, or errors. Specifically, after the <a
 href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
@@ -208,11 +213,13 @@ URL" for your monitor. Here's an example:
 
 
 ```yaml
-hooks:
-    cronhub:
-        ping_url: https://cronhub.io/start/1f5e3410-254c-11e8-b61d-55875966d031
+cronhub:
+    ping_url: https://cronhub.io/start/1f5e3410-254c-11e8-b61d-55875966d031
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 With this hook in place, borgmatic pings your Cronhub monitor when a backup
 begins, ends, or errors. Specifically, after the <a
 href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
@@ -251,11 +258,13 @@ Here's an example:
 
 
 ```yaml
-hooks:
-    pagerduty:
-        integration_key: a177cad45bd374409f78906a810a3074
+pagerduty:
+    integration_key: a177cad45bd374409f78906a810a3074
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 With this hook in place, borgmatic creates a PagerDuty event for your service
 whenever backups fail. Specifically, if an error occurs during a `create`,
 `prune`, `compact`, or `check` action, borgmatic sends an event to PagerDuty
@@ -291,31 +300,34 @@ An example configuration is shown here, with all the available options, includin
 [tags](https://ntfy.sh/docs/publish/#tags-emojis):
 
 ```yaml
-hooks:
-    ntfy:
-        topic: my-unique-topic
-        server: https://ntfy.my-domain.com
-        start:
-            title: A Borgmatic backup started
-            message: Watch this space...
-            tags: borgmatic
-            priority: min
-        finish:
-            title: A Borgmatic backup completed successfully
-            message: Nice!
-            tags: borgmatic,+1
-            priority: min
-        fail:
-            title: A Borgmatic backup failed
-            message: You should probably fix it
-            tags: borgmatic,-1,skull
-            priority: max
-        states:
-            - start
-            - finish
-            - fail
+ntfy:
+    topic: my-unique-topic
+    server: https://ntfy.my-domain.com
+    start:
+        title: A Borgmatic backup started
+        message: Watch this space...
+        tags: borgmatic
+        priority: min
+    finish:
+        title: A Borgmatic backup completed successfully
+        message: Nice!
+        tags: borgmatic,+1
+        priority: min
+    fail:
+        title: A Borgmatic backup failed
+        message: You should probably fix it
+        tags: borgmatic,-1,skull
+        priority: max
+    states:
+        - start
+        - finish
+        - fail
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+the `ntfy:` option in the `hooks:` section of your configuration.
+
+
 ## Scripting borgmatic
 
 To consume the output of borgmatic in other software, you can include an

docs/how-to/provide-your-passwords.md

@@ -20,10 +20,12 @@ pull your repository passphrase, your database passwords, or any other option
 values from environment variables. For instance:
 
 ```yaml
-storage:
-    encryption_passphrase: ${MY_PASSPHRASE}
+encryption_passphrase: ${MY_PASSPHRASE}
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `storage:` section of your configuration.
+
 This uses the `MY_PASSPHRASE` environment variable as your encryption
 passphrase. Note that the `{` `}` brackets are required. `$MY_PASSPHRASE` by
 itself will not work.
@@ -38,12 +40,14 @@ configuration](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/)
 the same approach applies. For example:
 
 ```yaml
-hooks:
-    postgresql_databases:
-        - name: users
-          password: ${MY_DATABASE_PASSWORD}
+postgresql_databases:
+    - name: users
+      password: ${MY_DATABASE_PASSWORD}
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 This uses the `MY_DATABASE_PASSWORD` environment variable as your database
 password.
 
@@ -53,8 +57,7 @@ password.
 If you'd like to set a default for your environment variables, you can do so with the following syntax:
 
 ```yaml
-storage:
-    encryption_passphrase: ${MY_PASSPHRASE:-defaultpass}
+encryption_passphrase: ${MY_PASSPHRASE:-defaultpass}
 ```
 
 Here, "`defaultpass`" is the default passphrase if the `MY_PASSPHRASE`
@@ -72,8 +75,7 @@ can escape it with a backslash. For instance, if your password is literally
 `${A}@!`:
 
 ```yaml
-storage:
-    encryption_passphrase: \${A}@!
+encryption_passphrase: \${A}@!
 ```
 
 ### Related features

docs/how-to/upgrade.md

@@ -135,12 +135,6 @@ repositories:
     - path: original.borg
 ```
 
-<span class="minilink minilink-addedin">Prior to version 1.8.0</span> This
-option was found in the `location:` section of your configuration.
-
-<span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
-the `path:` portion of the `repositories` list.
-
 Change it to a new (not yet created) repository path:
 
 ```yaml
@@ -148,6 +142,12 @@ repositories:
     - path: upgraded.borg
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> This
+option was found in the `location:` section of your configuration.
+
+<span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
+the `path:` portion of the `repositories` list.
+
 Then, run the `rcreate` action (formerly `init`) to create that new Borg 2
 repository:
 

docs/reference/command-line.md

@@ -15,7 +15,7 @@ listed here do not have equivalents in borgmatic's [configuration
 file](https://torsion.org/borgmatic/docs/reference/configuration/).
 
 If you're using an older version of borgmatic, some of these flags may not be
-present in that version, and you should instead use `borgmatic --help` or
+present in that version and you should instead use `borgmatic --help` or
 `borgmatic [action name] --help` (where `[action name]` is the name of an
 action like `list`, `create`, etc.).