fix: render markdown in deprecated blocks in package docs (#446)

Author: lino-levan

app/pages/docs/[...path].vue

@@ -364,8 +364,16 @@ const showEmptyState = computed(() => docsData.value?.status !== 'ok')
   @apply text-badge-orange text-sm;
 }
 
-.docs-content .docs-deprecated p {
-  @apply text-badge-orange text-sm mt-2 mb-0;
+.docs-content .docs-deprecated-message {
+  @apply text-badge-orange text-sm mt-2;
+}
+
+.docs-content .docs-deprecated-message code {
+  @apply bg-badge-orange/20 text-badge-orange;
+}
+
+.docs-content .docs-deprecated-message .docs-link {
+  @apply text-badge-orange;
 }
 
 /* Parameters, Returns, Examples, See Also sections */

server/utils/docs/render.ts

@@ -184,7 +184,10 @@ async function renderJsDocTags(tags: JsDocTag[], symbolLookup: SymbolLookup): Pr
     lines.push(`<div class="docs-deprecated">`)
     lines.push(`<strong>Deprecated</strong>`)
     if (deprecated.doc) {
-      lines.push(`<p>${parseJsDocLinks(deprecated.doc, symbolLookup)}</p>`)
+      // We remove new lines because they look weird when rendered into the deprecated block
+      // I think markdown is actually supposed to collapse single new lines automatically but this function doesn't do that so if that changes remove this
+      const renderedMessage = await renderMarkdown(deprecated.doc.replace(/\n/g, ' '), symbolLookup)
+      lines.push(`<div class="docs-deprecated-message">${renderedMessage}</div>`)
     }
     lines.push(`</div>`)
   }

server/utils/docs/text.ts

@@ -75,7 +75,7 @@ export function parseJsDocLinks(text: string, symbolLookup: SymbolLookup): strin
 
     // External URL
     if (target.startsWith('http://') || target.startsWith('https://')) {
-      return `<a href="${target}" target="_blank" rel="noopener" class="docs-link">${displayText}</a>`
+      return `<a href="${target}" target="_blank" rel="noreferrer" class="docs-link">${displayText}</a>`
     }
 
     // Internal symbol reference
@@ -116,6 +116,12 @@ export async function renderMarkdown(text: string, symbolLookup: SymbolLookup):
   // Now process the rest (JSDoc links, HTML escaping, etc.)
   result = parseJsDocLinks(result, symbolLookup)
 
+  // Markdown links - i.e. [text](url)
+  result = result.replace(
+    /\[([^\]]+)\]\((https?:\/\/[^)]+)\)/g,
+    '<a href="$2" target="_blank" rel="noreferrer" class="docs-link">$1</a>',
+  )
+
   // Handle inline code (single backticks) - won't interfere with fenced blocks
   result = result
     .replace(/`([^`]+)`/g, '<code class="docs-inline-code">$1</code>')

test/unit/docs-text.spec.ts

@@ -78,7 +78,7 @@ describe('parseJsDocLinks', () => {
     const result = parseJsDocLinks('{@link https://example.com}', emptyLookup)
     expect(result).toContain('href="https://example.com"')
     expect(result).toContain('target="_blank"')
-    expect(result).toContain('rel="noopener"')
+    expect(result).toContain('rel="noreferrer"')
   })
 
   it('should handle external URLs with labels', () => {
@@ -252,4 +252,14 @@ describe('renderMarkdown', () => {
     expect(result).toContain('<code class="docs-inline-code">code</code>')
     expect(result).toContain('shiki')
   })
+
+  it('should handle basic markdown links', async () => {
+    const result = await renderMarkdown(
+      'This [thing](https://example.com) is really important',
+      emptyLookup,
+    )
+    expect(result).toContain(
+      'This <a href="https://example.com" target="_blank" rel="noreferrer" class="docs-link">thing</a> is really important',
+    )
+  })
 })