Improve comments and fix examples in redirects-map.conf

images/nginx/redirects-map.conf

@@ -1,26 +1,47 @@
-## Nginx redirect map
-## This file is expected to have two entries per line:
-## 1. source, which will be matched against '$host$uri' from nginx (so the hostname and uri, while uri is always at least /)
-## 2. destination of the redirect
-## The file is read from top to bottom, so more specific sources need to be above more general matches
-## A couple of examples:
+#########################
+#  NGINX Redirects Map  #
+#########################
 
-## Simple www to non www redirect, with preserving the URL string and arguments
-# ~^www\.example\.com\/   http://example.com$request_uri;
+# Every line is one rule. A rule has one source for matching and one destination
+# to redirect to. The rules are evaluated from top to bottom until a match is
+# found. More specific rules should come before more general ones. 
+# The rule format is: <source> <destination>;
+#
+# Source: Can be a string literal or a regular expression. It will be tested
+# against the nginx variable `$host$uri`.
+#
+# Destination: Can contain nginx variables, including regular expression matches
+# from the source. Some useful variables are:
+# - $scheme: Request scheme, “http” or “https”
+# - $request_uri: The full original request path with query string
+# - $query_string: Request query string
+#
+# Check the NGINX docs for details about the format and available variables.
+# - https://nginx.org/en/docs/http/ngx_http_map_module.html#map
+# - https://nginx.org/en/docs/varindex.html
 
-## Simple non-www to www redirect, with preserving the URL string and arguments
-#~^example\.com\/   http://www.example.com$request_uri;
+##############
+#  Examples  #
+##############
 
-## Redirect every request to example.com to example.net with preserving the URL string and arguments, eg: example.com/bla -> example.net/bla, example.com/bla?test -> example.net/bla?test
-##
-# ~^example\.com\/   http://example.net$request_uri;
+# Redirect www to non-www (www.example.com/blog?page=2 -> example.com/blog?page=2)
+# ~^www\.example\.com/   $scheme://example.com$request_uri;
+#
+# Redirect non-www to www (example.com/blog?page=2 -> www.example.com/blog?page=2)
+# ~^example\.com/   $scheme://www.example.com$request_uri;
+#
+# Redirect from one domain to another (example.com/blog?page=2 -> example.net/blog?page=2)
+# ~^example\.com/   $scheme://example.net$request_uri;
+#
+# Redirect frome one domain to another,
+# removing a subfolder (example.com/legacy/blog?page=2 -> example.net/blog?page=2)
+# ~*^example\.com/legacy/(.*)   $scheme://example.net/$1$is_args$query_string;
+#
+# Redirect example.com/blog (EXACTLY) to example.net/ (example.com/blog -> example.net)
+# Does not match, e.g., example.com/about-us, example.com/blog?page=2, or example.com/legacy/blog
+# Does not preserve original request path or query string
+# example.com/blog   $scheme://example.net;
 
-## Redirect request only to example.com/test (no regex matching) to example.net without preserving the URL string, eg: example.com/test -> example.net
-## Requestes to example.com/test/bla or example.com/bla are not matched
-##
-# example\.com\/test   http://example.net;
-
-## Redirect request only to example.com/test to example.net with preserving the rest of the URL string and arguments, eg: example.com/test/bla -> example.net/bla, example.com/test/bla?test -> example.net/bla?test
-## Requestes to example.com/bla are not matched
-##
-# ~^example\.com\/test\/(.*)   http://example.net/$1$is_args$args;
+#####################
+#  Add Rules Below  #
+#####################