Documentation versioning (#464)

* rephrasing home and getting started pages

* add release notes generated from github releases

* add pageversions shortcode

* add flag to ignore checking documentation on some files

* also ignore in CI

* changelog: remove links to old documentation

* fixes from markdownlint

* remove temporary profile on test config

Author: creativeprojects

.github/workflows/doc.yml

@@ -28,7 +28,7 @@ jobs:
           go-version: ~1.23
 
       - name: Check configuration snippets in documentation
-        run: go run ./config/checkdoc -r docs/content
+        run: go run ./config/checkdoc -r docs/content -i changelog.md
         shell: bash
 
       - name: Build JSON schema & config reference
@@ -55,7 +55,7 @@ jobs:
         with:
           url: "https://${{ env.BRANCH_NAME }}.resticprofile.pages.dev/"
           pages_path: ./public/
-          cmd_params: '--exclude="(linux.die.net|stackoverflow.com)" --buffer-size=8192 --max-connections=10 --color=always --skip-tls-verification --header="User-Agent:curl/7.54.0" --timeout=20'
+          cmd_params: '--exclude="(linux.die.net|stackoverflow.com|scoop.sh)" --buffer-size=8192 --max-connections=10 --color=always --skip-tls-verification --header="User-Agent:curl/7.54.0" --timeout=20'
 
       - name: Publish to pages.dev
         continue-on-error: true # secrets are not set for PRs from forks

.github/workflows/release-doc.yml

@@ -22,7 +22,7 @@ jobs:
           go-version: ~1.23
 
       - name: Check configuration snippets in documentation
-        run: go run ./config/checkdoc -r docs/content
+        run: go run ./config/checkdoc -r docs/content -i changelog.md
         shell: bash
 
       - name: Build JSON schema & config reference
@@ -49,7 +49,7 @@ jobs:
         with:
           url: https://creativeprojects.github.io/resticprofile/
           pages_path: ./www/
-          cmd_params: '--exclude="(linux.die.net|stackoverflow.com)" --buffer-size=8192 --max-connections-per-host=5 --rate-limit=5 --timeout=20 --header="User-Agent:curl/7.54.0" --skip-tls-verification'
+          cmd_params: '--exclude="(linux.die.net|stackoverflow.com|scoop.sh)" --buffer-size=8192 --max-connections-per-host=5 --rate-limit=5 --timeout=20 --header="User-Agent:curl/7.54.0" --skip-tls-verification'
 
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v4

Makefile

@@ -292,12 +292,12 @@ syslog-ng:
 
 checkdoc:
 	@echo "[*] $@"
-	$(GOCMD) run ./config/checkdoc -r docs/content
+	$(GOCMD) run ./config/checkdoc -r docs/content -i changelog.md
 
 .PHONY: checklinks
 checklinks:
 	@echo "[*] $@"
-	muffet -b 8192 --exclude="(linux.die.net|stackoverflow.com)" http://localhost:1313/resticprofile/
+	muffet -b 8192 --max-connections=10 --exclude="(linux.die.net|stackoverflow.com|scoop.sh)" http://localhost:1313/resticprofile/
 
 .PHONY: lint
 lint: $(GOBIN)/golangci-lint

config/checkdoc/main.go

@@ -39,9 +39,11 @@ func main() {
 
 	var root string
 	var verbose bool
+	var ignoreFiles []string
 	pflag.StringVarP(&root, "root", "r", "", "root directory where to search for documentation files (*.md)")
 	pflag.StringVarP(&tempDir, "temp-dir", "t", "", "temporary directory to store extracted configuration files")
 	pflag.BoolVarP(&verbose, "verbose", "v", false, "display more information")
+	pflag.StringSliceVarP(&ignoreFiles, "ignore", "i", nil, "ignore files")
 	pflag.Parse()
 
 	level := clog.LevelInfo
@@ -68,12 +70,18 @@ func main() {
 		if d.IsDir() {
 			return nil
 		}
+		simplePath := strings.TrimPrefix(path, wd)
+		for _, ignore := range ignoreFiles {
+			if strings.Contains(simplePath, ignore) {
+				clog.Infof("* ignoring file %s", simplePath)
+				return nil
+			}
+		}
 		base := filepath.Base(path)
 		ext := filepath.Ext(base)
 		if ext != ".md" {
 			return nil
 		}
-		simplePath := strings.TrimPrefix(path, wd)
 		clog.Infof("* file %s", simplePath)
 		if !extractConfigurationSnippets(path) {
 			exitCode = 1

docs/content/_index.md

@@ -6,41 +6,38 @@ description: Configuration profiles manager for restic backup
 
 Configuration profiles manager for [restic backup](https://restic.net/)
 
-**resticprofile** is the missing link between a configuration file and restic backup. Creating a configuration file for restic has been [discussed before](https://github.com/restic/restic/issues/16), but seems to be a very low priority right now.
+**resticprofile** bridges the gap between a configuration file and restic backup. Although creating a configuration file for restic has been [discussed](https://github.com/restic/restic/issues/16), it remains a low priority.
 
 With resticprofile:
 
-* You no longer need to remember command parameters and environment variables
-* You can create multiple profiles inside one configuration file
-* A profile can inherit all the options from another profile
-* You can run the forget command before or after a backup (in a section called *retention*)
-* You can check a repository before or after a backup
-* You can create groups of profiles that will run sequentially
-* You can run [shell commands]({{% relref "/configuration/run_hooks" %}}) before or after running a profile: useful if you need to mount and unmount your backup disk for example
-* You can run a [shell command]({{% relref "/configuration/run_hooks" %}}) if an error occurred (at any time)
-* You can send a backup stream via _stdin_
-* You can start restic at a lower or higher priority (Priority Class in Windows, *nice* in all unixes) and/or _ionice_ (only available on Linux)
-* It can check that you have [enough memory]({{% relref "/usage/memory" %}}) before starting a backup. (I've had some backups that literally killed a server with swap disabled)
-* You can generate cryptographically secure random keys to use as a restic [key file]({{% relref "/usage/keyfile" %}})
-* You can easily [schedule]({{% relref "/schedules" %}}) backups, retentions and checks (works for *systemd*, *crond*, *launchd* and *windows task scheduler*)
-* You can generate a simple [status file]({{% relref "/status" %}}) to send to some monitoring software and make sure your backups are running fine 
-* You can use a template syntax in your configuration file
-* You can generate scheduled tasks using *crond*
-* Get backup statistics in your [status file]({{% relref "/status" %}})
-* Automatically clear up [stale locks]({{% relref "/usage/locks" %}})
-* Export a [prometheus]({{% relref "/status/prometheus" %}}) file after a backup, or send the report to a push gateway automatically
-* **[new for v0.17.0]** Run shell commands in the background when non fatal errors are detected from restic
-* **[new for v0.18.0]** Send messages to [HTTP hooks]({{% relref "/configuration/http_hooks" %}}) before, after a successful or failed job (backup, forget, check, prune, copy)
-* **[new for v0.18.0]** Automatically initialize the secondary repository using `copy-chunker-params` flag
-* **[new for v0.18.0]** Send resticprofile logs to a syslog server
-* **[new for v0.19.0]** Preventing your system from idle sleeping
-* **[new for v0.21.0]** See the help from both restic and resticprofile via the `help` command or `-h` flag
-* **[new for v0.24.0]** Don't schedule a job when the system is running on battery
-* **[new for v0.29.0]** Scheduling a group of profiles is finally available (configuration `v2` only)
-
-The configuration file accepts various formats:
-* [TOML](https://github.com/toml-lang/toml) : configuration file with extension _.toml_ and _.conf_ to keep compatibility with versions before 0.6.0
-* [JSON](https://en.wikipedia.org/wiki/JSON) : configuration file with extension _.json_
-* [YAML](https://en.wikipedia.org/wiki/YAML) : configuration file with extension _.yaml_
-* [HCL](https://github.com/hashicorp/hcl): configuration file with extension _.hcl_
+* No need to remember command parameters and environment variables
+* Create multiple profiles in one configuration file
+* Profiles can inherit options from other profiles
+* Run the forget command before or after a backup (in a section called *retention*)
+* Check a repository before or after a backup
+* Create groups of profiles to run sequentially
+* Run [shell commands]({{% relref "/configuration/run_hooks" %}}) before or after running a profile, useful for mounting and unmounting backup disks
+* Run a [shell command]({{% relref "/configuration/run_hooks" %}}) if an error occurs
+* Send a backup stream via _stdin_
+* Start restic at different [priorities]({{% relref "/configuration/priority" %}}) (Priority Class in Windows, *nice* in Unix, and/or _ionice_ in Linux)
+* Check for [enough memory]({{% relref "/usage/memory" %}}) before starting a backup
+* Generate cryptographically secure random keys for a restic [key file]({{% relref "/usage/keyfile" %}})
+* Easily [schedule]({{% relref "/schedules" %}}) backups, retentions, and checks (supports *systemd*, *crond*, *launchd*, and *Windows Task Scheduler*)
+* Generate a simple [status file]({{% relref "/status" %}}) for monitoring software to ensure backups are running smoothly
+* Use [template syntax]({{% relref "/configuration/templates" %}}) in your configuration file
+* Automatically clear [stale locks]({{% relref "/usage/locks" %}})
+* Export a [prometheus]({{% relref "/status/prometheus" %}}) file after a backup or send the report to a push gateway
+* Run shell commands in the background when non-fatal errors are detected
+* Send messages to [HTTP hooks]({{% relref "/configuration/http_hooks" %}}) before, after a successful or failed job (backup, forget, check, prune, copy)
+* Automatically [initialize the secondary repository]({{% relref "/configuration/copy" %}}) using the `copy-chunker-params` flag
+* Send resticprofile [logs]({{% relref "/configuration/logs" %}}) to a syslog server
+* Prevent the system from [idle sleeping]({{% relref "/configuration/sleep" %}})
+* View help for both restic and resticprofile via the `help` command or `-h` flag
+* Avoid scheduling a job when the system is on battery
+* **[new for v0.29.0]** Schedule a group of profiles (configuration `v2` only)
 
+The configuration file supports various formats:
+* [TOML](https://github.com/toml-lang/toml): files with extensions *.toml* and *.conf* (for compatibility with versions before 0.6.0)
+* [JSON](https://en.wikipedia.org/wiki/JSON): files with extension *.json*
+* [YAML](https://en.wikipedia.org/wiki/YAML): files with extension *.yaml*
+* [HCL](https://github.com/hashicorp/hcl): files with extension *.hcl*