Update to Documentation! #579
Conversation
…and env ref out of index and into seperate pages
WalkthroughThis PR reorganises and rewrites large parts of the documentation: restructures configuration, usage, installation and scheduling docs, adds new pages (hooks, variables, monitoring, features, usage examples), removes obsolete pages, updates metadata/weights, and updates the Makefile to initialise the docs submodule. Changes
Sequence Diagram(s)(omitted — changes are documentation reorganisation and build-step update; no multi-component runtime control flow requiring a sequence diagram) Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested labels
Pre-merge checks❌ Failed checks (2 inconclusive)
✅ Passed checks (1 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #579 +/- ##
==========================================
+ Coverage 79.69% 81.00% +1.31%
==========================================
Files 137 137
Lines 13467 11083 -2384
==========================================
- Hits 10732 8977 -1755
+ Misses 2310 1680 -630
- Partials 425 426 +1
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
I'll have a look at it during the week or at the week-end, thank you for your help 👍🏻 |
|
Just wanted to bump this to bring to your attention! Lemme know if the direction this is heading at is looking good! |
|
Hi! I finally got a bit of time to look at it. Sadly I can't try to view the result locally, I get an error on building it with Hugo: Are you using a different version of Hugo by any chance? |
|
Ah! I see what's happened. To explain:
This is different than my working version, which has the following under the same dir: I've pushed a change that just updates the link, it should be good! |
|
Cool I can browse the doc locally, it's easier to see that way 👍🏻 |
|
Build looks to be failing at the check broken links, which makes sense/is to be expected (seeing as the update to the docs would move a lot of the links around) |
|
Hi! Pushed a couple of updates to this, here's the update: I'm taking another sweep through of the documentation to rework it again. I'm not particularly trained in this field unfortunately, but I am trying to emulate some of my favorite documentation (such as ntfy). The main area I'd like to tackle (slowly but surely) is the reference section, as I've noticed some information being out of date or being incorrect (the schedule-after-error YAML example comes to mind). But! It'll get done slowly but surely :). I am using Diataxis to guide how I edit the information. I still aim to keep all the information intact, but just condensed as per the needs of the section. Eg, the installation section got cut to pieces, to make it really condensed. This follows the 'How To' sector of Diataxis, and anything that doesn't fall under it has (so far) been put into either |
|
Thanks for your help; I'll have a look at it. You don't need to do a big bang rewrite of the documentation; small changes in their own pull requests help improve things gradually 👍🏻 |
|
Many thanks :D ! Yes, you do raise an excellent point re: not doing it in one shot, and likewise on my end, no rush on reviewing the docs on my part! I'll mark the PR away from Draft when I feel like I've sufficiently completed a part of it! |
|
I'm ready for this to be reviewed properly. Thank you again for mentioning that it does not have to be a big bang rewrite of the documentation, that helped ease the perfectionism LOL. Take a look at it and let me know what you think! Happy holidays :) |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 11
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/content/usage/keyfile.md (1)
14-14: Fix spelling error in link text.Line 14 contains a typo: "cryto" should be "crypto".
🔎 Proposed fix
-[Reference from the Go cryto library documentation](https://golang.org/pkg/crypto/rand/#pkg-variables) +[Reference from the Go crypto library documentation](https://golang.org/pkg/crypto/rand/#pkg-variables)docs/content/configuration/schedules/_index.md (1)
1-21: Fix broken reference link on line 20.The link to
/reference/globalon line 20 is broken—this page does not exist in the documentation. The global section configuration is documented across multiple pages in the configuration directory (such asdocs/content/configuration/profiles/priority.md,profiles/include.md, andprofiles/locks.md), not in a centralised reference page.Consider either removing the reference or updating it to point to a relevant configuration page (e.g.,
/configuration/profiles/or/configuration/_index.md). If scheduler-specific global options are the focus, refer to the relevant scheduling method page instead.The relative links to scheduling methods are valid and correctly configured.
🧹 Nitpick comments (19)
docs/content/installation/binaries.md (1)
10-40: Improve structural consistency for netbsd and solaris entries.The reorganisation from a flat list to OS-grouped sections is a clear improvement for readability. However, the netbsd and solaris entries (lines 39–40) remain in flat format whilst all other operating systems have dedicated sections. This inconsistency may confuse users about whether other architectures are supported for these platforms.
Consider either:
- Adding dedicated OS sections for netbsd and solaris (if multiple architectures are supported or planned), or
- Removing them if support is obsolete or not actively maintained.
docs/content/installation/_index.md (1)
16-20: Address punctuation and improve clarity in the Memory section.LanguageTool has flagged three punctuation issues. Additionally, consider rewriting the section in a more formal, third-person tone to align with technical documentation standards, rather than the current first-person narrative.
Proposed improvements:
- Line 16: Add a comma before "and I managed to kill some of them" (compound sentence).
- Line 17: Add a comma after "For that matter," (introductory phrase).
- Line 20: Clarify the parenthetical remark for readability.
🔎 Suggested revision for improved clarity and tone
- restic can be memory hungry. I'm running a few servers with no swap and I managed to kill some of them during a backup. + restic can be memory hungry. Some servers running without swap may experience issues if restic exhausts available memory during a backup. - For that matter I've introduced a parameter in the `global` section called `min-memory`. The **default value is 100MB**. You can disable it by using a value of `0`. + For that reason, a global parameter called `min-memory` is available (default: **100 MB**). Set it to `0` to disable the check. - It compares against `(total - used)` which is probably the best way to know how much memory is available (that is including the memory used for disk buffers/cache). + This parameter checks available memory as `(total - used)`, which includes memory used for disk buffers and caches, providing an accurate view of truly available memory.docs/content/installation/linux.md (1)
2-2: Standardise "macOS" capitalisation.The Apple operating system is branded as "macOS" (not "MacOS"). Please update capitalisation on lines 2, 9, and 30 for consistency with the official branding.
🔎 Proposed capitalisation fixes
- title: "Linux and MacOS" + title: "Linux and macOS" - Works for: MacOS, Linux + Works for: macOS, Linux - ## Installation With Homebrew - Works for: MacOS, Linux + ## Installation With Homebrew + Works for: macOS, LinuxAlso applies to: 9-9, 30-30
docs/content/installation/docker.md (2)
9-11: Clarify the Docker example mount path for user flexibility.The example uses
$PWD/examples:/resticprofileas the volume mount. This is a specific relative path that may not reflect typical user setups. Consider whether:
- The path should be more generic (e.g.,
/path/to/your/config) with explanation- Additional example variations would be helpful (e.g., mounting a configuration file, backup sources)
- A link to the reference page for Docker usage patterns would supplement this example
Currently, a new user might not understand how to adapt the command to their own filesystem layout.
13-16: Make the macOS performance caveat more specific if possible.The warning states backups "may be slower" on macOS with mounted volumes. If performance data or specific impact estimates are available (e.g., 2–10× slower, or guidance to use native macOS volumes), consider including it to help users decide whether to use Docker on macOS or seek alternatives.
If the issue is well-documented elsewhere, a reference link (similar to the docker reference link below) would be appropriate.
docs/content/configuration/profiles/editorConfig.md (1)
5-7: Consider expanding guidance to other editors.The file correctly notes that any editor supporting JSON schema can be used, and provides the schema reference. However, practical configuration examples are limited to Visual Studio Code. This is acceptable for a practical how-to (VS Code is the most popular), but the content could optionally be enhanced with:
- Brief mentions of schema integration in other popular editors (Vim with coc-json, Neovim with LSP, JetBrains IDEs, etc.)
- An example configuration for JSON files alongside TOML and YAML
- Links to editor-specific schema integration resources for users of other tools
This is not a blocker, as the JSON schema reference allows users of other editors to configure support independently.
docs/content/configuration/profiles/_index.md (1)
17-17: Consider adding a comma for clarity.The phrase "configurations but is not the easiest format" would read more smoothly with a comma: "configurations, but is not the easiest format". However, this is a minor stylistic suggestion and not critical.
docs/content/_index.md (1)
9-9: Minor hyphenation suggestion for British English style.Consider writing "low-priority task" with a hyphen, as it functions as a compound adjective modifying "task". However, both forms are acceptable.
docs/content/features/_index.md (1)
10-38: Consider standardising markdown formatting.The markdown linter has flagged some minor formatting inconsistencies:
- Nested list items use 4-space indentation instead of the expected 2-space indentation.
- Lines 22-23 use underscore emphasis (
_stdin_,_nice_,_ionice_) instead of asterisk emphasis, which is inconsistent with the rest of the document (e.g., line 23 uses*nice*and*systemd*).Standardising these would improve consistency across the documentation.
🔎 Proposed formatting fixes
For indentation, reduce nested list items from 4 spaces to 2 spaces:
* **Profiles** - * No need to remember command parameters and environment variables + * No need to remember command parameters and environment variablesFor emphasis style on lines 22-23, change underscores to asterisks:
- * Send a backup stream via _stdin_ + * Send a backup stream via *stdin* - * Start restic at different [priorities]({{% relref "/configuration/profiles/priority" %}}) (Priority Class in Windows, *nice* in Unix, and/or _ionice_ in Linux) + * Start restic at different [priorities]({{% relref "/configuration/profiles/priority" %}}) (Priority Class in Windows, *nice* in Unix, and/or *ionice* in Linux)docs/content/configuration/hooks/_index.md (1)
7-7: Consider adding a brief introductory description.The page currently relies entirely on the Children shortcode to render child pages. Adding a short introductory sentence or paragraph explaining what hooks are and why users might need to configure them would improve navigation and context for readers discovering this section.
For example:
{{% children sort="weight" depth="2" %}}could be preceded by:
Hooks allow you to run custom commands at various points during backup execution, such as before, after, or on error events. {{% children sort="weight" depth="2" %}}docs/content/configuration/monitoring/_index.md (1)
1-11: Add missing comma after "By default" in introductory text.Line 6 should read: "By default, resticprofile will display all logs..." The grammatically correct form requires a comma after introductory adverbs.
🔎 Proposed grammar fix
-By default **resticprofile** will display all logs (from itself and **restic**) to the console. +By default, **resticprofile** will display all logs (from itself and **restic**) to the console.docs/content/usage/scheduling/change-schedule.md (1)
10-12: Clarify the instruction for changing schedule permission.The phrase on line 11 is ambiguous about the action being taken. The grammatical hint about missing preposition is valid. Consider rephrasing to: "Change the permission in your configuration (from user to system, or from system to user)" or "Change your permission setting to either user or system" for greater clarity.
🔎 Proposed clarity improvement
- Unschedule the job first (before updating the permission in the configuration) -- Change your permission (user to system, or system to user). +- Change the permission in your configuration (from user to system, or from system to user). - Schedule your updated profile.docs/content/usage/variables/list-variables.md (1)
1-4: Consider adding weight to front matter for consistent ordering.The front matter lacks a
weightparameter, which may cause the page to appear in an unintended position within the navigation hierarchy. Other files in the PR (e.g., body-template.md, ntfy.md) include explicit weights. Consider whether this page should have a weight value for consistent ordering.docs/content/usage/configuration/stdin.md (1)
8-8: Consider standardising the tabs groupid for consistency.Line 8 specifies
groupid="config-with-hcl"whilst most other documentation pages in the PR usegroupid="config-with-json". If this is intentional (to group this example with HCL-focused content), that's acceptable, but if it's an oversight, it should be updated for consistency across the documentation.docs/content/usage/variables/inheritance-and-variables.md (1)
228-228: Use hyphen for compound adjective modifying "example".Change "real world example" to "real-world example" to correctly format the compound adjective.
🔎 Proposed fix
-This is obviously not a real world example, but it shows many of the possibilities you can do with variable expansion. +This is obviously not a real-world example, but it shows many of the possibilities you can do with variable expansion.docs/content/configuration/profiles/include.md (1)
84-84: Consider using "before" instead of "prior to" for conciseness.The phrase "prior to parsing" is slightly wordier than necessary. Using "before" is more concise and equally clear in this documentation context.
🔎 Proposed fix
-Loading a configuration file involves loading the physical file from disk and applying all [variables]({{% relref "/configuration/variables" %}}) and [templates]({{% relref "/configuration/variables/templates" %}}) prior to parsing the file in a supported format `hcl`, `json`, `toml` and `yaml`. +Loading a configuration file involves loading the physical file from disk and applying all [variables]({{% relref "/configuration/variables" %}}) and [templates]({{% relref "/configuration/variables/templates" %}}) before parsing the file in a supported format `hcl`, `json`, `toml` and `yaml`.docs/content/configuration/variables/_index.md (3)
30-30: Add comma after "For example".When "for example" introduces a clause, it should be followed by a comma for proper grammar.
🔎 Proposed fix
-Default and fallback values for an empty or unset variable can be declared with `{{ ... | or ... }}`. -For example `{{ .Env.HOME | or .Env.USERPROFILE | or "/fallback-homedir" }}` will try to resolve `$HOME`, if empty try to resolve `$USERPROFILE` +Default and fallback values for an empty or unset variable can be declared with `{{ ... | or ... }}`. +For example, `{{ .Env.HOME | or .Env.USERPROFILE | or "/fallback-homedir" }}` will try to resolve `$HOME`, if empty try to resolve `$USERPROFILE`
55-55: Improve the grammar of "allows to derive".The phrase "allows to derive" is awkward in English. Use "allows deriving" or "lets you derive" for better flow.
🔎 Proposed fix
-The variable `.Now` also allows to derive a relative `Time`. For example `{{ (.Now.AddDate 0 -6 -14).Format "2006-01-02" }}` formats a date that +The variable `.Now` also lets you derive a relative `Time`. For example, `{{ (.Now.AddDate 0 -6 -14).Format "2006-01-02" }}` formats a date that
110-110: Consider using "before" instead of "prior to".In this context, "before parsing" is more concise and equally clear than "prior to parsing".
🔎 Proposed fix
-Variable expansion as described in the previous section using the `{{ .Var }}` syntax refers to [template variables]({{% relref "/configuration/variables/templates" %}}) that are expanded prior to parsing the configuration file. +Variable expansion as described in the previous section using the `{{ .Var }}` syntax refers to [template variables]({{% relref "/configuration/variables/templates" %}}) that are expanded before parsing the configuration file.
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (7)
docs/content/configuration/profiles/TOML.pngis excluded by!**/*.pngdocs/content/configuration/profiles/YAML.pngis excluded by!**/*.pngdocs/content/configuration/schedules/removable_volume.pngis excluded by!**/*.pngdocs/content/configuration/schedules/scheduling_methods/task_scheduler/administrator.pngis excluded by!**/*.pngdocs/content/configuration/schedules/scheduling_methods/task_scheduler/runas.pngis excluded by!**/*.pngdocs/content/configuration/schedules/scheduling_methods/task_scheduler/unwanted_my_ass.pngis excluded by!**/*.pngdocs/content/reference/jsonschema/jsonschema-vsc.gifis excluded by!**/*.gif
📒 Files selected for processing (76)
Makefiledocs/content/_index.mddocs/content/changelog.mddocs/content/configuration/_index.mddocs/content/configuration/hooks/_index.mddocs/content/configuration/hooks/copy.mddocs/content/configuration/hooks/http_hooks.mddocs/content/configuration/hooks/run_hooks.mddocs/content/configuration/http_hooks.mddocs/content/configuration/jsonschema/index.mddocs/content/configuration/monitoring/_index.mddocs/content/configuration/monitoring/prometheus.mddocs/content/configuration/monitoring/status.mddocs/content/configuration/monitoring/tempfilelogging.mddocs/content/configuration/monitoring/warnings.mddocs/content/configuration/profiles/_index.mddocs/content/configuration/profiles/editorConfig.mddocs/content/configuration/profiles/include.mddocs/content/configuration/profiles/inheritance.mddocs/content/configuration/profiles/locks.mddocs/content/configuration/profiles/path.mddocs/content/configuration/profiles/priority.mddocs/content/configuration/schedules/_index.mddocs/content/configuration/schedules/commands.mddocs/content/configuration/schedules/configuration.mddocs/content/configuration/schedules/scheduling_methods/_index.mddocs/content/configuration/schedules/scheduling_methods/cron.mddocs/content/configuration/schedules/scheduling_methods/launchd.mddocs/content/configuration/schedules/scheduling_methods/non-root-schedule-in-container.mddocs/content/configuration/schedules/scheduling_methods/systemd.mddocs/content/configuration/schedules/scheduling_methods/task_scheduler/index.mddocs/content/configuration/sleep.mddocs/content/configuration/v2.mddocs/content/configuration/variables.mddocs/content/configuration/variables/_index.mddocs/content/configuration/variables/env_vars.mddocs/content/configuration/variables/templates.mddocs/content/contributions/_index.mddocs/content/faq.mddocs/content/features/_index.mddocs/content/installation/_index.mddocs/content/installation/ansible/index.mddocs/content/installation/binaries.mddocs/content/installation/docker.mddocs/content/installation/linux.mddocs/content/installation/macosx.mddocs/content/installation/shell.mddocs/content/installation/source.mddocs/content/installation/upgrade.mddocs/content/installation/windows.mddocs/content/monitoring/_index.mddocs/content/schedules/examples.mddocs/content/usage/_index.mddocs/content/usage/configuration/_index.mddocs/content/usage/configuration/azure-storage.mddocs/content/usage/configuration/configWindows.mddocs/content/usage/configuration/configWinheritence.mddocs/content/usage/configuration/stdin.mddocs/content/usage/getting_started.mddocs/content/usage/hooks/_index.mddocs/content/usage/hooks/body-template.mddocs/content/usage/hooks/healthchecks.mddocs/content/usage/hooks/ntfy.mddocs/content/usage/keyfile.mddocs/content/usage/memory.mddocs/content/usage/scheduling/_index.mddocs/content/usage/scheduling/change-schedule.mddocs/content/usage/scheduling/linux.mddocs/content/usage/scheduling/macos.mddocs/content/usage/scheduling/windows.mddocs/content/usage/variables/_index.mddocs/content/usage/variables/inheritance-and-variables.mddocs/content/usage/variables/list-variables.mddocs/content/usage/version.mddocs/layouts/shortcodes/toc.htmldocs/themes/hugo-theme-relearn
💤 Files with no reviewable changes (13)
- docs/content/configuration/variables/templates.md
- docs/content/usage/version.md
- docs/content/configuration/variables.md
- docs/content/installation/upgrade.md
- docs/content/configuration/v2.md
- docs/content/installation/shell.md
- docs/content/usage/memory.md
- docs/content/configuration/http_hooks.md
- docs/content/installation/macosx.md
- docs/content/configuration/sleep.md
- docs/content/schedules/examples.md
- docs/content/monitoring/_index.md
- docs/content/configuration/jsonschema/index.md
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2025-02-14T22:53:42.689Z
Learnt from: creativeprojects
Repo: creativeprojects/resticprofile PR: 459
File: schtasks/schtasks.go:29-30
Timestamp: 2025-02-14T22:53:42.689Z
Learning: In the `schtasks` package, `tasksPath` is defined as a constant with value `\resticprofile backup\` in `taskscheduler.go`. It's used as a prefix for managing task paths in the Windows Task Scheduler.
Applied to files:
docs/content/usage/getting_started.mddocs/content/configuration/schedules/_index.mddocs/content/usage/scheduling/windows.md
📚 Learning: 2025-02-14T22:53:45.818Z
Learnt from: creativeprojects
Repo: creativeprojects/resticprofile PR: 459
File: examples/windows.yaml:41-41
Timestamp: 2025-02-14T22:53:45.818Z
Learning: Changes to example configurations in the `examples/` directory do not require changelog entries as they are meant for testing and demonstration purposes only.
Applied to files:
docs/content/configuration/_index.mddocs/content/usage/configuration/configWinheritence.md
🪛 LanguageTool
docs/content/configuration/profiles/_index.md
[uncategorized] ~17-~17: Possible missing comma found.
Context: ...itable for auto-generated configurations but is not the easiest format for humans to...
(AI_HYDRA_LEO_MISSING_COMMA)
[typographical] ~23-~23: Consider wrapping this idiom with two commas if you want to put a strong emphasize on it.
Context: ...your template and variable expansion If for some reason you don't understand why resticprofile ...
(FOR_WHATEVER_REASON_COMMA)
docs/content/installation/_index.md
[uncategorized] ~16-~16: Possible missing comma found.
Context: ...ngry. I'm running a few servers with no swap and I managed to kill some of them duri...
(AI_HYDRA_LEO_MISSING_COMMA)
[typographical] ~17-~17: Use a comma after an introductory phrase.
Context: ... to kill some of them during a backup. For that matter I've introduced a parameter in the `glo...
(COMMA_INTRODUCTORY_WORDS_PHRASES)
[uncategorized] ~20-~20: Possible missing comma found.
Context: ...know how much memory is available (that is including the memory used for disk buff...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/content/usage/variables/inheritance-and-variables.md
[uncategorized] ~228-~228: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ... {{< /tabs >}} This is obviously not a real world example, but it shows many of the possi...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
[uncategorized] ~280-~280: Possible missing comma found.
Context: ...d the read-data-subset in the check section which will read a seventh of the data e...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/content/configuration/hooks/http_hooks.md
[uncategorized] ~45-~45: Loose punctuation mark.
Context: ...dy: - PROFILE_NAME - PROFILE_COMMAND: backup, check, forget, etc. Additional...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~57-~57: Possible missing comma found.
Context: ...n). Failures in any send-* are logged but do not influence environment or return ...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/content/configuration/monitoring/_index.md
[uncategorized] ~6-~6: Did you mean: “By default,”?
Context: ...Logs" weight: 50 alwaysopen: false --- By default resticprofile will display all logs...
(BY_DEFAULT_COMMA)
docs/content/features/_index.md
[grammar] ~31-~31: You’ve repeated a verb. Did you mean to only write one of them?
Context: ...ring/index" %}}) to a syslog server * Checks * Check for [enough memory]({{% relref "/instal...
(REPEATED_VERBS)
docs/content/usage/scheduling/change-schedule.md
[uncategorized] ~11-~11: Possible missing preposition found.
Context: ... the permission in the configuration) - Change your permission (user to system, or sys...
(AI_HYDRA_LEO_MISSING_TO)
docs/content/installation/linux.md
[uncategorized] ~9-~9: The operating system from Apple is written “macOS”.
Context: ...## Installation via a script Works for: MacOS, Linux Here's a simple script to down...
(MAC_OS)
[uncategorized] ~30-~30: The operating system from Apple is written “macOS”.
Context: ...# Installation With Homebrew Works for: MacOS, Linux There's a [homebrew](https://br...
(MAC_OS)
docs/content/configuration/profiles/include.md
[style] ~84-~84: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ...configuration/variables/templates" %}}) prior to parsing the file in a supported format ...
(EN_WORDINESS_PREMIUM_PRIOR_TO)
docs/content/faq.md
[grammar] ~23-~23: There seems to be a noun/verb agreement error. Did you mean “installs” or “installed”?
Context: ...--zsh-completion)" ``` ### My homebrew install failed! Homebrew appears to need acces...
(SINGULAR_NOUN_VERB_AGREEMENT)
[misspelling] ~31-~31: This word is normally spelled with a hyphen.
Context: ...on section how to schedule backups in a long running container. The configuration needs to s...
(EN_COMPOUNDS_LONG_RUNNING)
docs/content/_index.md
[uncategorized] ~9-~9: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: .../restic/restic/issues/16), it remains a low priority task.
(EN_COMPOUND_ADJECTIVE_INTERNAL)
docs/content/configuration/variables/_index.md
[typographical] ~30-~30: After the expression ‘for example’ a comma is usually used.
Context: ...declared with {{ ... | or ... }}. For example `{{ .Env.HOME | or .Env.USERPROFILE | o...
(COMMA_FOR_EXAMPLE)
[grammar] ~55-~55: Did you mean “deriving”? Or maybe you should add a pronoun? In active voice, ‘allow’ + ‘to’ takes an object, usually a pronoun.
Context: ...mples. The variable .Now also allows to derive a relative Time. For example `{{ (.No...
(ALLOW_TO)
[typographical] ~55-~55: After the expression ‘for example’ a comma is usually used.
Context: ...allows to derive a relative Time. For example `{{ (.Now.AddDate 0 -6 -14).Format "200...
(COMMA_FOR_EXAMPLE)
[style] ~95-~95: As a shorter alternative for ‘able to’, consider using “can”.
Context: ...hes / instead of backslashes. Windows is able to use forward slashes in paths. - you can...
(BE_ABLE_TO)
[style] ~110-~110: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ...ables/templates" %}}) that are expanded prior to parsing the configuration file. This m...
(EN_WORDINESS_PREMIUM_PRIOR_TO)
[style] ~115-~115: Would you like to use the Oxford spelling “parametrization”? The spelling ‘parametrisation’ is also correct.
Context: ...}}) where $variable style is used for parametrisation and the profile [config flag]({{% relre...
(OXFORD_SPELLING_Z_NOT_S)
docs/content/usage/scheduling/windows.md
[uncategorized] ~9-~9: Possible missing comma found.
Context: ...m not emailing your password to myself. Seriously you shouldn't trust anyone. {{% /notice...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/content/configuration/profiles/inheritance.md
[uncategorized] ~194-~194: Possible missing comma found.
Context: ...for variables can be defined inside the mixin with default-vars and use can speci...
(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~194-~194: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ...nfiguration/variables" %}}) that expand prior to parsing, mixin variables expand when th...
(EN_WORDINESS_PREMIUM_PRIOR_TO)
[typographical] ~194-~194: It seems that a comma is missing.
Context: ...d when the mixin is merged and for this reason the syntax differs. Unlike configurati...
(FOR_THIS_REASON_COMMA)
[style] ~300-~300: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ...n/profiles/include/index.html" %}}) but prior to [profile inheritance](#profile-inherita...
(EN_WORDINESS_PREMIUM_PRIOR_TO)
[style] ~300-~300: Unless you want to emphasize “not”, use “cannot” which is more common.
Context: ...a derived profile, but derived profiles can not change which mixins apply to their pare...
(CAN_NOT_PREMIUM)
🪛 markdownlint-cli2 (0.18.1)
docs/content/configuration/_index.md
14-14: Emphasis style
Expected: asterisk; Actual: underscore
(MD049, emphasis-style)
14-14: Emphasis style
Expected: asterisk; Actual: underscore
(MD049, emphasis-style)
docs/content/features/_index.md
10-10: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
11-11: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
12-12: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
13-13: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
14-14: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
15-15: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
16-16: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
18-18: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
19-19: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
20-20: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
21-21: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
22-22: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
22-22: Emphasis style
Expected: asterisk; Actual: underscore
(MD049, emphasis-style)
22-22: Emphasis style
Expected: asterisk; Actual: underscore
(MD049, emphasis-style)
23-23: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
23-23: Emphasis style
Expected: asterisk; Actual: underscore
(MD049, emphasis-style)
23-23: Emphasis style
Expected: asterisk; Actual: underscore
(MD049, emphasis-style)
24-24: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
26-26: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
27-27: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
28-28: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
29-29: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
30-30: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
32-32: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
33-33: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
35-35: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
36-36: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
37-37: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
38-38: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
🔇 Additional comments (45)
docs/content/usage/keyfile.md (2)
2-3: Front matter changes are appropriate.The title is now more descriptive and better reflects the content. The weight adjustment aligns with the documentation restructuring.
16-26: Code examples are clear and practical.The examples effectively demonstrate both basic usage and customisation, with clear explanatory text. The progression from default to custom key size is logical and helpful.
docs/content/installation/linux.md (1)
37-38: Verify whether the--with-resticHomebrew option should be retained.The AI summary indicates that the
--with-resticoption was removed from the Homebrew snippet, but lines 37–38 still reference and document it. Please clarify whether this option remains supported in the current resticprofile release, or whether these lines should be removed to align with the intended consolidation.docs/content/faq.md (2)
1-38: Good addition to documentation structure.The FAQ page provides practical quick-start answers for common questions (shell completion, Docker scheduling, sleep prevention) and aligns well with the documentation reorganisation. The front matter, section layout, and content are clear and helpful.
38-38: Link path verified as correct.The relref path
/configuration/schedules/configuration/#preventing-system-sleepis accurate. The target file exists atdocs/content/configuration/schedules/configuration.md, and the heading "Preventing System Sleep" at line 199 correctly generates the anchor#preventing-system-sleep. The same path is consistently used across the documentation (also in features/_index.md), confirming the link was properly updated during documentation reorganisation.docs/content/usage/configuration/configWindows.md (1)
1-107: Example is well-structured and practical.The three-format tabbed example provides clear, parallel configuration demonstrations for Windows users. The real-world restic-binary path and profile structure are appropriate and helpful. The weight positioning (30) and groupid consistency align with the documentation's multi-format presentation pattern.
docs/content/configuration/profiles/editorConfig.md (1)
1-21: Overall structure and content look good.The markdown formatting is clean, the Hugo shortcode syntax appears correct, and the content is well-organised. The focus on Visual Studio Code is practical, and the recommendations for TOML and YAML extensions are helpful for users.
However, this approval is conditional on the paths referenced in line 7 and image paths in lines 15 and 21 being verified to exist after the documentation reorganisation.
docs/content/usage/hooks/_index.md (1)
1-7: LGTM!The index page structure is correct and follows Hugo conventions for organizing child pages by weight.
docs/content/installation/windows.md (1)
6-6: LGTM!The table of contents placeholder is correctly positioned and aligns with the documentation enhancement strategy across the PR.
docs/content/configuration/monitoring/warnings.md (1)
3-3: LGTM!The weight adjustment and newline handling are part of the documentation reorganization and improve consistency.
Also applies to: 67-67
docs/layouts/shortcodes/toc.html (1)
1-1: LGTM!The shortcode is minimal but functional. For future enhancements, consider adding parameters for customization (e.g., heading levels, CSS classes).
docs/content/contributions/_index.md (1)
3-3: LGTM!The numbering adjustment is part of the documentation restructuring and maintains consistency across the site navigation.
docs/content/changelog.md (1)
3-3: LGTM!The numbering adjustment aligns with the overall documentation restructuring.
docs/content/configuration/schedules/scheduling_methods/systemd.md (1)
75-75: Verify the anchor link resolves correctly.The change to a same-page anchor reference simplifies the link. The target heading exists at line 177, and Hugo should auto-generate the anchor correctly. However, please verify the link works as expected in the built documentation, as anchor generation can sometimes vary.
docs/content/configuration/schedules/scheduling_methods/task_scheduler/index.md (1)
18-18: All relative image paths are valid and correctly configured.Verification confirms that all three image files exist at the expected relative paths:
./unwanted_my_ass.png✓./runas.png✓./administrator.png✓The change to relative paths maintains correct references and improves maintainability as described.
docs/content/installation/ansible/index.md (1)
6-8: Work-in-progress notice appropriately placed.The caution notice clearly communicates the preliminary state of the Ansible documentation. This is good practice for documentation under active development.
docs/content/configuration/schedules/configuration.md (2)
199-210: Prevent-sleep feature documentation is clear and well-structured.The new section appropriately documents platform availability and important behavioural limitations. This helps users understand when the feature will and won't work as expected.
85-87: Reference path is valid.The internal link to
[Changing Schedule Permissions]({{% relref "/usage/scheduling/change-schedule" %}})correctly references an existing documentation page. No action required.docs/content/usage/configuration/_index.md (1)
1-102: Excellent introduction to configuration files with multi-format examples.The page effectively bridges the gap between raw restic commands and resticprofile configuration. The progression from command-line syntax to each configuration format makes it accessible to users new to resticprofile. The dry-run example output is particularly helpful.
docs/content/configuration/monitoring/tempfilelogging.md (2)
10-77: Well-crafted examples demonstrating the tempFile feature.The multi-format examples clearly show how to use the
tempFiletemplate function with timestamped naming for log management. The use case is well-suited for this documentation format.
6-6: No issues identified. The internal reference to/configuration/variables/templatesis valid and correctly linked; thetemplates.mddocumentation file exists at the expected location within the configuration structure.docs/content/_index.md (1)
7-9: Homepage description is now more concise and focused.The new description clearly conveys resticprofile's core purpose in two sentences. Removing the bulleted feature list aligns well with the Diataxis-informed reorganisation and directs users toward structured documentation rather than marketing copy.
docs/content/configuration/schedules/scheduling_methods/launchd.md (1)
22-22: Image path verified and correctly placed.The image file
removable_volume.pngexists atdocs/content/configuration/schedules/removable_volume.png, and the path reference in the markdown is correctly configured.docs/content/installation/source.md (1)
1-26: LGTM! Simplified installation instructions.The updated installation instructions are clearer and more concise. Adding the requirements upfront and streamlining the build steps improves usability.
docs/content/configuration/profiles/locks.md (1)
3-3: LGTM! Weight adjustment for documentation reorganisation.The weight update aligns with the broader documentation restructuring in this PR.
docs/content/configuration/hooks/copy.md (1)
191-191: LGTM! Formatting cleanup.Minor whitespace adjustment at the end of the file improves consistency.
docs/content/configuration/profiles/path.md (1)
3-3: LGTM! Weight adjustment for documentation reorganisation.The weight update aligns with the broader documentation restructuring in this PR.
docs/content/usage/variables/_index.md (1)
1-8: LGTM! Well-structured index page.The new variables index page correctly uses the Hugo
childrenshortcode to render child pages sorted by weight.docs/content/configuration/schedules/commands.md (2)
6-7: LGTM! TOC addition aligns with documentation pattern.Adding the table of contents shortcode is consistent with other documentation pages in this PR.
62-62: Link target confirmed.The link reference has been updated from
/schedules/examplesto/usage/scheduling. The target documentation page exists atdocs/content/usage/scheduling/_index.mdand will be correctly resolved by the Hugo relref syntax.Makefile (1)
294-294: LGTM! Proper submodule initialisation for documentation builds.Adding the git submodule initialisation and update ensures the Hugo theme is properly available before building the documentation site. This aligns with the submodule pointer update in the theme directory.
docs/content/configuration/hooks/_index.md (1)
1-5: Index page structure looks good.The Hugo front matter is correctly formatted and appropriate for a documentation index page. The
weight: 60ensures proper ordering in the navigation hierarchy, andalwaysopen: falseallows the section to collapse, which is reasonable.docs/themes/hugo-theme-relearn (1)
1-1: Verify the theme submodule update is intentional and compatible.The submodule commit hash has been updated; however, the rationale for this specific version bump is not documented in the commit message or PR description. Confirm this update is necessary to support the documentation reorganisation and that no breaking changes are introduced.
Please verify the following:
- Intentionality: Is this version bump intentional, or was it accidentally included? If intentional, document why this specific theme version is required for the restructured documentation.
- Breaking changes: Check whether the new theme commit (
d9ca8e8d8f592909707aef80e9a1a6b5b37b4b78) introduces any breaking changes or incompatibilities with the documentation restructuring.- CI/CD success: Confirm the documentation build pipeline passes with this theme version (the PR comments indicate local builds succeeded, but verify the CI pipeline also succeeds with this submodule version).
You can inspect the theme repository's changelog or commit history to identify what changed between the previous and current commit to ensure compatibility.
docs/content/configuration/schedules/scheduling_methods/_index.md (1)
1-5: Proper index structure with dynamic children rendering.The index page correctly uses the children shortcode to organize scheduling method sub-pages. Ensure that all expected child pages (launchd, systemd, task_scheduler, etc.) exist and have appropriate weight metadata for correct ordering.
docs/content/configuration/monitoring/status.md (1)
1-8: Front matter updates align with documentation hierarchy restructuring.The title and weight changes fit the broader monitoring section reorganisation. The "Monitoring - Status file" naming pattern is consistent with prometheus.md updates, and the weight 52 provides appropriate ordering.
docs/content/configuration/monitoring/prometheus.md (1)
1-6: Documentation hierarchy updates with corrected cross-reference path.Title and weight changes align with the monitoring section reorganisation. The relref update on line 82 correctly reflects the new location of the status page under
/configuration/monitoring/rather than the previous/monitoring/location. Verify that the target path/configuration/monitoring/status#-extended-statusis correct.Also applies to: 82-82
docs/content/usage/_index.md (1)
1-10: Restructured index page to use dynamic children shortcode.The transition from static content to
{{% children sort="weight" depth="2" %}}is appropriate for the new documentation hierarchy. The front matter changes (pre and weight from 3 to 2) indicate this section moves earlier in navigation. Verify that all expected child pages (hooks, configuration, variables, getting_started, etc.) exist and have correct weight assignments.docs/content/configuration/monitoring/_index.md (1)
1-11: Monitoring section restructuring with proper hierarchy and content extraction.The weight increase to 50 and new
alwaysopen: falseparameter correctly position this section within the documentation hierarchy. The relref to the new tempfilelogging page and {{< toc >}} placeholder align with the broader reorganisation. The removal of the "Send logs to a temporary file" section is appropriate given the extraction to a dedicated page. Verify that/configuration/monitoring/tempfileloggingexists.docs/content/configuration/hooks/run_hooks.md (1)
1-7: Improved page structure with explicit headers and table of contents.The title update aligns with the "Hooks - Commands" naming pattern, and the addition of {{< toc >}} with explicit level-2 headers (lines 138, 209) properly supports the table-of-contents generation. These structural improvements enhance document navigation and accessibility.
Also applies to: 138-138, 209-209
docs/content/usage/scheduling/_index.md (1)
1-131: Well-structured scheduling configuration guide with multi-format examples.The page provides excellent multi-format examples of a complete scheduling configuration, with helpful inline comments (YAML). The children shortcode appropriately links to platform-specific scheduling pages. Verify that expected child pages (linux.md, macos.md, windows.md) exist with proper weight ordering.
docs/content/configuration/variables/env_vars.md (1)
1-21: Comprehensive variable reference documentation.This new reference page provides excellent documentation of pre-defined variables with version annotations. The table structure is clear and the type information (especially the golang time.Time link on line 12) aids understanding. The page is well-organised and fits well within the variable documentation hierarchy.
docs/content/usage/getting_started.md (1)
276-276: Link path update on line 276 is valid.The update from
/schedulesto/configuration/schedulescorrectly points to the existingdocs/content/configuration/schedules/_index.mdfile.docs/content/usage/hooks/body-template.md (1)
8-8:anddocs/content/usage/scheduling/macos.md (1)
29-29: Image path is correct and present in the source tree atdocs/content/configuration/schedules/removable_volume.png. No action required.docs/content/configuration/profiles/inheritance.md (1)
12-12: Link target verified as correct.The path
/configuration/hooks/run_hooksexists in the reorganised documentation structure and the Hugo shortcode syntax is properly formatted. No issues found.
| * [HCL](https://github.com/hashicorp/hcl): files with extension *.hcl* | ||
|
|
||
| * A configuration is a set of _profiles_. | ||
| * A configuration is a set of [_profiles_]({{% relref "/configuration/profiles" %}}). |
There was a problem hiding this comment.
Fix emphasis-style consistency.
Line 14 uses an underscore for emphasis (_profiles_) which violates the project's emphasis style (should use asterisks: *profiles*). This matches the markdownlint-cli2 warning (MD049).
🔎 Proposed fix for emphasis style
-* A configuration is a set of [_profiles_]({{% relref "/configuration/profiles" %}}).
+* A configuration is a set of [*profiles*]({{% relref "/configuration/profiles" %}}).📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| * A configuration is a set of [_profiles_]({{% relref "/configuration/profiles" %}}). | |
| * A configuration is a set of [*profiles*]({{% relref "/configuration/profiles" %}}). |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
14-14: Emphasis style
Expected: asterisk; Actual: underscore
(MD049, emphasis-style)
14-14: Emphasis style
Expected: asterisk; Actual: underscore
(MD049, emphasis-style)
🤖 Prompt for AI Agents
In docs/content/configuration/_index.md around line 14, replace the
underscore-based emphasis `_profiles_` with asterisks `*profiles*` so the line
reads "* A configuration is a set of [*profiles*]({{% relref
\"/configuration/profiles\" %}})." Ensure only the emphasis markers change and
the link/ref syntax stays identical to satisfy MD049.
|
|
||
| We'll show you how to get documentation and auto-completion for the **resticprofile** configuration using [Visual Studio Code](https://code.visualstudio.com/). | ||
|
|
||
| You can use any other editor that recognizes the [JSON schema]({{% relref "/reference/json-schema" %}}). The same JSON schema can be used for JSON, TOML, and YAML file formats. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Verify that referenced documentation and image assets exist.
# Check if the referenced JSON schema documentation exists
echo "=== Searching for JSON schema documentation ==="
find docs -name "*json-schema*" -o -name "*jsonschema*" 2>/dev/null | head -20
# Check if image files exist at the referenced paths
echo "=== Searching for image files ==="
find docs -name "TOML.png" -o -name "YAML.png" 2>/dev/null
# Verify the structure of docs/content/reference directory
echo "=== Reference directory structure ==="
find docs/content/reference -type f 2>/dev/null | head -20
# Verify the structure of docs/content/configuration/profiles directory
echo "=== Configuration/profiles directory structure ==="
ls -la docs/content/configuration/profiles/ 2>/dev/null || echo "Directory not found"Repository: creativeprojects/resticprofile
Length of output: 1190
Fix broken reference link at line 7 — the path uses hyphenation that does not exist.
Line 7 references /reference/json-schema via the relref shortcode, but the actual documentation directory is jsonschema (without hyphen). The link should reference /reference/jsonschema instead. The image paths at lines 15 and 21 are correctly referenced and exist.
🤖 Prompt for AI Agents
In docs/content/configuration/profiles/editorConfig.md around line 7, the relref
link incorrectly points to /reference/json-schema; update the relref target to
/reference/jsonschema (remove the hyphen) so it matches the actual documentation
directory; keep the rest of the sentence unchanged and verify the rendered link
resolves correctly.
| When assuming profile "*backup-homes*" inherits from profile "*base*", then the effective configuration of "*backup-homes*" is built by merging the profile configuration of "*backup-homes*" into "*base*". | ||
|
|
||
| Profile configuration merging follows the same logic as [configuration merging]({{% relref "/configuration/include/index.html#configuration-merging" %}}) in includes: | ||
| Profile configuration merging follows the same logic as [configuration merging]({{% relref "/configuration/profiles/include#configuration-merging" %}}) in includes: |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's look at the actual file and the lines mentioned
echo "=== Inspecting inheritance.md at mentioned lines ==="
cat -n docs/content/configuration/profiles/inheritance.md | sed -n '14,18p; 112,116p; 190,198p; 298,302p'
echo -e "\n=== Checking if target documentation files exist ==="
find docs/content/configuration -name "*.md" -type f | grep -E "(profiles|variables)" | sort
echo -e "\n=== Looking for configuration-merging content ==="
grep -r "configuration-merging\|Configuration merging" docs/content/configuration/ --include="*.md" | head -20Repository: creativeprojects/resticprofile
Length of output: 5870
🏁 Script executed:
# Check for configuration-merging anchor/heading in include.md
echo "=== Searching for configuration-merging in include.md ==="
grep -n "configuration.merging\|Configuration.*[Mm]erging" docs/content/configuration/profiles/include.md | head -20
echo -e "\n=== Checking the actual heading structure in include.md ==="
grep -n "^#" docs/content/configuration/profiles/include.md | head -15
echo -e "\n=== Checking variables/_index.md ==="
grep -n "^#" docs/content/configuration/variables/_index.md
echo -e "\n=== Checking templates.md ==="
grep -n "^#" docs/content/configuration/variables/templates.md | head -10
echo -e "\n=== Checking if index.html reference is needed in Hugo ==="
cat docs/content/configuration/profiles/include.md | head -20Repository: creativeprojects/resticprofile
Length of output: 1682
🏁 Script executed:
# Verify the variables references
echo "=== Checking if /configuration/variables path resolves correctly ==="
ls -la docs/content/configuration/variables/ | grep -E "_index|templates"
echo -e "\n=== Checking Hugo relref usage patterns in the codebase ==="
grep -r "relref" docs/content/configuration/ --include="*.md" | grep -v ".swp" | head -15
echo -e "\n=== Verifying all paths used in inheritance.md ==="
grep -o '{{% relref "[^"]*" %}}' docs/content/configuration/profiles/inheritance.md | sort | uniqRepository: creativeprojects/resticprofile
Length of output: 5228
Update reference syntax to remove redundant index.html for consistency with established patterns.
All target documentation files and anchors verified as present. However, lines 114, 192, and 300 inconsistently include /index.html in their relref paths, whilst line 16 correctly omits it. This deviates from the codebase convention (e.g., /configuration/variables/templates without index.html). Update lines 114, 192, and 300 to use /configuration/profiles/include#configuration-merging instead of /configuration/profiles/include/index.html#configuration-merging, and line 300 to use /configuration/profiles/include instead of /configuration/profiles/include/index.html.
🤖 Prompt for AI Agents
In docs/content/configuration/profiles/inheritance.md around lines 114, 192 and
300, update the inconsistent relref paths that include a redundant
"/index.html": replace any occurrences of
"/configuration/profiles/include/index.html#configuration-merging" with
"/configuration/profiles/include#configuration-merging" on lines 114 and 192,
and on line 300 replace
"/configuration/profiles/include/index.html#configuration-merging" with
"/configuration/profiles/include#configuration-merging" (and any bare
"/configuration/profiles/include/index.html" with
"/configuration/profiles/include"), matching the existing convention used on
line 16.
| Configuration merging is following the same logic as used in [inheritance](#profile-inheritance) and [includes]({{% relref "/configuration/include/index.html#configuration-merging" %}}). When `use` references multiple mixins, the mixins apply in the order they are referenced and can override each other (mixins referenced later override what earlier mixins defined). | ||
| Configuration merging is following the same logic as used in [inheritance](#profile-inheritance) and [includes]({{% relref "/configuration/profiles/include/index.html#configuration-merging" %}}). When `use` references multiple mixins, the mixins apply in the order they are referenced and can override each other (mixins referenced later override what earlier mixins defined). | ||
|
|
||
| Configuration values inside a mixin may be parametrized with variables following the syntax `${variable}` or `$variable`. Defaults for variables can be defined inside the mixin with `default-vars` and `use` can specify variables before merging the mixin. In difference to configuration [variables]({{% relref "/configuration/variables" %}}) that expand prior to parsing, mixin variables expand when the mixin is merged and for this reason the syntax differs. |
There was a problem hiding this comment.
Address grammar issue: missing comma.
Line 194 contains a grammatical error flagged by the static analysis tool. A comma is missing after "when the mixin is merged."
🔎 Proposed fix
-Configuration values inside a mixin may be parametrized with variables following the syntax `${variable}` or `$variable`. Defaults for variables can be defined inside the mixin with `default-vars` and `use` can specify variables before merging the mixin. In difference to configuration [variables]({{% relref "/configuration/variables" %}}) that expand prior to parsing, mixin variables expand when the mixin is merged and for this reason the syntax differs.
+Configuration values inside a mixin may be parametrized with variables following the syntax `${variable}` or `$variable`. Defaults for variables can be defined inside the mixin with `default-vars` and `use` can specify variables before merging the mixin. In difference to configuration [variables]({{% relref "/configuration/variables" %}}) that expand prior to parsing, mixin variables expand when the mixin is merged, and for this reason the syntax differs.Whilst making this correction, consider replacing the wordy phrase "prior to parsing" with the more concise "before parsing" (line 194).
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Configuration values inside a mixin may be parametrized with variables following the syntax `${variable}` or `$variable`. Defaults for variables can be defined inside the mixin with `default-vars` and `use` can specify variables before merging the mixin. In difference to configuration [variables]({{% relref "/configuration/variables" %}}) that expand prior to parsing, mixin variables expand when the mixin is merged and for this reason the syntax differs. | |
| Configuration values inside a mixin may be parametrized with variables following the syntax `${variable}` or `$variable`. Defaults for variables can be defined inside the mixin with `default-vars` and `use` can specify variables before merging the mixin. In difference to configuration [variables]({{% relref "/configuration/variables" %}}) that expand prior to parsing, mixin variables expand when the mixin is merged, and for this reason the syntax differs. |
🧰 Tools
🪛 LanguageTool
[uncategorized] ~194-~194: Possible missing comma found.
Context: ...for variables can be defined inside the mixin with default-vars and use can speci...
(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~194-~194: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ...nfiguration/variables" %}}) that expand prior to parsing, mixin variables expand when th...
(EN_WORDINESS_PREMIUM_PRIOR_TO)
[typographical] ~194-~194: It seems that a comma is missing.
Context: ...d when the mixin is merged and for this reason the syntax differs. Unlike configurati...
(FOR_THIS_REASON_COMMA)
🤖 Prompt for AI Agents
In docs/content/configuration/profiles/inheritance.md around line 194, fix the
grammar by adding a comma after "when the mixin is merged," and simplify "prior
to parsing" to "before parsing"; update the sentence so it reads with the comma
inserted and the phrase replaced while preserving the existing meaning and
punctuation.
| | `<variable-name>` | Set mixin variable `$<variable-name>` (short syntax) | | ||
|
|
||
| Mixins are applied to the configuration after processing all [includes]({{% relref "/configuration/include/index.html" %}}) but prior to [profile inheritance](#profile-inheritance) which means the `use` properties are not inherited but the result of applying `use` is inherited instead. What is defined by a mixin in a parent profile can still be overridden by a definition in a derived profile, but derived profiles can not change which mixins apply to their parent. | ||
| Mixins are applied to the configuration after processing all [includes]({{% relref "/configuration/profiles/include/index.html" %}}) but prior to [profile inheritance](#profile-inheritance) which means the `use` properties are not inherited but the result of applying `use` is inherited instead. What is defined by a mixin in a parent profile can still be overridden by a definition in a derived profile, but derived profiles can not change which mixins apply to their parent. |
There was a problem hiding this comment.
Address grammar inconsistency: "can not" vs "cannot".
Line 300 uses the less common form "can not" instead of the standard "cannot."
🔎 Proposed fix
-Mixins are applied to the configuration after processing all [includes]({{% relref "/configuration/profiles/include/index.html" %}}) but prior to [profile inheritance](#profile-inheritance) which means the `use` properties are not inherited but the result of applying `use` is inherited instead. What is defined by a mixin in a parent profile can still be overridden by a definition in a derived profile, but derived profiles can not change which mixins apply to their parent.
+Mixins are applied to the configuration after processing all [includes]({{% relref "/configuration/profiles/include/index.html" %}}) but prior to [profile inheritance](#profile-inheritance) which means the `use` properties are not inherited but the result of applying `use` is inherited instead. What is defined by a mixin in a parent profile can still be overridden by a definition in a derived profile, but derived profiles cannot change which mixins apply to their parent.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Mixins are applied to the configuration after processing all [includes]({{% relref "/configuration/profiles/include/index.html" %}}) but prior to [profile inheritance](#profile-inheritance) which means the `use` properties are not inherited but the result of applying `use` is inherited instead. What is defined by a mixin in a parent profile can still be overridden by a definition in a derived profile, but derived profiles can not change which mixins apply to their parent. | |
| Mixins are applied to the configuration after processing all [includes]({{% relref "/configuration/profiles/include/index.html" %}}) but prior to [profile inheritance](#profile-inheritance) which means the `use` properties are not inherited but the result of applying `use` is inherited instead. What is defined by a mixin in a parent profile can still be overridden by a definition in a derived profile, but derived profiles cannot change which mixins apply to their parent. |
🧰 Tools
🪛 LanguageTool
[style] ~300-~300: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ...n/profiles/include/index.html" %}}) but prior to [profile inheritance](#profile-inherita...
(EN_WORDINESS_PREMIUM_PRIOR_TO)
[style] ~300-~300: Unless you want to emphasize “not”, use “cannot” which is more common.
Context: ...a derived profile, but derived profiles can not change which mixins apply to their pare...
(CAN_NOT_PREMIUM)
🤖 Prompt for AI Agents
In docs/content/configuration/profiles/inheritance.md around line 300, the
phrase uses the less common "can not" — change it to the standard "cannot" to
correct the grammar; update the sentence so it reads "...but derived profiles
cannot change which mixins apply to their parent."
| ```hcl | ||
| default { | ||
| repository = "azure:restic:/" | ||
| password-file = "key" | ||
| options = "azure.connections=3" | ||
|
|
||
| env { | ||
| AZURE_ACCOUNT_NAME = "my_storage_account" | ||
| AZURE_ACCOUNT_KEY = "my_super_secret_key" | ||
| } | ||
|
|
||
| backup = { | ||
| exclude-file = "excludes" | ||
| exclude-caches = true | ||
| one-file-system = true | ||
| tag = [ "root" ] | ||
| source = [ "/", "/var" ] | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Critical: Inconsistent field names and missing fields in HCL example.
The HCL configuration diverges from the TOML and YAML examples in two ways:
- Line 67: Uses
options(plural) instead ofoption(singular) as shown in TOML (line 17) and YAML (line 41). This will cause configuration errors if users follow the HCL example. - Lines 74–80: The HCL backup section is missing two fields present in TOML (lines 29–30) and YAML (lines 56–57):
scheduleandschedule-after-network-online.
These omissions reduce clarity and may confuse users selecting HCL as their configuration format.
🔎 Proposed fix for the HCL example
default {
repository = "azure:restic:/"
password-file = "key"
- options = "azure.connections=3"
+ option = "azure.connections=3"
env {
AZURE_ACCOUNT_NAME = "my_storage_account"
AZURE_ACCOUNT_KEY = "my_super_secret_key"
}
backup = {
exclude-file = "excludes"
exclude-caches = true
one-file-system = true
tag = [ "root" ]
source = [ "/", "/var" ]
+ schedule = "daily"
+ schedule-after-network-online = true
}
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```hcl | |
| default { | |
| repository = "azure:restic:/" | |
| password-file = "key" | |
| options = "azure.connections=3" | |
| env { | |
| AZURE_ACCOUNT_NAME = "my_storage_account" | |
| AZURE_ACCOUNT_KEY = "my_super_secret_key" | |
| } | |
| backup = { | |
| exclude-file = "excludes" | |
| exclude-caches = true | |
| one-file-system = true | |
| tag = [ "root" ] | |
| source = [ "/", "/var" ] | |
| } | |
| } | |
| ``` | |
| default { | |
| repository = "azure:restic:/" | |
| password-file = "key" | |
| option = "azure.connections=3" | |
| env { | |
| AZURE_ACCOUNT_NAME = "my_storage_account" | |
| AZURE_ACCOUNT_KEY = "my_super_secret_key" | |
| } | |
| backup = { | |
| exclude-file = "excludes" | |
| exclude-caches = true | |
| one-file-system = true | |
| tag = [ "root" ] | |
| source = [ "/", "/var" ] | |
| schedule = "daily" | |
| schedule-after-network-online = true | |
| } | |
| } |
🤖 Prompt for AI Agents
In docs/content/usage/configuration/azure-storage.md around lines 63–82, the HCL
example uses the wrong field name and omits backup scheduling fields; change the
top-level "options" key to the singular "option" to match TOML/YAML, and add the
missing backup fields "schedule" and "schedule-after-network-online" to the
backup block (use the same example values/formats as the TOML/YAML examples so
the HCL example is consistent).
| ```yaml | ||
| version: "1" | ||
|
|
||
| global: | ||
| restic-binary: c:\ProgramData\chocolatey\bin\restic.exe | ||
|
|
||
| # Default profile when not specified on the command line | ||
| # There's no default inheritance from the 'default' profile, | ||
| # but you can use the 'inherit' flag if needed | ||
| default: | ||
| repository: local:r:/ | ||
| password-file: key | ||
| initialize: false | ||
|
|
||
| # New profile named 'test' | ||
| test: | ||
| inherit: default | ||
| initialize: true | ||
|
|
||
| # 'backup' command of profile 'test' | ||
| backup: | ||
| tag: | ||
| - windows | ||
| source: | ||
| - c:\ | ||
| check-after: true | ||
| run-before: dir /l | ||
| run-after: echo All Done! | ||
| # ignore restic warnings | ||
| # without it the backup is considered failed when restic can't read some files | ||
| no-error-on-warning: true | ||
| ``` |
There was a problem hiding this comment.
Escape Windows paths properly in YAML format.
The YAML configuration contains unescaped backslashes in Windows paths, which is inconsistent with the TOML and HCL examples and may cause parsing issues. In YAML, the backslash is an escape character and should be properly handled using single quotes (which treat backslashes literally) or double quotes with escaped backslashes.
Compare against lines 13 and 31 in the TOML section, which correctly use c:\\ProgramData\\ with escaped backslashes.
🔎 Proposed fix for YAML path escaping
global:
- restic-binary: c:\ProgramData\chocolatey\bin\restic.exe
+ restic-binary: 'c:\ProgramData\chocolatey\bin\restic.exe'
# Default profile when not specified on the command line
# There's no default inheritance from the 'default' profile,
@@ -64,7 +64,7 @@ test:
backup:
tag:
- windows
source:
- - c:\
+ - 'c:\'
check-after: trueAlternatively, use double quotes with escaped backslashes to match the TOML/HCL style:
- restic-binary: c:\ProgramData\chocolatey\bin\restic.exe
+ restic-binary: "c:\\ProgramData\\chocolatey\\bin\\restic.exe"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```yaml | |
| version: "1" | |
| global: | |
| restic-binary: c:\ProgramData\chocolatey\bin\restic.exe | |
| # Default profile when not specified on the command line | |
| # There's no default inheritance from the 'default' profile, | |
| # but you can use the 'inherit' flag if needed | |
| default: | |
| repository: local:r:/ | |
| password-file: key | |
| initialize: false | |
| # New profile named 'test' | |
| test: | |
| inherit: default | |
| initialize: true | |
| # 'backup' command of profile 'test' | |
| backup: | |
| tag: | |
| - windows | |
| source: | |
| - c:\ | |
| check-after: true | |
| run-before: dir /l | |
| run-after: echo All Done! | |
| # ignore restic warnings | |
| # without it the backup is considered failed when restic can't read some files | |
| no-error-on-warning: true | |
| ``` |
| - Makes a template profile called "default" [(learn more)]({{% relref "/configuration/variables/templates/" %}}) | ||
| - Creates a `backup` on a schedule every day at 12am [(learn more)]({{% relref "/configuration/schedules/configuration/" %}}) | ||
| - After a fail or success, sends a message through the `ntfy` service using a POST request [(learn more)]({{% relref "/configuration/hooks/http_hooks/" %}}) | ||
| - Creates a `forget` schedule that runs every day at 12:05am | ||
| - Prunes all non-matching entries [(learn more)]({{% relref "/reference/profile/forget/" %}}) | ||
| - Keeps every daily backup for the past week (7 backups), every weekly backup for the past month (4 backups), and a monthly backup for 75 years. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify cross-reference paths in ntfy.md
echo "=== Checking for schedules paths ==="
find docs/content/configuration/schedules -type f -name "*index.md" -o -name "configuration.md" 2>/dev/null | head -20
echo -e "\n=== Checking for hooks paths ==="
find docs/content/configuration/hooks -type f -name "*http*" 2>/dev/null | head -20
echo -e "\n=== Checking for variables/templates paths ==="
find docs/content/configuration/variables -type d -name "templates" 2>/dev/null
echo -e "\n=== Checking for reference/profile/forget paths ==="
find docs/content/reference/profile -type f -name "*forget*" 2>/dev/null
echo -e "\n=== Full structure of docs/content/configuration/schedules ==="
ls -la docs/content/configuration/schedules/ 2>/dev/null || echo "Directory not found"
echo -e "\n=== Full structure of docs/content/reference/profile ==="
ls -la docs/content/reference/profile/ 2>/dev/null || echo "Directory not found"
echo -e "\n=== Checking relref syntax in ntfy.md ==="
cat -n docs/content/usage/hooks/ntfy.md | sed -n '7,12p'Repository: creativeprojects/resticprofile
Length of output: 1917
🏁 Script executed:
#!/bin/bash
# Find where templates and forget documentation actually exist
echo "=== Full structure of docs/content/configuration/variables ==="
ls -la docs/content/configuration/variables/ 2>/dev/null || echo "Directory not found"
echo -e "\n=== Search for 'templates' in docs ==="
find docs/content -type f -name "*template*" 2>/dev/null | grep -E "\.md$"
echo -e "\n=== Full structure of docs/content ==="
ls -la docs/content/
echo -e "\n=== Search for 'forget' in docs ==="
find docs/content -type f -name "*forget*" 2>/dev/null | grep -E "\.md$"
echo -e "\n=== Check if reference directory exists ==="
ls -la docs/content/ | grep reference
echo -e "\n=== Search for profile-related content ==="
find docs/content -type f -name "*profile*" 2>/dev/null | grep -E "\.md$" | head -20Repository: creativeprojects/resticprofile
Length of output: 1453
🏁 Script executed:
#!/bin/bash
# Check reference directory structure
echo "=== Full structure of docs/content/reference ==="
find docs/content/reference -type f -name "*.md" 2>/dev/null
echo -e "\n=== Search for 'forget' content across entire docs ==="
rg -i "forget" docs/content --type md -l 2>/dev/null | head -20
echo -e "\n=== Search for 'prune' or 'retention' (related to forget) ==="
rg -i "prune|retention" docs/content --type md -l 2>/dev/null | head -20
echo -e "\n=== Check if there's a profile-related page ==="
find docs/content -type f -name "*.md" | xargs grep -l "profile" 2>/dev/null | head -10Repository: creativeprojects/resticprofile
Length of output: 1794
Fix broken documentation link on line 11.
The relref path /reference/profile/forget/ on line 11 does not exist. The reference directory is empty and contains no profile/forget/ section. The "forget" functionality is documented within the configuration sections rather than in a dedicated reference page.
Either update the link to point to the correct documentation location (likely within configuration/profiles or configuration/schedules), or remove the link if no suitable reference documentation exists.
Lines 7, 8, and 9 reference valid documentation paths and require no changes.
🤖 Prompt for AI Agents
In docs/content/usage/hooks/ntfy.md around lines 7 to 12, the relref link on
line 11 points to a non-existent /reference/profile/forget/ path; update that
link to the correct documentation location (e.g., change the relref to the
appropriate configuration page such as /configuration/profiles/forget/ or
/configuration/schedules/forget/ if that exists), or if no suitable
configuration page exists, remove the relref markup entirely so the text reads
without a broken link; ensure the surrounding sentence punctuation and spacing
remain correct after the change.
There was a problem hiding this comment.
Invalid flag, reference is auto generated
There was a problem hiding this comment.
@Inventhrice, thank you for the clarification! You're absolutely right — the configuration file reference is generated from resticprofile's data model and restic's manual pages, so the /reference/profile/forget/ path will exist in the built documentation even though the source files aren't present in the repository.
I apologize for the false positive. The relref link is valid and will resolve correctly when Hugo builds the site.
✏️ Learnings added
Learnt from: Inventhrice
Repo: creativeprojects/resticprofile PR: 579
File: docs/content/usage/hooks/ntfy.md:7-12
Timestamp: 2025-12-30T23:33:19.308Z
Learning: In the resticprofile project, the `/docs/content/reference/` directory documentation is auto-generated during the build process from resticprofile's data model and restic's manual pages. The reference section appears empty in the source repository but is populated when the documentation is built. Links using relref to paths like `/reference/profile/forget/` are valid even when the source files don't exist in the repository.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
…eference dir is not in the repo
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/content/installation/docker.md (1)
22-28: Reduce duplication of the docker run example.The Configuration section (lines 24–28) repeats the same
docker runcommand as the introductory example (lines 8–11), with identical volume mounting. Consider removing the duplication by either consolidating the examples or replacing line 27 with a more specific configuration-related example (e.g., passing a custom config file path or environment variable).
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/content/installation/docker.mddocs/content/usage/configuration/configWinheritence.md
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: Inventhrice
Repo: creativeprojects/resticprofile PR: 579
File: docs/content/usage/hooks/ntfy.md:7-12
Timestamp: 2025-12-30T23:33:19.308Z
Learning: In the resticprofile project, the `/docs/content/reference/` directory documentation is auto-generated during the build process from resticprofile's data model and restic's manual pages. The reference section appears empty in the source repository but is populated when the documentation is built. Links using relref to paths like `/reference/profile/forget/` are valid even when the source files don't exist in the repository.
📚 Learning: 2025-02-14T22:53:45.818Z
Learnt from: creativeprojects
Repo: creativeprojects/resticprofile PR: 459
File: examples/windows.yaml:41-41
Timestamp: 2025-02-14T22:53:45.818Z
Learning: Changes to example configurations in the `examples/` directory do not require changelog entries as they are meant for testing and demonstration purposes only.
Applied to files:
docs/content/usage/configuration/configWinheritence.md
📚 Learning: 2025-12-30T23:33:19.308Z
Learnt from: Inventhrice
Repo: creativeprojects/resticprofile PR: 579
File: docs/content/usage/hooks/ntfy.md:7-12
Timestamp: 2025-12-30T23:33:19.308Z
Learning: In the resticprofile project, the `/docs/content/reference/` directory documentation is auto-generated during the build process from resticprofile's data model and restic's manual pages. The reference section appears empty in the source repository but is populated when the documentation is built. Links using relref to paths like `/reference/profile/forget/` are valid even when the source files don't exist in the repository.
Applied to files:
docs/content/installation/docker.md
🔇 Additional comments (4)
docs/content/installation/docker.md (2)
1-18: Good structure and safety documentation.The front matter, explicit Docker image references, concise run command, and warning block about volume mounting and macOS performance are well-organised. The condensed format aligns well with the PR objectives to streamline installation guidance.
30-42: LGTM!The List profiles and Container hostname sections provide useful, distinct examples that complement the installation guidance without duplication.
docs/content/usage/configuration/configWinheritence.md (2)
1-4: Front-matter typo from previous review has been corrected.The
weight: 20metadata is now correctly specified (previously flagged aswieght). Navigation ordering should now be applied as intended.
108-112: Inconsistencies between TOML and YAML configuration examples.The TOML and YAML examples use different paths and scripts, which may confuse readers:
- Source path: TOML uses
./src(line 108); YAML uses~/go(line 243)- Pre-backup script: TOML has
echo Starting! ls -al ./src(line 111); YAML omits "echo Starting!" and usesls -al ~/go(line 240)- Post-backup action: TOML uses
sync(line 112); YAML usesecho All Done!(line 241)Clarify whether these variations are intentional (to demonstrate flexibility) or unintentional misalignment. If examples should be functionally parallel across formats, align them.
Also applies to: 240-241
| --- | ||
| title: "Examples" | ||
| weight: 5 | ||
| title: "Example: Using Inheritance" | ||
| weight: 20 | ||
| --- |
There was a problem hiding this comment.
Fix filename typo: "Winheritence" should be "WithInheritance" or "Inheritance".
The filename configWinheritence.md appears to be a typo. The title is "Example: Using Inheritance" and the content demonstrates configuration inheritance, so the filename should reflect this—likely configWithInheritance.md or configInheritance.md. This filename mismatch could cause confusion and may impact documentation navigation or linking.
🔎 Proposed filename correction
Rename the file from docs/content/usage/configuration/configWinheritence.md to docs/content/usage/configuration/configWithInheritance.md (or similar variant reflecting the content clearly).
🤖 Prompt for AI Agents
In docs/content/usage/configuration/configWinheritence.md lines 1-4, the
filename contains a typo ("Winheritence") that doesn't match the content title
"Example: Using Inheritance"; rename the file to a clear, correct name such as
docs/content/usage/configuration/configWithInheritance.md (or
docs/content/usage/configuration/configInheritance.md), update any
internal/frontmatter references and any links elsewhere in the repo or site
config that point to the old filename to the new filename to preserve navigation
and routing.
2 participants
This is the work I've done so far for the documentation! Let me know your thoughts :)