migrated over info on redirects

Author: kodster28

public/__redirects

@@ -1312,6 +1312,12 @@
 /stream/platform/ /stream/changelog/ 301
 /stream/reference/ /stream/faq/ 301
 
+# style guide
+
+/docs-guide/manage-content/redirects/ /style-guide/how-we-docs/redirects/ 301
+/docs-guide/manage-content/redirects/best-practices/ /style-guide/how-we-docs/redirects/ 301
+/docs-guide/manage-content/redirects/process/ /style-guide/how-we-docs/redirects/ 301
+
 # support
 
 /support/about-cloudflare/getting-started/troubleshooting-faq-for-new-cloudflare-customers/ /fundamentals/reference/troubleshooting/ 301

src/content/docs/docs-guide/manage-content/redirects/best-practices.mdx

@@ -1,38 +1,37 @@
 ---
 pcx_content_type: concept
 title: Links
-
+meta:
+  title: Links | Component attributes
 ---
 
-## Definition
-
-Reference to data that can be accessed by clicking, tapping, or selecting.
+import { Render } from "~/components";
 
-## Used in
+A link is a reference to another page, part of a page, or external resource.
 
-All content types
+Hyperlinks are incredibly useful but - if overdone - can be distracting.
 
-## Overview
+## Types of links
 
-Hyperlinks are incredibly useful in online content but should not be overdone.  Excessive hyperlinking inside of paragraphs is often distracting and can deviate the reader's focus from the piece at hand.
+<Render file="link-types" />
 
 ## Guidance for inline paragraph links
 
-Avoid non-descriptive link text like: click here and this page; instead, use the actual title of the target page or an abbreviated version of that title. This is also important so that readers see that when they get there, they actually linked to the page they intended to visit.
+Avoid non-descriptive link text like: `click here` and `this page`; instead, use the actual title of the target page or an abbreviated version of that title. This is also important so that readers see that when they get there, they actually linked to the page they intended to visit.
 
 Use unique link text. Speech recognition software does not handle duplicated link text well.
 
-Use in-paragraph links only if they are internal (those within Cloudflare's websites) and if the material relates directly to what's being described.  In other words, will the content behind the link help the reader make a decision or accomplish something before continuing to read the current document?
+Use in-paragraph links only if they are internal (those within Cloudflare's websites) and if the material relates directly to what's being described. In other words, will the content behind the link help the reader make a decision or accomplish something before continuing to read the current document?
 
 Avoid directional language.
 
 ## Links for the Related resources section
 
-Use a *Related resources* section at the end of your document for:
+Use a _Related resources_ section at the end of your document for:
 
-* Internal links that loosely relate to the topic or offer a chance for deeper learning
-* All external links (not residing in Cloudflare's websites)
-* Internal and external links that represent the next logical steps to follow
+- Internal links that loosely relate to the topic or offer a chance for deeper learning
+- All external links (not residing in Cloudflare's websites)
+- Internal and external links that represent the next logical steps to follow
 
 External links placed in-paragraph are strongly discouraged because Cloudflare has no control over them. For example, if a link no longer resolves, our content feels less reliable. By shifting all external links to the end of the document, the impact of a broken link is less dramatic.
 
@@ -42,6 +41,10 @@ Place links for example requests and API calls in code blocks.
 
 Use placeholders in links with account- or user-specific information. And explain what to replace the referential text with.
 
-* For example, for the link "`https://api.cloudflare.com/client/v4/accounts/a0b1c2d3/rulesets`" use "`https://api.cloudflare.com/client/v4/accounts/<ACCOUNTID>/rulesets`" and add text to say "replace `<ACCOUNTID>` with your Account ID" or similar.
+- For example, for the link "`https://api.cloudflare.com/client/v4/accounts/a0b1c2d3/rulesets`" use "`https://api.cloudflare.com/client/v4/accounts/<ACCOUNTID>/rulesets`" and add text to say "replace `<ACCOUNTID>` with your Account ID" or similar.
 
 See [angle brackets](/style-guide/formatting/code-conventions-and-format/) in Code Conventions and Formatting.
+
+## Maintenance
+
+For more details on how we handle link maintenance, refer to [Link maintenance](/style-guide/how-we-docs/links/).

src/content/docs/docs-guide/manage-content/redirects/index.mdx

@@ -4,3 +4,59 @@ title: Links
 meta:
   title: Links | How we docs
 ---
+
+import { Render } from "~/components";
+
+Though [links](/style-guide/documentation-content-strategy/component-attributes/links/) are an important part of documentation, they also have their own maintenance cost.
+
+We have a few strategies we use to make link maintenance easier.
+
+## Link types
+
+<Render file="link-types" />
+
+For each type of link, we think through a few different aspects of the experience.
+
+- **External**:
+  - _Source of truth_: Another site.
+  - _Why does it break_: Another site changed its content.
+  - _Customer experience of a break_: `404` page on another site.
+- **Internal**:
+  - _Source of truth_: Your site.
+  - _Why does it break_: Your site changed its content.
+  - _Customer experience of a break_: `404` page on your site.
+- **Anchor**:
+  - _Source of truth_: Your site.
+  - _Why does it break_: Your site changed its content.
+  - _Customer experience of a break_: Page load on your site. Content might be further down the page or have been moved to another page.
+
+## Checks
+
+### Internal links
+
+Of these three [link types](#link-types), only **Internal** links:
+
+- Happen _within_ the context of a change to your site's content.
+- Universally lead to a bad customer experience (a `404` page).
+- Are easily auditable within the current context.
+
+For these reasons, we choose to **fail** a build based on broken internal links. For our implementation, we rely on the Starlight link validator plugin.
+
+{/* Insert reference to astro.config.ts + links to starlight link plugin + CI build step */}
+
+We also make two intentional decisions about this link auditing:
+
+- **Absolute links, not relative**: We enforce absolute links (`/style-guide/how-we-docs/metadata/`) and fail on relative links (`../metadata/`) to avoid time-consuming maintenance in the future. This decision also helps with find/replace work and any future platform migrations.
+- **No redirects**: We do not consider redirects when evaluating links. We have the current source of truth, so we should utilize that truth to its fullest (as well as helping us avoid redirect chains and future maintenance).
+
+### External links
+
+Though external links are not good for the customer experience, they also don't change within the context of a change to your site's content. Additionally, external link checking can be time consuming and error prone, which can slow down contributions.
+
+We use an external SEO tool to help flag these broken external links for us, addressing them as needed (instead of failing a build on them).
+
+### Anchor links
+
+Anchor links do not have as dramatic as consequences of being wrong as internal links. If you have a broken anchor link, a customer will either need to manually scroll to the header or - in some cases - go to another page.
+
+Because of these characteristics, we run periodic, background checks to flag broken anchor links, using the `htmltest` library.

src/content/docs/docs-guide/manage-content/redirects/process.mdx

@@ -4,3 +4,118 @@ title: Redirects
 meta:
   title: Redirects | How we docs
 ---
+
+import { GlossaryTooltip } from "~/components";
+
+As your content changes (and it will change), <GlossaryTooltip term="redirect">redirects</GlossaryTooltip> preserve continuity for your users and (friendly) bots.
+
+The most obvious part of this is the user experience. If you click a link in the dashboard or use a bookmarked URL, you trust that it's taking you to the right place. Not a `404` page or the wrong page, but the right page. Redirects help direct users to the right place.
+
+The same applies to the automated experience. If you move a page without redirects, you are losing the historical search authority that Google and other search engines use to rank your page.
+
+---
+
+## How we add redirects
+
+### Cloudflare Workers (primary)
+
+Our primary method takes advantage of [Workers Static Assets](/workers/static-assets/redirects/), defining redirects in a [plain text file](https://github.com/cloudflare/cloudflare-docs/blob/production/public/__redirects) in our GitHub repo.
+
+This setup allows us to use the same workflow for redirects as for any other documentation change. We implement a redirect in the same pull request as the content change and can test these changes in our preview branches. For maintenance, we try to keep these redirects [organized](#organize-your-redirects) by product and then — within each product — organized alphabetically.
+
+We also love the flexibility provided by the [Pages syntax](/workers/static-assets/redirects/#advanced-redirects).
+
+### Bulk redirects (secondary)
+
+In certain situations, we also use [Bulk redirects](/rules/url-forwarding/bulk-redirects/). We use this strategy sparing because having redirects in multiple places increases the cognitive load and potential confusion of making a change.
+
+Normally, bulk redirects only come up when another team is adding a large number of individual redirects to our site, such as when all of our previous `support.cloudflare.com` content was migrated and needed individualized redirects per locale.
+
+We use this method when the contributors are outside of our team and when the total number of redirects is so large that it would clutter our `__redirects` file and count against our [limit for redirects](/workers/static-assets/redirects/#surpass-_redirects-limits).
+
+---
+
+## When we add redirects
+
+Our team adds redirects in two situations: during the course of normal content and as needed based on data.
+
+### During content work
+
+During normal content work, you want to add redirects when you do the following to a page:
+
+- Change any part of the URL (filename, folder).
+- Delete the page.
+
+We have some automation to help [flag needed redirects](#potential-redirects).
+
+### Based on data
+
+Another time to add redirects is when you see a lot of `404` response codes on certain paths of your docs site. These `404` responses might be due to a missing redirect or mistyped link.
+
+We identify these status codes either through our [Cloudflare analytics](/analytics/account-and-zone-analytics/zone-analytics/) (ad hoc) or [Logpush job](/logs/about/) (more thorough, quarterly).
+
+---
+
+## How we automate redirects
+
+We have two automations in GitHub to help with redirects.
+
+### Infinite redirects
+
+An infinite redirect is when two pages keep redirecting to each other, trapping users in an infitnite loop that will crash their browser.
+
+Because that’s just a terrible experience, we explicitly check for that as part of our required `CI` GitHub action.
+
+{/* {{ CI step — use GitHub code }} */}
+
+We trigger this check _after_ we build our site. What it does it then call this script.
+
+{/* {{ Infinite redirects — use GitHub code }} */}
+
+{/* Talk through details of the script. */}
+
+### Potential redirects
+
+Contributors often struggle to know when they should add redirects. We try to help them by adding a comment to any pull requests that modify or delete content file paths.
+
+{/* Insert picture of comment */}
+
+{/* Talk through script */}
+
+---
+
+## Other guidance
+
+### Organize your redirects
+
+As much as you can, try to organize your redirects into logical groups (products, alphabetical order). This process helps prevent duplicate redirects, as well as identifying specific ones you might be looking for.
+
+In our [`__redirects` file](https://github.com/cloudflare/cloudflare-docs/blob/production/public/__redirects), we use extensive comments, separating different product areas. We also try, as much as we can, to keep the redirects in alphabetical order within a section.
+
+We used to apply a similar principle to [Bulk Redirect lists](/rules/url-forwarding/bulk-redirects/) (when that was our primary method). We created lists that grouped together similar products and labeled them as such, so it was easier to find which redirect you were looking for.
+
+### Know what you can redirect
+
+At the server level, you can trigger a redirect on a URL path (`/page/`), but not a fragment (`/page/#fragment`).
+
+You can redirect a page to a fragment, however (`/page1/` to `/page2/#fragment`).
+
+### Avoid redirect chains
+
+If possible, have all redirects send your users directly to their destination instead of chaining together redirects.
+
+Otherwise, you can have the following situation:
+
+```txt
+Page 1 --Redirect-> Page 2 --Redirect-> Page 3 --Redirect-> Page 4
+```
+
+A way to avoid this outcome is by continually updating the destinations of previous redirects. For example, let's say you changed the name of this page to `/style-guide/how-we-docs/redirect-guidance/`.
+
+In the pull request to update your redirects file, you would want to update the existing redirect as well as adding a new redirect:
+
+```diff title="__redirects"
+- /style-guide/redirects/ /style-guide/how-we-docs/redirects/ 301
++ /style-guide/redirects/ /style-guide/how-we-docs/redirect-guidance/ 301
++ /style-guide/how-we-docs/redirects/ /style-guide/how-we-docs/redirect-guidance/ 301
+```

src/content/docs/style-guide/documentation-content-strategy/component-attributes/links.mdx

@@ -0,0 +1,9 @@
+---
+{}
+---
+
+There are 3 types of links:
+
+- **External**: To other resources, such as www.cloudflare.com.
+- **Internal**: To other pages in the docs, such as [Workers](/workers/).
+- **Anchor**: To specific parts of other pages in our docs, such as [Proxied records](/dns/proxy-status/#proxied-records).