Improve configuration example (#631)

* Add missing parameters
* Remove deprecated `--exclude-file` parameter
* Improve TOML comments
* Add config smoketest

fixtures/configs/smoketest.toml

@@ -0,0 +1,116 @@
+#############################  Display  #############################
+
+# Verbose program output
+verbose = true
+
+# Don't show interactive progress bar while checking links.
+no_progress = true
+
+# Path to summary output file.
+# Commented to avoid creating temporary files.
+# output = "report.md"
+
+#############################  Cache  ###############################
+
+# Enable link caching. This can be helpful to avoid checking the same links on
+# multiple runs.
+cache = false
+
+# Discard all cached requests older than this duration.
+# Error: invalid type: string "2d", expected struct Duration for key `max_cache_age`
+# max_cache_age = "2d"
+
+#############################  Runtime  #############################
+
+# Number of threads to utilize.
+# Defaults to number of cores available to the system if omitted.
+threads = 2
+
+# Maximum number of allowed redirects.
+max_redirects = 10
+
+# Maximum number of allowed retries before a link is declared dead.
+max_retries = 2
+
+# Maximum number of concurrent link checks.
+max_concurrency = 14
+
+#############################  Requests  ############################
+
+# User agent to send with each request.
+user_agent = "curl/7.83.1"
+
+# Website timeout from connect to response finished.
+timeout = 20
+
+# Minimum wait time in seconds between retries of failed requests.
+retry_wait_time = 2
+
+# Comma-separated list of accepted status codes for valid links.
+accept = "403, 403"
+
+# Proceed for server connections considered insecure (invalid TLS).
+insecure = false
+
+# Only test links with the given schemes (e.g. https).
+# Omit to check links with any scheme.
+scheme = [ "https" ]
+
+# When links are available using HTTPS, treat HTTP links as errors.
+require_https = false
+
+# Request method
+method = "get"
+
+# Custom request headers
+headers = []
+
+# Remap URI matching pattern to different URI.
+remap = [ "https://example.com http://example.invalid" ]
+
+# Base URL or website root directory to check relative URLs.
+# Error: invalid type: unit variant, expected newtype variant for key `base`
+# base = "https://example.com"
+
+# HTTP basic auth support. This will be the username and password passed to the
+# authorization HTTP header. See
+# <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization>
+basic_auth = "user:pwd"
+
+#############################  Exclusions  ##########################
+
+# Skip missing input files (default is to error if they don't exist).
+skip_missing = false
+
+# Check links inside `<code>` and `<pre>` blocks as well as Markdown code
+# blocks.
+include_verbatim = false
+
+# Ignore case of paths when matching glob patterns.
+glob_ignore_case = false
+
+# Exclude URLs from checking (supports regex).
+exclude = [ '.*\.github.com\.*' ]
+
+# Exclude these filesystem paths from getting checked.
+exclude_path = ["file/path/to/Ignore", "./other/file/path/to/Ignore"]
+
+# URLs to check (supports regex). Has preference over all excludes.
+include = [ 'gist\.github\.com.*' ]
+
+# Exclude all private IPs from checking.
+# Equivalent to setting `exclude_private`, `exclude_link_local`, and
+# `exclude_loopback` to true.
+exclude_all_private = false
+
+# Exclude private IP address ranges from checking.
+exclude_private = false
+
+# Exclude link-local IP address range from checking.
+exclude_link_local = false
+
+# Exclude loopback IP address range and localhost from checking.
+exclude_loopback = false
+
+# Exclude all mail addresses from checking.
+exclude_mail = false

lychee-bin/src/options.rs

@@ -344,7 +344,7 @@ impl Config {
         // Read configuration file
         let result = fs::read(path);
 
-        // Ignore a file not found error
+        // Ignore a file-not-found error
         let contents = match result {
             Ok(c) => c,
             Err(e) => {

lychee-bin/tests/cli.rs

@@ -553,6 +553,20 @@ mod cli {
             .failure();
     }
 
+    #[tokio::test]
+    async fn test_config_smoketest() {
+        let mock_server = mock_server!(StatusCode::OK);
+        let config = fixtures_path().join("configs").join("smoketest.toml");
+        let mut cmd = main_command();
+        cmd.arg("--config")
+            .arg(config)
+            .arg("-")
+            .write_stdin(mock_server.uri())
+            .env_clear()
+            .assert()
+            .success();
+    }
+
     #[test]
     fn test_lycheeignore_file() -> Result<()> {
         let mut cmd = main_command();

lychee.example.toml

@@ -1,43 +1,62 @@
-###
-### Display
-###
+#############################  Display  #############################
+
 # Verbose program output
 verbose = false
 
-# Show progress
-progress = false
+# Don't show interactive progress bar while checking links.
+no_progress = false
 
+# Path to summary output file.
+output = "report.md"
+
+#############################  Cache  ###############################
+
+# Enable link caching. This can be helpful to avoid checking the same links on
+# multiple runs.
+cache = true
+
+# Discard all cached requests older than this duration.
+# Error: invalid type: string "2d", expected struct Duration for key `max_cache_age`
+# max_cache_age = "2d"
+
+#############################  Runtime  #############################
 
-###
-### Runtime
-###
 # Number of threads to utilize.
 # Defaults to number of cores available to the system if omitted.
-#threads = 2
+threads = 2
 
-# Maximum number of allowed redirects
+# Maximum number of allowed redirects.
 max_redirects = 10
 
+# Maximum number of allowed retries before a link is declared dead.
+max_retries = 2
 
-###
-### Requests
-###
-# User agent to send with each request
-user_agent = "curl/7.71.1"
+# Maximum number of concurrent link checks.
+max_concurrency = 14
 
-# Website timeout from connect to response finished
+#############################  Requests  ############################
+
+# User agent to send with each request.
+user_agent = "curl/7.83. 1"
+
+# Website timeout from connect to response finished.
 timeout = 20
 
-# Comma-separated list of accepted status codes for valid links.
-# Omit to accept all response types.
-#accept = "text/html"
+# Minimum wait time in seconds between retries of failed requests.
+retry_wait_time = 2
 
-# Proceed for server connections considered insecure (invalid TLS)
+# Comma-separated list of accepted status codes for valid links.
+accept = "403, 403"
+
+# Proceed for server connections considered insecure (invalid TLS).
 insecure = false
 
-# Only test links with the given schemes (e.g. https)
-# Omit to check links with any scheme
-#scheme = [ "https" ]
+# Only test links with the given schemes (e.g. https).
+# Omit to check links with any scheme.
+scheme = [ "https" ]
+
+# When links are available using HTTPS, treat HTTP links as errors.
+require_https = false
 
 # Request method
 method = "get"
@@ -45,32 +64,52 @@ method = "get"
 # Custom request headers
 headers = []
 
+# Remap URI matching pattern to different URI.
+remap = [ "https://example.com http://example.invalid" ]
 
-###
-### Exclusions
-###
-# Exclude URLs from checking (supports regex)
-exclude = []
+# Base URL or website root directory to check relative URLs.
+# Error: invalid type: unit variant, expected newtype variant for key `base`
+# base = "https://example.com"
 
-# Exclude URLs contained in a file from checking
-# If a file named `.lycheeignore` exists in the current working directory,
-# its contents will be excluded as well.
-exclude_file = []
+# HTTP basic auth support. This will be the username and password passed to the
+# authorization HTTP header. See
+# <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization>
+basic_auth = "user:pwd"
 
-include = []
+#############################  Exclusions  ##########################
 
-# Exclude all private IPs from checking
-# Equivalent to setting `exclude_private`, `exclude_link_local`, and `exclude_loopback` to true
+# Skip missing input files (default is to error if they don't exist).
+skip_missing = false
+
+# Check links inside `<code>` and `<pre>` blocks as well as Markdown code
+# blocks.
+include_verbatim = false
+
+# Ignore case of paths when matching glob patterns.
+glob_ignore_case = false
+
+# Exclude URLs from checking (supports regex).
+exclude = [ '.*\.github.com\.*' ]
+
+# Exclude these filesystem paths from getting checked.
+exclude_path = ["file/path/to/Ignore", "./other/file/path/to/Ignore"]
+
+# URLs to check (supports regex). Has preference over all excludes.
+include = [ 'gist\.github\.com.*' ]
+
+# Exclude all private IPs from checking.
+# Equivalent to setting `exclude_private`, `exclude_link_local`, and
+# `exclude_loopback` to true.
 exclude_all_private = false
 
-# Exclude private IP address ranges from checking
+# Exclude private IP address ranges from checking.
 exclude_private = false
 
-# Exclude link-local IP address range from checking
+# Exclude link-local IP address range from checking.
 exclude_link_local = false
 
-# Exclude loopback IP address range and localhost from checking
+# Exclude loopback IP address range and localhost from checking.
 exclude_loopback = false
 
-# Exclude all mail addresses from checking
+# Exclude all mail addresses from checking.
 exclude_mail = false