docs: remove unused _redirects file and document redirect process

blink-so[bot] · blink-so[bot] · commit f63ed978b1fd · 2025-12-08T22:14:41.000Z
The _redirects file format is used by Netlify and Cloudflare Pages, but
coder.com runs on Vercel with Next.js which uses redirects.json in the
coder/coder.com repo instead. This file was never functional.

Changes:
- Remove docs/_redirects (unused)
- Remove _redirects from markdownlint ignore list
- Add URL Redirects section to DOCS_STYLE_GUIDE.md explaining where to
  configure redirects and warning against creating _redirects files
diff --git a/.claude/docs/DOCS_STYLE_GUIDE.md b/.claude/docs/DOCS_STYLE_GUIDE.md
@@ -300,10 +300,22 @@ Some content is auto-generated with comments:
 
 Don't manually edit auto-generated sections.
 
+## URL Redirects
+
+When renaming or moving documentation pages, redirects must be added to prevent broken links.
+
+**Important**: Redirects are NOT configured in this repository. The coder.com website runs on Vercel with Next.js and reads redirects from a separate repository:
+
+- **Redirect configuration**: https://github.com/coder/coder.com/blob/master/redirects.json
+- **Do NOT create** a `docs/_redirects` file - this format (used by Netlify/Cloudflare Pages) is not processed by coder.com
+
+When you rename or move a doc page, create a PR in coder/coder.com to add the redirect.
+
 ## Key Principles
 
 1. **Research first** - Verify against actual code implementation
 2. **Be precise** - Use exact numbers, permission names, API paths
 3. **Visual structure** - Organize around screenshots when available
 4. **Link everything** - Related docs, API endpoints, CLI references
 5. **Manifest inclusion** - Add to manifest.json for navigation
+6. **Add redirects** - When moving/renaming pages, add redirects in coder/coder.com repo
diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
@@ -1,3 +1,3 @@
 {
-	"ignores": ["PLAN.md", "docs/_redirects"],
+	"ignores": ["PLAN.md"],
 }
diff --git a/docs/_redirects b/docs/_redirects

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`{`
`2`		`- "ignores": ["PLAN.md", "docs/_redirects"],`
	`2`	`+ "ignores": ["PLAN.md"],`
`3`	`3`	`}`