added headings handling and toc (only scroll behavior needs to be changed

Author: WilcoSp

app/components/Changelog/Card.vue

@@ -7,9 +7,17 @@ const { release } = defineProps<{
 </script>
 <template>
   <section class="border border-border rounded-lg p-4 sm:p-6">
-    <h2 class="text-1xl sm:text-2xl font-medium min-w-0 break-words py-2">
-      {{ release.title }}
-    </h2>
+    <div class="flex justify-between">
+      <h2 class="text-1xl sm:text-2xl font-medium min-w-0 break-words py-2">
+        {{ release.title }}
+      </h2>
+      <ReadmeTocDropdown
+        v-if="release?.toc && release.toc.length > 1"
+        :toc="release.toc"
+        class="justify-self-end"
+      />
+      <!-- :active-id="activeTocId" -->
+    </div>
     <Readme v-if="release.html" :html="release.html"></Readme>
   </section>
 </template>

server/api/changelog/releases/[provider]/[owner]/[repo].ts

@@ -3,7 +3,7 @@ import type { ReleaseData } from '~~/shared/types/changelog'
 import { ERROR_CHANGELOG_RELEASES_FAILED, THROW_INCOMPLETE_PARAM } from '~~/shared/utils/constants'
 import { GithubReleaseCollectionSchama } from '~~/shared/schemas/changelog/release'
 import { parse } from 'valibot'
-import { changelogRenderer, sanitizeRawHTML } from '~~/server/utils/changelog/markdown'
+import { changelogRenderer } from '~~/server/utils/changelog/markdown'
 
 export default defineCachedEventHandler(async event => {
   const provider = getRouterParam(event, 'provider')
@@ -46,15 +46,16 @@ async function getReleasesFromGithub(owner: string, repo: string) {
 
   const render = await changelogRenderer()
 
-  return releases.map(
-    r =>
-      ({
-        id: r.id,
-        html: r.markdown ? sanitizeRawHTML(render(r.markdown) as string) : null,
-        title: r.name,
-        draft: r.draft,
-        prerelease: r.prerelease,
-        publishedAt: r.publishedAt,
-      }) satisfies ReleaseData,
-  )
+  return releases.map(r => {
+    const { html, toc } = render(r.markdown, r.id)
+    return {
+      id: r.id,
+      html,
+      title: r.name,
+      draft: r.draft,
+      prerelease: r.prerelease,
+      toc,
+      publishedAt: r.publishedAt,
+    } satisfies ReleaseData
+  })
 }

server/utils/changelog/markdown.ts

@@ -1,16 +1,64 @@
-import { marked } from 'marked'
-import { ALLOWED_ATTR, ALLOWED_TAGS } from '../readme'
+import { marked, type Tokens } from 'marked'
+import { ALLOWED_ATTR, ALLOWED_TAGS, calculateSemanticDepth, prefixId, slugify } from '../readme'
 import sanitizeHtml from 'sanitize-html'
 
 export async function changelogRenderer() {
   const renderer = new marked.Renderer()
 
-  // settings will need to be added still
+  return (markdown: string | null, releaseId: string | number) => {
+    // Collect table of contents items during parsing
+    const toc: TocItem[] = []
 
-  return (markdown: string) =>
-    marked.parse(markdown, {
-      renderer,
-    })
+    if (!markdown) {
+      return {
+        html: null,
+        toc,
+      }
+    }
+
+    // Track used heading slugs to handle duplicates (GitHub-style: foo, foo-1, foo-2)
+    const usedSlugs = new Map<string, number>()
+
+    // settings will need to be added still
+    let lastSemanticLevel = 2 // Start after h2 (the "Readme" section heading)
+    renderer.heading = function ({ tokens, depth }: Tokens.Heading) {
+      // Calculate the target semantic level based on document structure
+      // Start at h3 (since page h1 + section h2 already exist)
+      // But ensure we never skip levels - can only go down by 1 or stay same/go up
+      const semanticLevel = calculateSemanticDepth(depth, lastSemanticLevel)
+      lastSemanticLevel = semanticLevel
+      const text = this.parser.parseInline(tokens)
+
+      // Generate GitHub-style slug for anchor links
+      // adding release id to prevent conflicts
+      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-${releaseId}-${uniqueSlug}`
+
+      // Collect TOC item with plain text (HTML stripped)
+      const plainText = text.replace(/<[^>]*>/g, '').trim()
+      if (plainText) {
+        toc.push({ text: plainText, id, depth })
+      }
+
+      return `<h${semanticLevel} id="${id}" data-level="${depth}">${text}</h${semanticLevel}>\n`
+    }
+
+    return {
+      html: marked.parse(markdown, {
+        renderer,
+      }) as string,
+      toc,
+    }
+  }
 }
 
 export function sanitizeRawHTML(rawHtml: string) {
@@ -99,11 +147,11 @@ export function sanitizeRawHTML(rawHtml: string) {
       //   attribs.href = resolvedHref
       //   return { tagName, attribs }
       // },
-      // div: prefixId,
-      // p: prefixId,
-      // span: prefixId,
-      // section: prefixId,
-      // article: prefixId,
+      div: prefixId,
+      p: prefixId,
+      span: prefixId,
+      section: prefixId,
+      article: prefixId,
     },
   })
 }

server/utils/readme.ts

@@ -183,7 +183,7 @@ export const ALLOWED_ATTR: Record<string, string[]> = {
  * - Remove special characters (keep alphanumeric, hyphens, underscores)
  * - Collapse multiple hyphens
  */
-function slugify(text: string): string {
+export function slugify(text: string): string {
   return text
     .replace(/<[^>]*>/g, '') // Strip HTML tags
     .toLowerCase()
@@ -319,7 +319,7 @@ function resolveImageUrl(url: string, packageName: string, repoInfo?: Repository
 }
 
 // Helper to prefix id attributes with 'user-content-'
-function prefixId(tagName: string, attribs: sanitizeHtml.Attributes) {
+export function prefixId(tagName: string, attribs: sanitizeHtml.Attributes) {
   if (attribs.id && !attribs.id.startsWith('user-content-')) {
     attribs.id = `user-content-${attribs.id}`
   }
@@ -329,7 +329,7 @@ function prefixId(tagName: string, attribs: sanitizeHtml.Attributes) {
 // README h1 always becomes h3
 // For deeper levels, ensure sequential order
 // Don't allow jumping more than 1 level deeper than previous
-function calculateSemanticDepth(depth: number, lastSemanticLevel: number) {
+export function calculateSemanticDepth(depth: number, lastSemanticLevel: number) {
   if (depth === 1) return 3
   const maxAllowed = Math.min(lastSemanticLevel + 1, 6)
   return Math.min(depth + 2, maxAllowed)

shared/types/changelog.ts

@@ -1,4 +1,5 @@
 import type { ProviderId } from '../utils/git-providers'
+import type { TocItem } from './readme'
 
 export interface ChangelogReleaseInfo {
   type: 'release'
@@ -24,4 +25,5 @@ export interface ReleaseData {
   draft?: boolean
   id: string | number
   publishedAt?: string
+  toc?: TocItem[]
 }