[VAULT DOCS] Update wonky redirects (#856)

* correcting broken redirects and updating redirect doc

* add some notes about wildcards vs regex

Author: schavis

content/vault/v1.20.x/content/docs/about-vault/how-vault-works.mdx

@@ -7,7 +7,6 @@ description: >-
 
 # How Vault works
 
-
 Vault is an identity-based secrets and encryption management system
 that centralizes secret management, rotates old credentials, generates
 credentials on demand, audits client interactions, and supports regulatory
@@ -35,7 +34,12 @@ them access to secrets or stored sensitive data.
 
 ## Core Vault workflow
 
-Vault works primarily with tokens and a token is associated to the client's policy. Each policy is path-based and policy rules constrains the actions and accessibility to the paths for each client. With Vault, you can create tokens manually and assign them to your clients, or the clients can log in and obtain a token. The illustration below displays Vault's core workflow.
+Vault works primarily with tokens associated to a client policy. The path-based
+policy defines rules that constrain the actions and accessibility of the
+associated paths for each client.
+
+Clients can authenticate against Vault to log in and obtain a token automatically
+or you can create tokens manually and explicitly assign them to your clients.
 
 ![Vault Workflow](/img/vault-workflow-diagram1.png)
 

content/vault/v1.20.x/redirects.jsonc

@@ -30,19 +30,11 @@
     "destination": "/vault/docs/agent-and-proxy/autoauth/methods/alicloud",
     "permanent": true
   },
-  
-  // Explicit redirect for /agent/autoauth because the slug-ed redirect refuses
-  // to work for some reason :\
-  {
-    "source": "/vault/docs/agent/autoauth",
-    "destination": "/vault/docs/agent-and-proxy/autoauth",
-    "permanent": true
-  },
-  
+    
   // Redirect /agent/autoauth/* paths to /agent-and-proxy/autoauth/*
   {
-    "source": "/vault/docs/agent/autoauth/:slug(.*)",
-    "destination": "/vault/docs/agent-and-proxy/autoauth/:slug",
+    "source": "/vault/docs/agent/autoauth/:slug*",
+    "destination": "/vault/docs/agent-and-proxy/autoauth/:slug*",
     "permanent": true
   },
 
@@ -61,8 +53,8 @@
       Range:  1.4.x through 1.13.x
   **/
   {
-    "source": "/vault/docs/:version(v1\\.(?:[4-9]|1[0-3])\\.x)/agent-and-proxy/autoauth/:slug(.*)",
-    "destination": "/vault/docs/:version/agent/autoauth/:slug",
+    "source": "/vault/docs/:version(v1\\.(?:[4-9]|1[0-3])\\.x)/agent-and-proxy/autoauth/:slug*",
+    "destination": "/vault/docs/:version/agent/autoauth/:slug*",
     "permanent": true
   },
 
@@ -91,8 +83,8 @@
     "permanent": true
   },
   {
-    "source": "/vault/docs/:version(v1\\.(?:8|9|1[0-3])\\.x)/agent-and-proxy/agent/caching/:slug(.*)",
-    "destination": "/vault/docs/:version/agent/caching/:slug",
+    "source": "/vault/docs/:version(v1\\.(?:8|9|1[0-3])\\.x)/agent-and-proxy/agent/caching/:slug*",
+    "destination": "/vault/docs/:version/agent/caching/:slug*",
     "permanent": true
   },
   {
@@ -193,8 +185,8 @@
     "permanent": true
   },
   {
-    "source": "/vault/docs/upgrading/deduplication/:slug(.*)",
-    "destination": "/vault/docs/secrets/identity/deduplication/:slug",
+    "source": "/vault/docs/upgrading/deduplication/:slug*",
+    "destination": "/vault/docs/secrets/identity/deduplication/:slug*",
     "permanent": true
   },
 
@@ -375,7 +367,7 @@
       Range: 1.11 through 1.18
   **/
   {
-    "source": "/vault/docs/v:version(1\\.1[1-8]\\.x)/partners",
+    "source": "/vault/docs/v:version(1\\.1[1-8]\\.x)/partners/:slug*",
     "destination": "/vault/docs/v:version/interoperability-matrix",
     "permanent": true
   },
@@ -389,18 +381,18 @@
     "permanent": true
   },
   {
-    "source": "/vault/docs/install/:slug(.*)",
-    "destination": "/vault/docs/get-vault/:slug",
+    "source": "/vault/docs/install/:slug*",
+    "destination": "/vault/docs/get-vault/:slug*",
     "permanent": true
   },
   {
-    "source": "/vault/docs/platform/aws/:slug(.*)",
-    "destination": "/vault/docs/deploy/aws/:slug",
+    "source": "/vault/docs/platform/aws/:slug*",
+    "destination": "/vault/docs/deploy/aws/:slug*",
     "permanent": true
   },
   {
-    "source": "/vault/docs/platform/k8s/:slug(.*)",
-    "destination": "/vault/docs/deploy/kubernetes/:slug",
+    "source": "/vault/docs/platform/k8s/:slug*",
+    "destination": "/vault/docs/deploy/kubernetes/:slug*",
     "permanent": true
   },
 
@@ -539,8 +531,8 @@
 
    // Corrected double-versioned URLs to just take the first version in the string
   {
-    "source": "/vault/docs/:version(v1\\.*\\.x)/v:ver(1\\.*\\.x)/:slug(.*)",
-    "destination": "/vault/docs/:version/:slug",
+    "source": "/vault/docs/:version(v1\\.*\\.x)/v:ver(1\\.*\\.x)/:slug*",
+    "destination": "/vault/docs/:version/:slug*",
     "permanent": true
   }
 ]

docs/redirects.md

@@ -56,18 +56,46 @@ Use redirects for fun and profit!
   URL.
 
 
-## Limitations and gotchas
+## Redirect slugs
 
-- The `developers.hashicorp.com` platform does not support global redirects. The
-  most current docset only knows about redirects associated with that docset.
+There are 3 types of slugs: placeholders, wildcards, and named path parameters.
 
-- You must perpetuate backfacing redirects across future docsets. Otherwise,
-  the most current version of a docset will "forget" how to handle the
-  backfacing redirects.
+### Placeholders
 
-- You cannot split redirects across multiple files. For example, you cannot
-  create a file to define your backfacing redirects and include it in the main
-  redirect file.
+Placeholders only match to a single path section in the source definition.
+
+- Source definition: `:<name>`
+- Destination use: `:<name>`
+
+For example, the source definition `/path/:slug` matches to `path/subpath` but
+not `path`, `path/`, or `/path/subpath/anothersubpath/`.
+
+### Wildcards
+
+Wildcards match to the root path (with or without a trailing slash) and all
+subpaths.
+
+- Source definition: `:<name>*`
+- Destination use: `:<name>*`
+
+For example, the source definition `/path/:slug*` matches to `path`, `path/`,
+`path/subpath`, and `/path/subpath/anothersubpath/`.
+
+You must include the `*` character in the destination URL. Just using the slug
+name will not work properly.
+
+### Named path parameters
+
+Named parameters match to the corresponding pattern or non-capture group.
+Patterns and non-capture groups can include a single path segment, multiple path
+segments, or all subpaths.
+
+- Source definition: `:<name>(<pattern or non-capture group>)`
+- Destination use: `:<name>`
+
+For example, the source definition `/path/:slug(1\\.(?:9\|1[0-5])\\.x)` matches
+to `path/1.9.x` through `path/1.15.x` but not to `path`, `path/` or any other
+subpath.
 
 
 ## Path parameter definition
@@ -117,6 +145,29 @@ Notation | Character set
 
 
 
+## Limitations and gotchas
+
+- Only the most recent redirect file matters.  The `developers.hashicorp.com`
+  platform only compiles redirects from the most recent redirect file.
+
+- You must perpetuate backfacing redirects across future docsets. Otherwise, the
+  most current version of a docset will "forget" how to handle the backfacing
+  redirects.
+
+- You cannot split redirects across multiple files. For example, you cannot
+  create a file to define your backfacing redirects and include it in the main
+  redirect file.
+
+- If you use a non-capture group to capture subpaths, the redirect only works
+  for the root path with the `/` included. For example, a source definition like
+  `/path/:slug(.*)` works for `/path/path1` or `/path/`, but not for `/path`.
+  To capture both forms of the root path, you need to include the `/` character
+  as part of the non-capture group instead of the explicit path. For example,
+  `/path:slug(/?.*)`. Unless you actually need a non-capture group for subpaths,
+  wildcards are typically easier to read.
+
+
+
 ## Example path parameter definitions
 
 Depending on the paths and page names you want to capture, there may be multiple
@@ -219,7 +270,7 @@ Use a non-capture group to redirect all child paths:
 
 ```json
   {
-    "source": "/old/path/:slug(.*)",
+    "source": "/old/path:slug(/?.*)",
     "destination": "/new/path/:slug",
     "permanent": true,
   }