fix: anchor navigation in details README (#254)

Author: Flo0806

app/assets/main.css

@@ -58,6 +58,15 @@ html {
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
   text-rendering: optimizeLegibility;
+  scroll-behavior: smooth;
+  scroll-padding-top: 5rem; /* Offset for fixed header - otherwise anchor headers are cutted */
+}
+
+/* Disable smooth scrolling if user prefers reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  html {
+    scroll-behavior: auto;
+  }
 }
 
 /*

server/utils/readme.ts

@@ -157,6 +157,25 @@ const ALLOWED_ATTR: Record<string, string[]> = {
 // GitHub-style callout types
 // Format: > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION]
 
+/**
+ * Generate a GitHub-style slug from heading text.
+ * - Convert to lowercase
+ * - Remove HTML tags
+ * - Replace spaces with hyphens
+ * - Remove special characters (keep alphanumeric, hyphens, underscores)
+ * - Collapse multiple hyphens
+ */
+function slugify(text: string): string {
+  return text
+    .replace(/<[^>]*>/g, '') // Strip HTML tags
+    .toLowerCase()
+    .trim()
+    .replace(/\s+/g, '-') // Spaces to hyphens
+    .replace(/[^\w\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff-]/g, '') // Keep alphanumeric, CJK, hyphens
+    .replace(/-+/g, '-') // Collapse multiple hyphens
+    .replace(/^-|-$/g, '') // Trim leading/trailing hyphens
+}
+
 /**
  * Resolve a relative URL to an absolute URL.
  * If repository info is available, resolve to provider's raw file URLs.
@@ -165,7 +184,8 @@ const ALLOWED_ATTR: Record<string, string[]> = {
 function resolveUrl(url: string, packageName: string, repoInfo?: RepositoryInfo): string {
   if (!url) return url
   if (url.startsWith('#')) {
-    return url
+    // Prefix anchor links to match heading IDs (avoids collision with page IDs)
+    return `#user-content-${url.slice(1)}`
   }
   if (hasProtocol(url, { acceptRelative: true })) {
     try {
@@ -240,6 +260,9 @@ export async function renderReadmeHtml(
   const collectedLinks: PlaygroundLink[] = []
   const seenUrls = new Set<string>()
 
+  // Track used heading slugs to handle duplicates (GitHub-style: foo, foo-1, foo-2)
+  const usedSlugs = new Map<string, number>()
+
   // Track heading hierarchy to ensure sequential order for accessibility
   // Page h1 = package name, h2 = "Readme" section heading
   // So README starts at h3, and we ensure no levels are skipped
@@ -262,7 +285,21 @@ export async function renderReadmeHtml(
 
     lastSemanticLevel = semanticLevel
     const text = this.parser.parseInline(tokens)
-    return `<h${semanticLevel} data-level="${depth}">${text}</h${semanticLevel}>\n`
+
+    // Generate GitHub-style slug for anchor links
+    let slug = slugify(text)
+    if (!slug) slug = 'heading' // Fallback for empty headings
+
+    // Handle duplicate slugs (GitHub-style: foo, foo-1, foo-2)
+    const count = usedSlugs.get(slug) ?? 0
+    usedSlugs.set(slug, count + 1)
+    const uniqueSlug = count === 0 ? slug : `${slug}-${count}`
+
+    // Prefix with 'user-content-' to avoid collisions with page IDs
+    // (e.g., #install, #dependencies, #versions are used by the package page)
+    const id = `user-content-${uniqueSlug}`
+
+    return `<h${semanticLevel} id="${id}" data-level="${depth}">${text}</h${semanticLevel}>\n`
   }
 
   // Syntax highlighting for code blocks (uses shared highlighter)