89
];
90
}
91
92
+/**
93
+ * Identifier URLs cite machine identifiers — OAuth scope URIs and API
94
+ * surface roots such as `https://api.example.com/v3` — not documents. They
95
+ * respond 404 by design, so they must never publish as links the nightly
96
+ * external-link sweep would have to keep alive: they render as code spans.
97
+ */
98
+export function isIdentifierUrl(raw: string): boolean {
99
+ let url: URL;
100
+ try {
101
+ url = new URL(raw);
102
+ } catch {
103
+ return false;
104
+ }
105
+ if ((url.protocol !== 'https:' && url.protocol !== 'http:') || url.search || url.hash) {
106
+ return false;
107
+ }
108
+ // Google OAuth scope URIs (https://www.googleapis.com/auth/…) identify a
109
+ // permission; the namespace serves no pages.
110
+ if (url.hostname === 'www.googleapis.com' && url.pathname.startsWith('/auth/')) {
111
+ return true;
112
+ }
113
+ // An API surface root: a version-only path such as `/v3` or `/v1beta/`.
114
+ // Deep paths (`/v3/tools/X`) stay links because they name real resources.
115
+ return /^\/v\d[\w.-]*\/?$/.test(url.pathname);
116
+}
117
+
118
+/**
119
+ * Wraps bare identifier URLs in code spans. URLs already presented as links —
120
+ * markdown link labels `[url](…)`, link targets `](url)`, and anything
121
+ * adjacent to a code span — keep their form; only bare citations and
122
+ * `<url>` autolinks (normalized earlier) become code.
123
+ */
124
+function identifierUrlsToCodeSpans(segment: string): string {
125
+ return segment.replace(/(?<![`(\]\[])https?:\/\/[^\s`<>\[\]()]+/g, match => {
126
+ // GFM autolinks drop trailing punctuation; keep it outside the code span.
127
+ const url = match.replace(/[.,;:!?'"]+$/, '');
128
+ if (!isIdentifierUrl(url)) return match;
129
+ return `\`${url}\`${match.slice(url.length)}`;
130
+ });
131
+}
132
+
133
function escapeMdxProse(line: string): string {
93
- const escapeSegment = (segment: string): string => segment
94
- .replace(/<(https?:\/\/[^>\s]+)>/g, '[$1]($1)')
95
- .replace(/<([^>\n]+)>/g, '<$1>')
96
- .replace(/\{/g, '{')
97
- .replace(/\}/g, '}');
134
+ const escapeSegment = (segment: string): string => identifierUrlsToCodeSpans(
135
+ segment
136
+ .replace(/<(https?:\/\/[^>\s]+)>/g, (match, url: string) =>
137
+ isIdentifierUrl(url) ? `\`${url}\`` : `[${url}](${url})`)
138
+ .replace(/<([^>\n]+)>/g, '<$1>')
139
+ .replace(/\{/g, '{')
140
+ .replace(/\}/g, '}'),
141
+ );
142
143
let result = '';
144
let cursor = 0;
161
/**
162
* Converts authoritative CommonMark into MDX-safe Markdown. The source and
163
* article snapshots stay verbatim; only the generated presentation escapes MDX
120
- * expressions, normalizes autolinks, and opts support snippets out of Twoslash.
164
+ * expressions, normalizes autolinks, demotes identifier URLs to code spans,
165
+ * and opts support snippets out of Twoslash.
166
*/
167
export function markdownForMdx(markdown: string): string {
168
let fence: { marker: string; length: number } | null = null;