From 2a69598e02641398732345544f259cc9fb48361d Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Fri, 10 Oct 2025 22:21:15 -0700 Subject: [PATCH] Partial work on factoring out references docs from how-to guides (#942). --- .eleventy.js | 2 +- NEWS | 3 + README.md | 58 +- borgmatic/config/schema.yaml | 2 +- docs/Dockerfile | 5 +- docs/_includes/asciinema.css | 3 - docs/_includes/components/toc.css | 33 +- docs/_includes/header.njk | 4 + docs/_includes/index.css | 4 +- docs/_includes/layouts/base.njk | 5 +- docs/_includes/layouts/main.njk | 2 +- ...reparation-and-cleanup-steps-to-backups.md | 10 +- ...movable-drive-or-an-intermittent-server.md | 8 +- docs/how-to/backup-your-databases.md | 30 +- docs/how-to/customize-warnings-and-errors.md | 2 - docs/how-to/deal-with-very-large-backups.md | 374 +--------- docs/how-to/develop-on-borgmatic.md | 6 +- docs/how-to/extract-a-backup.md | 8 +- docs/how-to/inspect-your-backups.md | 157 +---- docs/how-to/make-backups-redundant.md | 4 +- docs/how-to/make-per-application-backups.md | 653 +----------------- docs/how-to/monitor-your-backups.md | 651 +---------------- docs/how-to/provide-your-passwords.md | 359 +--------- docs/how-to/restore-a-backup.md | 2 +- docs/how-to/run-arbitrary-borg-commands.md | 2 - .../run-preparation-steps-before-backups.md | 2 +- docs/how-to/set-up-backups.md | 62 +- docs/how-to/snapshot-your-filesystems.md | 20 +- docs/how-to/upgrade.md | 8 +- docs/reference/command-line/actions.md | 89 +++ .../index.md} | 8 +- docs/reference/command-line/logging.md | 138 ++++ docs/reference/command-line/overrides.md | 145 ++++ .../configuration/archive-name-format.md | 100 +++ .../configuration/consistency-checks.md | 322 +++++++++ docs/reference/configuration/constants.md | 77 +++ .../configuration/credentials/container.md | 62 ++ .../configuration/credentials/file.md | 32 + .../configuration/credentials/index.md | 48 ++ .../configuration/credentials/keepassxc.md | 51 ++ .../configuration/credentials/systemd.md | 108 +++ .../configuration/environment-variables.md | 93 +++ docs/reference/configuration/includes.md | 319 +++++++++ .../index.md} | 10 +- .../configuration/monitoring/apprise.md | 106 +++ .../configuration/monitoring/cronhub.md | 33 + .../configuration/monitoring/cronitor.md | 29 + .../configuration/monitoring/healthchecks.md | 50 ++ .../configuration/monitoring/index.md | 25 + .../configuration/monitoring/loki.md | 55 ++ .../configuration/monitoring/ntfy.md | 64 ++ .../configuration/monitoring/pagerduty.md | 69 ++ .../configuration/monitoring/pushover.md | 54 ++ .../configuration/monitoring/sentry.md | 41 ++ .../configuration/monitoring/uptime-kuma.md | 59 ++ .../configuration/monitoring/zabbix.md | 71 ++ docs/reference/source-code.md | 17 +- scripts/run-end-to-end-tests | 2 +- scripts/run-full-tests | 2 +- 59 files changed, 2478 insertions(+), 2280 deletions(-) delete mode 100644 docs/_includes/asciinema.css create mode 100644 docs/reference/command-line/actions.md rename docs/reference/{command-line.md => command-line/index.md} (81%) create mode 100644 docs/reference/command-line/logging.md create mode 100644 docs/reference/command-line/overrides.md create mode 100644 docs/reference/configuration/archive-name-format.md create mode 100644 docs/reference/configuration/consistency-checks.md create mode 100644 docs/reference/configuration/constants.md create mode 100644 docs/reference/configuration/credentials/container.md create mode 100644 docs/reference/configuration/credentials/file.md create mode 100644 docs/reference/configuration/credentials/index.md create mode 100644 docs/reference/configuration/credentials/keepassxc.md create mode 100644 docs/reference/configuration/credentials/systemd.md create mode 100644 docs/reference/configuration/environment-variables.md create mode 100644 docs/reference/configuration/includes.md rename docs/reference/{configuration.md => configuration/index.md} (67%) create mode 100644 docs/reference/configuration/monitoring/apprise.md create mode 100644 docs/reference/configuration/monitoring/cronhub.md create mode 100644 docs/reference/configuration/monitoring/cronitor.md create mode 100644 docs/reference/configuration/monitoring/healthchecks.md create mode 100644 docs/reference/configuration/monitoring/index.md create mode 100644 docs/reference/configuration/monitoring/loki.md create mode 100644 docs/reference/configuration/monitoring/ntfy.md create mode 100644 docs/reference/configuration/monitoring/pagerduty.md create mode 100644 docs/reference/configuration/monitoring/pushover.md create mode 100644 docs/reference/configuration/monitoring/sentry.md create mode 100644 docs/reference/configuration/monitoring/uptime-kuma.md create mode 100644 docs/reference/configuration/monitoring/zabbix.md diff --git a/.eleventy.js b/.eleventy.js index 30057a4a..12543f7c 100644 --- a/.eleventy.js +++ b/.eleventy.js @@ -44,7 +44,7 @@ module.exports = function(eleventyConfig) { templateFormats: [ "md", "txt" - ] + ], } }; diff --git a/NEWS b/NEWS index 83494dbb..0bb12e95 100644 --- a/NEWS +++ b/NEWS @@ -1,4 +1,7 @@ 2.0.10.dev0 + * #942: Factor reference material out of the documentation how-to guides. This means + there's now a whole reference section in the docs! Check it out: + https://torsion.org/borgmatic/ * #1161: Fix a traceback (TypeError) in the "check" action with Python 3.14. 2.0.9 diff --git a/README.md b/README.md index f58b3ce9..b06fa830 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ permalink: index.html ## It's your data. Keep it that way. -borgmatic logo +borgmatic logo borgmatic is simple, configuration-driven backup software for servers and workstations. Protect your files with client-side encryption. Backup your @@ -60,45 +60,45 @@ borgmatic is powered by [Borg Backup](https://www.borgbackup.org/). ### Data -PostgreSQL -MySQL -MariaDB -MongoDB -SQLite -OpenZFS -Btrfs -LVM -rclone -BorgBase +PostgreSQL +MySQL +MariaDB +MongoDB +SQLite +OpenZFS +Btrfs +LVM +rclone +BorgBase ### Monitoring -Healthchecks -Uptime Kuma -Cronitor -Cronhub -PagerDuty -Pushover -ntfy -Loki -Apprise -Zabbix -Sentry +Healthchecks +Uptime Kuma +Cronitor +Cronhub +PagerDuty +Pushover +ntfy +Loki +Apprise +Zabbix +Sentry ### Credentials -Sentry -Docker -Podman -Podman +Sentry +Docker +Podman +Podman ## Getting started Your first step is to [install and configure -borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups/). +borgmatic](https://torsion.org/borgmatic/how-to/set-up-backups/). For additional documentation, check out the links above (left panel on wide screens) for borgmatic how-to and @@ -132,7 +132,7 @@ first. If you prefer to use an existing GitHub account, you can skip account creation and [login directly](https://projects.torsion.org/user/login). Also see the [security -policy](https://torsion.org/borgmatic/docs/security-policy/) for any security +policy](https://torsion.org/borgmatic/security-policy/) for any security issues. @@ -177,7 +177,7 @@ discuss your idea. Note that you'll need to first. In general, contributions are very welcome. We don't bite! Also, please check out the [borgmatic development -how-to](https://torsion.org/borgmatic/docs/how-to/develop-on-borgmatic/) for +how-to](https://torsion.org/borgmatic/how-to/develop-on-borgmatic/) for info on cloning source code, running tests, etc. ### Recent contributors diff --git a/borgmatic/config/schema.yaml b/borgmatic/config/schema.yaml index 933fa48c..4c2ee89c 100644 --- a/borgmatic/config/schema.yaml +++ b/borgmatic/config/schema.yaml @@ -275,7 +275,7 @@ properties: encryption_passphrase takes precedence. This can also be used to access encrypted systemd service credentials. Defaults to not set. For more details, see: - https://torsion.org/borgmatic/docs/how-to/provide-your-passwords/ + https://torsion.org/borgmatic/how-to/provide-your-passwords/ example: "secret-tool lookup borg-repository repo-name" encryption_passphrase: type: string diff --git a/docs/Dockerfile b/docs/Dockerfile index cfa1b828..4379abb4 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -27,10 +27,9 @@ COPY --from=borgmatic /etc/borgmatic/config.yaml /source/docs/_includes/borgmati COPY --from=borgmatic /command-line.txt /source/docs/_includes/borgmatic/command-line.txt COPY --from=borgmatic /contributors.html /source/docs/_includes/borgmatic/contributors.html COPY . /source -RUN NODE_ENV=${ENVIRONMENT} npx eleventy --input=/source/docs --output=/output/docs \ - && mv /output/docs/index.html /output/index.html +RUN NODE_ENV=${ENVIRONMENT} npx eleventy --input=/source/docs --output=/output FROM docker.io/nginx:1.26.1-alpine COPY --from=html /output /usr/share/nginx/html -COPY --from=borgmatic /etc/borgmatic/config.yaml /usr/share/nginx/html/docs/reference/config.yaml +COPY --from=borgmatic /etc/borgmatic/config.yaml /usr/share/nginx/html/reference/config.yaml diff --git a/docs/_includes/asciinema.css b/docs/_includes/asciinema.css deleted file mode 100644 index b2ddcffd..00000000 --- a/docs/_includes/asciinema.css +++ /dev/null @@ -1,3 +0,0 @@ -.asciicast > iframe { - width: 100% !important; -} diff --git a/docs/_includes/components/toc.css b/docs/_includes/components/toc.css index 4967c301..345b8f8a 100644 --- a/docs/_includes/components/toc.css +++ b/docs/_includes/components/toc.css @@ -48,9 +48,10 @@ padding-bottom: 0; padding-left: 0.625rem; /* 10px /16 */ } -/* Hide inactive menus 3 or more deep */ -.elv-toc-list ul ul > li:not(.elv-toc-active) > ul > li:not(.elv-toc-active) { - display: none; + +/* Display inline menus 4 or more deep */ +.elv-toc-list ul ul ul > li { + display: inline-block; } /* List items */ @@ -98,3 +99,29 @@ .elv-cat-list-active { font-weight: 600; } + +.breadcrumb-item.active { + color: var(--primary-color); +} + +#breadcrumb ol, +#breadcrumb ul { + margin: 0; + padding: 0 0 1em; +} + +#breadcrumb li { + display: inline; +} + +#breadcrumb li:not(:last-child)::after { + content: " ˃" +} + +#breadcrumb a:not(:hover) { + text-decoration: none; +} + +#breadcrumb a { + text-decoration-color: #00bcd4; +} diff --git a/docs/_includes/header.njk b/docs/_includes/header.njk index f511e012..c227f241 100644 --- a/docs/_includes/header.njk +++ b/docs/_includes/header.njk @@ -1,4 +1,8 @@
{% if page.url != '/' %}

borgmatic

{% endif %} +

{{ title | safe }}

diff --git a/docs/_includes/index.css b/docs/_includes/index.css index c798f2e9..a81293da 100644 --- a/docs/_includes/index.css +++ b/docs/_includes/index.css @@ -112,7 +112,7 @@ h5 { } h1 { font-size: 2.666666666667em; /* 48px /18 */ - margin: 0 0 .5em; + margin: 0; } main .elv-toc + h1 { margin-top: 1em; @@ -229,7 +229,7 @@ pre + .note { /* Layout */ .elv-layout { - padding: 1rem; + padding: 0 1rem 1rem; margin: 0 auto; max-width: 42rem; clear: both; diff --git a/docs/_includes/layouts/base.njk b/docs/_includes/layouts/base.njk index 0807f5f0..994598a0 100644 --- a/docs/_includes/layouts/base.njk +++ b/docs/_includes/layouts/base.njk @@ -4,8 +4,8 @@ - - {{ subtitle + ' - ' if subtitle}}{{ title }} + + borgmatic - {{ subtitle + ' - ' if subtitle}}{{ title }} {%- set css %} {% include 'index.css' %} {% include 'components/lists.css' %} @@ -14,7 +14,6 @@ {% include 'components/toc.css' %} {% include 'components/info-blocks.css' %} {% include 'prism-theme.css' %} -{% include 'asciinema.css' %} {% endset %} {% if feedTitle and feedUrl %} diff --git a/docs/_includes/layouts/main.njk b/docs/_includes/layouts/main.njk index 81300bae..f9e06dd9 100644 --- a/docs/_includes/layouts/main.njk +++ b/docs/_includes/layouts/main.njk @@ -11,7 +11,7 @@ headerClass: elv-header-default {% set navPages = collections.all | eleventyNavigation %} {% macro renderNavListItem(entry) -%} - {{ entry.title }} + {{ entry.title }} {%- if entry.children.length -%}