Add clearer guidance for filter return values

docs/development/plugins.md

@@ -125,6 +125,12 @@ The steps to create a filter function are:
 1. hook your function to the particular filter, using YOURLS function `yourls_add_filter()`;
 1. put your custom function and its hook into a plugin file.
 
+:::warning
+
+Even when your Filter doesn't alter the passed value in any way, it **must _return_** the unmodified value!
+
+:::
+
 #### Example of a filter function
 
 When a short URL is created with no custom keyword provided, a random (actually, sequential) keyword is generated. Then this keyword goes through [the following filter](https://github.com/YOURLS/YOURLS/blob/1.7/includes/functions.php#L269):
@@ -151,6 +157,28 @@ function my_silly_function( $original_keyword ) {
 }
 ```
 
+#### Special case: Shunts
+
+Certain filter hooks, which have names starting with `shunt_`, are used to let plugins conditionally tell YOURLS it should skip some actions. For example, you can skip logging/click-tracking for users matching a set of conditions defined by a custom function. Shunts are registered like any other filter:
+
+```php
+yourls_add_filter( 'shunt_update_clicks', 'yp_dont_log_conditional' );
+yourls_add_filter( 'shunt_log_redirect', 'yp_dont_log_conditional' );
+
+function yp_dont_log_conditional($value = yourls_shunt_default()) {
+    if (yp_dont_log_conditions_match()) {
+        return true;
+    }
+    return $value;
+}
+```
+
+:::danger
+
+**Any** non-default return value will trigger the shunt, even `false` or `0`. Unless your plugin's own conditions are met, it should **never** return anything other than the passed-in `$value`.
+
+:::
+
 ### Advanced syntax for hooks
 
 There are different ways to hook functions into actions or filters: read the [advanced hook syntax page](/docs/development/hooks).
@@ -182,7 +210,7 @@ First we need to create the plugin directory and file:
 1. in `user/plugins/` create a new directory, named for instance `my_first_plugin`
 1. create a new empty file named `plugin.php`
 
-**ProTip**: On GitHub, clone this skeleton repository to get yours in seconds: https://github.com/YOURLS/plugin-sample
+**ProTip**: On GitHub, clone this skeleton repository to get yours in seconds: [YOURLS/plugin-sample](https://github.com/YOURLS/plugin-sample)
 
 In this empty `plugin.php` paste the following code: