feat: add clickable anchor links to readme headings (#1417)

Author: essenmitsosse

app/components/Readme.vue

@@ -150,6 +150,16 @@ function handleClick(event: MouseEvent) {
   @apply inline i-lucide:external-link rtl-flip ms-1 opacity-50;
 }
 
+.readme :deep(a[href^='#']::after) {
+  /* I don't know what kind of sorcery this is, but it ensures this icon can't wrap to a new line on its own. */
+  content: '__';
+  @apply inline i-carbon:link rtl-flip ms-1 opacity-0;
+}
+
+.readme :deep(a[href^='#']:hover::after) {
+  @apply opacity-100;
+}
+
 .readme :deep(code) {
   @apply font-mono;
   font-size: 0.875em;

server/utils/readme.ts

@@ -221,16 +221,6 @@ const isNpmJsUrlThatCanBeRedirected = (url: URL) => {
   return true
 }
 
-const replaceHtmlLink = (html: string) => {
-  return html.replace(/href="([^"]+)"/g, (match, href) => {
-    if (isNpmJsUrlThatCanBeRedirected(new URL(href, 'https://www.npmjs.com'))) {
-      const newHref = href.replace(/^https?:\/\/(www\.)?npmjs\.com/, '')
-      return `href="${newHref}"`
-    }
-    return match
-  })
-}
-
 /**
  * Resolve a relative URL to an absolute URL.
  * If repository info is available, resolve to provider's raw file URLs.
@@ -387,7 +377,8 @@ export async function renderReadmeHtml(
       toc.push({ text: plainText, id, depth })
     }
 
-    return `<h${semanticLevel} id="${id}" data-level="${depth}">${text}</h${semanticLevel}>\n`
+    /** The link href uses the unique slug WITHOUT the 'user-content-' prefix, because that will later be added for all links. */
+    return `<h${semanticLevel} id="${id}" data-level="${depth}"><a href="#${uniqueSlug}">${plainText}</a></h${semanticLevel}>\n`
   }
 
   // Syntax highlighting for code blocks (uses shared highlighter)
@@ -443,14 +434,7 @@ ${html}
     return `<blockquote>${body}</blockquote>\n`
   }
 
-  marked.setOptions({
-    renderer,
-    walkTokens: token => {
-      if (token.type === 'html') {
-        token.text = replaceHtmlLink(token.text)
-      }
-    },
-  })
+  marked.setOptions({ renderer })
 
   const rawHtml = marked.parse(content) as string
 

test/unit/server/utils/readme.spec.ts

@@ -388,7 +388,8 @@ describe('HTML output', () => {
     const markdown = `# Title\n\nSome **bold** text and a [link](https://example.com).`
     const result = await renderReadmeHtml(markdown, 'test-pkg')
 
-    expect(result.html).toBe(`<h3 id="user-content-title" data-level="1">Title</h3>
+    expect(result.html)
+      .toBe(`<h3 id="user-content-title" data-level="1"><a href="#user-content-title">Title</a></h3>
 <p>Some <strong>bold</strong> text and a <a href="https://example.com" rel="nofollow noreferrer noopener" target="_blank">link</a>.</p>
 `)
   })