Fix 404 links to rule pages in tspd-generated linter reference (#10501)

Auto-generated linter reference pages (e.g. <a
href="https://typespec.io/docs/libraries/http/reference/linter">`/docs/libraries/http/reference/linter`</a>)
contained broken links to individual rule pages.

### Root cause
`linterRuleLink` in tspd's Starlight (and Docusaurus) emitters stripped
the package's `docusaurusWebsite` prefix from each rule URL and appended
`.md`, producing browser-absolute paths like
`/libraries/http/rules/op-reference-container-route.md`. Because
typespec.io is served under a `/docs/` base path, those links resolve to
`https://typespec.io/libraries/...` and 404.

### Changes
- **`packages/tspd/src/ref-doc/emitters/{starlight,docusaurus}.ts`** —
`linterRuleLink` now takes the `LinterRuleRefDoc` (instead of a URL
string) and the Starlight/Docusaurus emitters simply return
`../rules/${rule.rule.name}.md`. tspd owns the folder structure for
generated rule pages, so the filename can be resolved directly without
parsing URLs or relying on package metadata. Both Astro/Starlight (via
`rehypeAstroRelativeMarkdownLinks`) and Docusaurus rewrite relative
`.md` links into proper site URLs honoring the active base path / host,
so links work in production, local dev, and PR previews. The
`markdown.ts` emitter logic is unchanged.
- **`website/.../http/reference/linter.md`** — regenerated via `pnpm
regen-docs`; the table cell now links to
`../rules/op-reference-container-route.md`.
- **Changelog** — added a `fix` entry for `@typespec/tspd`.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: tadelesh <1726438+tadelesh@users.noreply.github.com>
Co-authored-by: Chenjie Shi <tadelesh.shi@live.cn>

Author: Copilot

.chronus/changes/fix-tspd-linter-rule-link-2026-4-27-8-54-0.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/tspd"
+---
+
+Fix broken (404) links to linter rule pages on auto-generated linter reference pages. The links no longer drop the website base path.

packages/tspd/src/ref-doc/emitters/docusaurus.ts

@@ -1,5 +1,6 @@
 import {
   DeprecationNotice,
+  LinterRuleRefDoc,
   NamedTypeRefDoc,
   RefDocEntity,
   TypeSpecLibraryRefDoc,
@@ -286,14 +287,8 @@ export class DocusaurusRenderer extends MarkdownRenderer {
     }
   }
 
-  linterRuleLink(url: string) {
-    const homepage = (this.refDoc.packageJson as any).docusaurusWebsite;
-    if (homepage && url.includes(homepage)) {
-      const fromRoot = url.replace(homepage, "");
-      return `${fromRoot}.md`;
-    } else {
-      return url;
-    }
+  linterRuleLink(rule: LinterRuleRefDoc) {
+    return `../rules/${rule.rule.name}.md`;
   }
 
   deprecationNotice(notice: DeprecationNotice): MarkdownDoc {

packages/tspd/src/ref-doc/emitters/markdown.ts

@@ -438,13 +438,14 @@ export class MarkdownRenderer {
       ["Name", "Description"],
       ...rules.map((rule) => {
         const name = inlinecode(rule.name);
-        const nameCell = rule.rule.url ? link(name, this.linterRuleLink(rule.rule.url)) : name;
+        const ruleLink = this.linterRuleLink(rule);
+        const nameCell = ruleLink ? link(name, ruleLink) : name;
         return [nameCell, rule.rule.description];
       }),
     ]);
   }
 
-  linterRuleLink(url: string) {
-    return url;
+  linterRuleLink(rule: LinterRuleRefDoc): string | undefined {
+    return rule.rule.url;
   }
 }

packages/tspd/src/ref-doc/emitters/starlight.ts

@@ -1,5 +1,6 @@
 import {
   DeprecationNotice,
+  LinterRuleRefDoc,
   NamedTypeRefDoc,
   RefDocEntity,
   TypeSpecLibraryRefDoc,
@@ -311,14 +312,8 @@ export class StarlightRenderer extends MarkdownRenderer {
     }
   }
 
-  linterRuleLink(url: string) {
-    const homepage = (this.refDoc.packageJson as any).docusaurusWebsite;
-    if (homepage && url.includes(homepage)) {
-      const fromRoot = url.replace(homepage, "");
-      return `${fromRoot}.md`;
-    } else {
-      return url;
-    }
+  linterRuleLink(rule: LinterRuleRefDoc) {
+    return `../rules/${rule.rule.name}.md`;
   }
 
   deprecationNotice(notice: DeprecationNotice): MarkdownDoc {

website/src/content/docs/docs/libraries/http/reference/linter.md

@@ -20,6 +20,6 @@ Available ruleSets:
 
 ## Rules
 
-| Name                                                                                                   | Description                                                                               |
-| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
-| [`@typespec/http/op-reference-container-route`](/libraries/http/rules/op-reference-container-route.md) | Check for referenced (`op is`) operations which have a @route on one of their containers. |
+| Name                                                                                      | Description                                                                               |
+| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| [`@typespec/http/op-reference-container-route`](../rules/op-reference-container-route.md) | Check for referenced (`op is`) operations which have a @route on one of their containers. |