diff --git a/app/components/Changelog/Card.vue b/app/components/Changelog/Card.vue
index efc8da2cd2..307a2ae7c1 100644
--- a/app/components/Changelog/Card.vue
+++ b/app/components/Changelog/Card.vue
@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import type { IconClass } from '~/types'
 import type { ReleaseData } from '~~/shared/types/changelog'
 import { slugify } from '~~/shared/utils/html'
 
@@ -19,6 +20,14 @@ const navId = computed(() => `release-${slugify(release.title)}`)
 function navigateToTitle() {
   navigateTo(`#${navId.value}`)
 }
+
+const { providerIcon, viewOnProvider } = inject<{
+  providerIcon: MaybeRef<IconClass>
+  viewOnProvider: MaybeRef<string>
+}>('changelog-provider-linkattr', {
+  providerIcon: 'i-lucide:code',
+  viewOnProvider: computed(() => $t('common.view_on.git_repo')),
+})
 </script>
 <template>
   <section
@@ -48,6 +57,12 @@ function navigateToTitle() {
         {{ $t('changelog.draft') }}
       </TagStatic>
       <div class="flex-1" aria-hidden="true"></div>
+      <LinkBase
+        :classicon="providerIcon"
+        :title="viewOnProvider"
+        :to="release.link"
+        class="size-[0.9em]"
+      />
       <ReadmeTocDropdown
         v-if="release?.toc && release.toc.length > 1"
         :toc="release.toc"
diff --git a/app/components/Changelog/Markdown.vue b/app/components/Changelog/Markdown.vue
index 782cd44a40..141e3ede95 100644
--- a/app/components/Changelog/Markdown.vue
+++ b/app/components/Changelog/Markdown.vue
@@ -8,7 +8,7 @@ const { info, goToVersion, tpTarget, resolveVersionPending } = defineProps<{
 
 const route = useRoute()
 
-const { data, error } = await useLazyFetch(
+const { data, error, pending } = useLazyFetch(
   () => `/api/changelog/md/${info.provider}/${info.repo}/${info.path}`,
 )
 
@@ -34,8 +34,11 @@ if (import.meta.client) {
       }
       // lc = lower case
       const lcRequestedVersion = goToVersion.toLowerCase()
+      const isMatching = createHeadingVersionMatcher(lcRequestedVersion)
+
       for (const item of toc) {
-        if (item.text.toLowerCase().includes(lcRequestedVersion)) {
+        const lText = item.text.toLowerCase()
+        if (lText.toLowerCase().includes(lcRequestedVersion) && isMatching(lText)) {
           navigateTo(`#${item.id}`)
           return
         }
@@ -49,9 +52,12 @@ if (import.meta.client) {
 }
 </script>
 <template>
-  <Teleport v-if="data?.toc && data.toc.length > 1 && !!tpTarget" :to="tpTarget">
-    <ReadmeTocDropdown :toc="data.toc" class="justify-self-end" />
-  </Teleport>
-  <Readme v-if="data?.html" :html="data.html" class="pt-4"></Readme>
+  <ChangelogSkeleton v-if="pending" />
+  <template v-else-if="data?.html">
+    <Teleport v-if="data?.toc && data.toc.length > 1 && !!tpTarget" :to="tpTarget">
+      <ReadmeTocDropdown :toc="data.toc" class="justify-self-end" />
+    </Teleport>
+    <Readme :html="data.html" class="pt-4"></Readme>
+  </template>
   <slot v-else-if="error" name="error"></slot>
 </template>
diff --git a/app/components/Changelog/Releases.vue b/app/components/Changelog/Releases.vue
index a65ede945c..f89504d7ff 100644
--- a/app/components/Changelog/Releases.vue
+++ b/app/components/Changelog/Releases.vue
@@ -8,9 +8,11 @@ const { info, requestedDate, goToVersion, resolveVersionPending } = defineProps<
   resolveVersionPending?: boolean
 }>()
 
-const { data: releases, error } = await useLazyFetch<ReleaseData[]>(
-  () => `/api/changelog/releases/${info.provider}/${info.repo}`,
-)
+const {
+  data: releases,
+  error,
+  pending,
+} = useLazyFetch<ReleaseData[]>(() => `/api/changelog/releases/${info.provider}/${info.repo}`)
 
 const route = useRoute()
 
@@ -23,7 +25,7 @@ const matchingDateReleases = computed(() => {
     if (!release.publishedAt) {
       return
     }
-    return requestedDate === toIsoDate(new Date(release.publishedAt))
+    return requestedDate === release.publishedAt.slice(0, 10)
   })
 })
 
@@ -75,7 +77,8 @@ if (import.meta.client) {
 prefetchComponents('ChangelogCard')
 </script>
 <template>
-  <div class="flex flex-col gap-2 py-3" v-if="releases">
+  <ChangelogSkeleton v-if="pending" />
+  <div class="flex flex-col gap-2 py-3" v-else-if="releases">
     <ChangelogCard v-for="release of releases" :release :key="release.id" />
   </div>
   <slot v-else-if="error" name="error"></slot>
diff --git a/app/components/Changelog/Skeleton.vue b/app/components/Changelog/Skeleton.vue
new file mode 100644
index 0000000000..1606140393
--- /dev/null
+++ b/app/components/Changelog/Skeleton.vue
@@ -0,0 +1,11 @@
+<template>
+  <SkeletonBlock class="h-8 w-40 rounded" />
+  <ul class="ms-3 list-disc my-4 ps-6 marker:color-[--border-hover]">
+    <li class="mb-1" v-for="_n in 5">
+      <SkeletonBlock class="h-7 w-full max-w-2xl rounded" />
+    </li>
+  </ul>
+
+  <SkeletonBlock class="h-5 w-5/6 max-w-2xl rounded" />
+  <SkeletonBlock class="h-5 w-3/4 max-w-2xl rounded" />
+</template>
diff --git a/app/components/OgImage/Package.takumi.vue b/app/components/OgImage/Package.takumi.vue
index d61afcb2e8..5779aa4811 100644
--- a/app/components/OgImage/Package.takumi.vue
+++ b/app/components/OgImage/Package.takumi.vue
@@ -18,19 +18,6 @@ import { joinURL } from 'ufo'
 import { useCharts } from '~/composables/useCharts'
 import { createSmoothPath } from 'vue-data-ui/utils'
 
-const REPO_PROVIDER_ICONS: Record<string, string> = {
-  github: 'i-simple-icons:github',
-  gitlab: 'i-simple-icons:gitlab',
-  bitbucket: 'i-simple-icons:bitbucket',
-  codeberg: 'i-simple-icons:codeberg',
-  gitea: 'i-simple-icons:gitea',
-  forgejo: 'i-simple-icons:forgejo',
-  gitee: 'i-simple-icons:gitee',
-  sourcehut: 'i-simple-icons:sourcehut',
-  tangled: 'i-custom:tangled',
-  radicle: 'i-lucide:network',
-}
-
 function sortJsDelivrNodes(nodes: JsDelivrFileNode[]) {
   return [...nodes].sort((a, b) => {
     if (a.type !== b.type) return a.type === 'directory' ? -1 : 1
@@ -76,10 +63,7 @@ const repositoryUrl = computed(() => {
 })
 
 const { repoRef, stars, refresh: refreshRepoMeta } = useRepoMeta(repositoryUrl)
-const repoProviderIcon = computed(() => {
-  const provider = repoRef.value?.provider
-  return provider ? (REPO_PROVIDER_ICONS[provider] ?? 'i-lucide:code') : 'i-lucide:code'
-})
+const repoProviderIcon = useProviderIcon(() => repoRef.value?.provider, 'i-lucide:code')
 
 const formattedStars = computed(() => (stars.value > 0 ? compactFormat.format(stars.value) : ''))
 
diff --git a/app/components/Package/ExternalLinks.vue b/app/components/Package/ExternalLinks.vue
index 9864c23365..c1a3fac963 100644
--- a/app/components/Package/ExternalLinks.vue
+++ b/app/components/Package/ExternalLinks.vue
@@ -1,5 +1,4 @@
 <script setup lang="ts">
-import type { IconClass } from '~/types'
 import type { CommandPaletteContextCommandInput } from '~/types/command-palette'
 
 const props = defineProps<{
@@ -24,24 +23,7 @@ const homepageUrl = computed(() => {
   return homepage
 })
 
-const PROVIDER_ICONS: Record<string, IconClass> = {
-  github: 'i-simple-icons:github',
-  gitlab: 'i-simple-icons:gitlab',
-  bitbucket: 'i-simple-icons:bitbucket',
-  codeberg: 'i-simple-icons:codeberg',
-  gitea: 'i-simple-icons:gitea',
-  forgejo: 'i-simple-icons:forgejo',
-  gitee: 'i-simple-icons:gitee',
-  sourcehut: 'i-simple-icons:sourcehut',
-  tangled: 'i-custom:tangled',
-  radicle: 'i-lucide:network', // Radicle is a P2P network, using network icon
-}
-
-const repoProviderIcon = computed((): IconClass => {
-  const provider = repoRef.value?.provider
-  if (!provider) return 'i-simple-icons:github'
-  return PROVIDER_ICONS[provider] ?? 'i-lucide:code'
-})
+const repoProviderIcon = useProviderIcon(() => repoRef.value?.provider)
 
 const repositoryCommandLabel = computed(() => {
   if (!repoRef.value) {
diff --git a/app/components/Package/Header.vue b/app/components/Package/Header.vue
index 759f751b88..48f0300f12 100644
--- a/app/components/Package/Header.vue
+++ b/app/components/Package/Header.vue
@@ -2,7 +2,6 @@
 import type { RouteLocationRaw } from 'vue-router'
 import type { CommandPaletteContextCommandInput } from '~/types/command-palette'
 import { SCROLL_TO_TOP_THRESHOLD } from '~/composables/useScrollToTop'
-import { usePackageChangelog } from '~/composables/usePackageChangelog'
 
 const props = defineProps<{
   pkg?: Pick<SlimPackument, 'name' | 'versions' | 'dist-tags'> | null
@@ -163,12 +162,15 @@ const diffLink = computed((): RouteLocationRaw | null => {
   return diffRoute(props.pkg.name, props.resolvedVersion, props.latestVersion.version)
 })
 
-const { data: changelog } = usePackageChangelog(packageName, requestedVersion)
-
+const hasChangelog = usePackageHasChangelog(
+  packageName,
+  () => requestedVersion.value || props.resolvedVersion,
+  true,
+)
 const changelogLink = computed((): RouteLocationRaw | null => {
   if (
     // either changelog.value is available or current page is the changelog
-    !(changelog.value || props.page == 'changelog') ||
+    !(hasChangelog.value || props.page == 'changelog') ||
     props.pkg == null ||
     props.resolvedVersion == null
   ) {
diff --git a/app/composables/useCommandPalettePackageCommands.ts b/app/composables/useCommandPalettePackageCommands.ts
index acbb59364c..1f10641278 100644
--- a/app/composables/useCommandPalettePackageCommands.ts
+++ b/app/composables/useCommandPalettePackageCommands.ts
@@ -27,10 +27,7 @@ export function useCommandPalettePackageCommands(
       .includes(packageName)
   }
 
-  const { data: changelog } = usePackageChangelog(
-    () => toValue(context)?.packageName,
-    () => toValue(context)?.resolvedVersion,
-  )
+  const hasChangelog = usePackageHasChangelogFromState()
 
   useCommandPaletteContextCommands(
     computed((): CommandPaletteContextCommandInput[] => {
@@ -109,8 +106,7 @@ export function useCommandPalettePackageCommands(
         },
       ]
 
-      const uChangelog = changelog.value
-      if (uChangelog?.type === 'md' || uChangelog?.type === 'release') {
+      if (hasChangelog.value) {
         commands.push({
           id: 'package-changelog',
           group: 'package',
diff --git a/app/composables/usePackageChangelog.ts b/app/composables/usePackageChangelog.ts
index 11f98b02b1..9df374874b 100644
--- a/app/composables/usePackageChangelog.ts
+++ b/app/composables/usePackageChangelog.ts
@@ -1,13 +1,38 @@
 import type { ChangelogInfo } from '~~/shared/types/changelog'
 
+const key = 'changelog:has:info'
+
 export function usePackageChangelog(
-  packageName: MaybeRefOrGetter<string | null | undefined>,
+  packageName: MaybeRefOrGetter<string>,
   version?: MaybeRefOrGetter<string | null | undefined>,
 ) {
   return useLazyFetch<ChangelogInfo | null>(() => {
     const name = toValue(packageName)
-    if (!name) return 'data:application/json,null' // returns null
     const ver = toValue(version)
     return `/api/changelog/info/${name}/v/${ver || 'latest'}`
   })
 }
+
+/**
+ * check whether the current package & version has changelogs
+ * @param setState with `useState` also set the state of `changelog:info` (currently only for packageHeader)
+ */
+export function usePackageHasChangelog(
+  packageName: MaybeRefOrGetter<string>,
+  version?: MaybeRefOrGetter<string | null | undefined>,
+  setState?: boolean,
+) {
+  const { data } = usePackageChangelog(packageName, version)
+  const hasChangelog = computed(() => data.value?.type == 'md' || data.value?.type == 'release')
+  if (setState) {
+    useState(key, () => hasChangelog)
+  }
+  return hasChangelog
+}
+
+/**
+ * get whether current package has changelog via `useState` (is needed for command pallette)
+ */
+export function usePackageHasChangelogFromState() {
+  return useState<boolean>(key)
+}
diff --git a/app/composables/useProviderIcon.ts b/app/composables/useProviderIcon.ts
index 4da402f42d..99af262331 100644
--- a/app/composables/useProviderIcon.ts
+++ b/app/composables/useProviderIcon.ts
@@ -15,10 +15,13 @@ const PROVIDER_ICONS: Record<ProviderId, IconClass> = {
   radicle: 'i-lucide:network', // Radicle is a P2P network, using network icon
 }
 
-export function useProviderIcon(provider: MaybeRefOrGetter<ProviderId | null | undefined>) {
+export function useProviderIcon(
+  provider: MaybeRefOrGetter<ProviderId | null | undefined>,
+  noProviderIcon: IconClass = 'i-simple-icons:github',
+) {
   return computed((): IconClass => {
     const uProvider = toValue(provider)
-    if (!uProvider) return 'i-simple-icons:github'
+    if (!uProvider) return noProviderIcon
     return PROVIDER_ICONS[uProvider] ?? 'i-lucide:code'
   })
 }
diff --git a/app/pages/package-changelog/[[org]]/[name].vue b/app/pages/package-changelog/[[org]]/[name].vue
index ec52f9a49d..a1c0ed6661 100644
--- a/app/pages/package-changelog/[[org]]/[name].vue
+++ b/app/pages/package-changelog/[[org]]/[name].vue
@@ -47,7 +47,14 @@ const latestVersion = computed(() => {
 // getting info
 const { data: changelog, error: changelogError } = usePackageChangelog(packageName, version)
 
-const repoProviderIcon = useProviderIcon(() => changelog.value?.provider)
+const providerIcon = useProviderIcon(() => changelog.value?.provider)
+const viewOnProvider = useViewOnGitProvider(() => changelog.value?.provider)
+
+provide('changelog-provider-linkattr', {
+  providerIcon,
+  viewOnProvider,
+})
+
 const tptoc = useTemplateRef('tptoc')
 
 const versionDate = computed(() => {
@@ -60,8 +67,6 @@ const versionDate = computed(() => {
   }
 })
 
-const viewOnGit = useViewOnGitProvider(() => changelog.value?.provider)
-
 const packageHeaderHeight = usePackageHeaderHeight()
 const stickyStyle = computed(() => {
   return {
@@ -120,8 +125,8 @@ defineOgImage(
         <LinkBase
           v-if="changelog?.link"
           :to="changelog?.link"
-          :classicon="repoProviderIcon"
-          :title="viewOnGit"
+          :classicon="providerIcon"
+          :title="viewOnProvider"
         >
           {{ changelog.provider }}
         </LinkBase>
@@ -130,62 +135,38 @@ defineOgImage(
         </div>
       </div>
       <section v-if="!changelog && !changelogError" class="flex flex-col gap-2 py-3">
-        <SkeletonBlock class="h-8 w-40 rounded" />
-        <ul class="ms-3 list-disc my-4 ps-6 marker:color-[--border-hover]">
-          <li class="mb-1" v-for="_n in 5">
-            <SkeletonBlock class="h-7 w-full max-w-2xl rounded" />
-          </li>
-        </ul>
-
-        <SkeletonBlock class="h-5 w-5/6 max-w-2xl rounded" />
-        <SkeletonBlock class="h-5 w-3/4 max-w-2xl rounded" />
+        <ChangelogSkeleton />
       </section>
 
-      <Suspense v-else-if="changelog">
-        <template #default>
-          <LazyChangelogReleases
-            v-if="changelog?.type === 'release'"
-            :info="changelog"
-            :requested-date="versionDate"
-            :goToVersion="requestedVersion && version"
-            :resolveVersionPending="resolvingPending"
-            #error
-          >
-            <LazyChangelogErrorMsg
-              :pkgName="pkg?.name"
-              :changelog-link="changelog.link"
-              :viewOnGit
-            />
-          </LazyChangelogReleases>
-          <LazyChangelogMarkdown
-            v-else-if="changelog?.type === 'md'"
-            :info="changelog"
-            :tpTarget="tptoc"
-            :goToVersion="requestedVersion && version"
-            :resolveVersionPending="resolvingPending"
-            #error
-          >
-            <LazyChangelogErrorMsg
-              :pkgName="pkg?.name"
-              :changelog-link="changelog.link"
-              :viewOnGit
-            />
-          </LazyChangelogMarkdown>
-        </template>
-        <template #fallback>
-          <section class="flex flex-col gap-2 py-3">
-            <SkeletonBlock class="h-8 w-40 rounded" />
-            <ul class="ms-3 list-disc my-[1rem] ps-[1.5rem] marker:color-border-hover">
-              <li class="mb-1" v-for="_n in 5">
-                <SkeletonBlock class="h-7 w-full max-w-2xl rounded" />
-              </li>
-            </ul>
-
-            <SkeletonBlock class="h-5 w-5/6 max-w-2xl rounded" />
-            <SkeletonBlock class="h-5 w-3/4 max-w-2xl rounded" />
-          </section>
-        </template>
-      </Suspense>
+      <LazyChangelogReleases
+        v-if="changelog?.type === 'release'"
+        :info="changelog"
+        :requested-date="versionDate"
+        :goToVersion="requestedVersion && version"
+        :resolveVersionPending="resolvingPending"
+        #error
+      >
+        <LazyChangelogErrorMsg
+          :pkgName="pkg?.name"
+          :changelog-link="changelog.link"
+          :viewOnGit="viewOnProvider"
+        />
+      </LazyChangelogReleases>
+      <LazyChangelogMarkdown
+        v-else-if="changelog?.type === 'md'"
+        :info="changelog"
+        :tpTarget="tptoc"
+        :goToVersion="requestedVersion && version"
+        :resolveVersionPending="resolvingPending"
+        #error
+      >
+        <LazyChangelogErrorMsg
+          :pkgName="pkg?.name"
+          :changelog-link="changelog.link"
+          :viewOnGit="viewOnProvider"
+        />
+      </LazyChangelogMarkdown>
+
       <!-- error handling -->
       <p class="mt-5" v-else-if="changelogError?.statusMessage == ERROR_UNGH_API_KEY_EXHAUSTED">
         {{ $t('changelog.rate_limit_ungh') }}
diff --git a/app/utils/header-version-matcher.ts b/app/utils/header-version-matcher.ts
new file mode 100644
index 0000000000..694cf1b266
--- /dev/null
+++ b/app/utils/header-version-matcher.ts
@@ -0,0 +1,12 @@
+// This is used by changelog for matching version in a heading, this is here to allow testing
+
+/**
+ * Check a toc heading if it contains the asked version
+ * @param version the version that needs to match
+ */
+export function createHeadingVersionMatcher(version: string) {
+  // only matches the exact version for normal version, pre releases could match but shouldn't if ordered by release time
+  const escapedVersion = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const versionRegex = new RegExp(`(?<!\\d)(?:v|@)?${escapedVersion}\\b`)
+  return (heading: string) => versionRegex.test(heading)
+}
diff --git a/app/utils/router.ts b/app/utils/router.ts
index c9f2c5247c..a383adf204 100644
--- a/app/utils/router.ts
+++ b/app/utils/router.ts
@@ -32,7 +32,7 @@ export function packageRoute(
 
 /** Full version history page (`/package/.../versions`) */
 export function packageVersionsRoute(packageName: string): RouteLocationRaw {
-  const [org, name = ''] = packageName.startsWith('@') ? packageName.split('/') : ['', packageName]
+  const { org, name } = splitPackageName(packageName)
   return { name: 'package-versions', params: { org, name } }
 }
 
@@ -58,7 +58,7 @@ export function changelogRoute(
   version?: string | null,
   hash?: string,
 ): RouteLocationRaw {
-  const [org, name = ''] = packageName.startsWith('@') ? packageName.split('/') : ['', packageName]
+  const { org, name } = splitPackageName(packageName)
 
   if (version) {
     return {
diff --git a/server/api/changelog/info/[name]/v/[version].get.ts b/server/api/changelog/info/[name]/v/[version].get.ts
index af77ea44ce..b01365900d 100644
--- a/server/api/changelog/info/[name]/v/[version].get.ts
+++ b/server/api/changelog/info/[name]/v/[version].get.ts
@@ -38,7 +38,7 @@ export default defineCachedEventHandler(async event => {
     return await detectChangelog(pkg)
   } catch (error) {
     handleApiError(error, {
-      statusCode: 502,
+      statusCode: 500,
       message: ERROR_PACKAGE_DETECT_CHANGELOG,
     })
   }
diff --git a/server/api/changelog/md/[provider]/[owner]/[repo]/[...path].get.ts b/server/api/changelog/md/[provider]/[owner]/[repo]/[...path].get.ts
index 8b6252bd12..6467eff694 100644
--- a/server/api/changelog/md/[provider]/[owner]/[repo]/[...path].get.ts
+++ b/server/api/changelog/md/[provider]/[owner]/[repo]/[...path].get.ts
@@ -31,7 +31,7 @@ export default defineCachedEventHandler(
       }
     } catch (error) {
       handleApiError(error, {
-        statusCode: 502,
+        statusCode: 500,
         message: ERROR_CHANGELOG_FILE_FAILED,
       })
     }
@@ -46,6 +46,7 @@ export default defineCachedEventHandler(
       const path = getRouterParam(event, 'path') ?? ''
       return `changelogMarkdown:v1:${provider}:${owner}:${repo}:${path.replaceAll('/', ':')}`
     },
+    shouldBypassCache: () => import.meta.dev,
   },
 )
 
diff --git a/server/api/changelog/releases/[provider]/[owner]/[repo].get.ts b/server/api/changelog/releases/[provider]/[owner]/[repo].get.ts
index e7d2b528a5..fa4291cd89 100644
--- a/server/api/changelog/releases/[provider]/[owner]/[repo].get.ts
+++ b/server/api/changelog/releases/[provider]/[owner]/[repo].get.ts
@@ -34,7 +34,7 @@ export default defineCachedEventHandler(
       }
     } catch (error) {
       handleApiError(error, {
-        statusCode: 502,
+        statusCode: 500,
         message: ERROR_CHANGELOG_RELEASES_FAILED,
       })
     }
@@ -46,8 +46,9 @@ export default defineCachedEventHandler(
       const provider = getRouterParam(event, 'provider')
       const repo = getRouterParam(event, 'repo')
       const owner = getRouterParam(event, 'owner')
-      return `changelogRelease:v1:${provider}:${owner}:${repo}`
+      return `changelogRelease:v1_1:${provider}:${owner}:${repo}`
     },
+    shouldBypassCache: () => import.meta.dev,
   },
 )
 
@@ -77,6 +78,7 @@ async function getReleasesFromGithub(owner: string, repo: string) {
       prerelease: r.prerelease,
       toc,
       publishedAt: r.publishedAt,
+      link: `https://github.com/${owner}/${repo}/releases/tag/${r.tag}`,
     } satisfies ReleaseData
   })
 }
diff --git a/server/utils/changelog/detectChangelog.ts b/server/utils/changelog/detectChangelog.ts
index 6f8393a4af..0ccea9e5bf 100644
--- a/server/utils/changelog/detectChangelog.ts
+++ b/server/utils/changelog/detectChangelog.ts
@@ -1,9 +1,5 @@
-import type {
-  ChangelogMarkdownInfo,
-  ChangelogInfo,
-  ChangelogReleaseInfo,
-} from '~~/shared/types/changelog'
-import type { FetchError } from 'ofetch'
+import type { ChangelogMarkdownInfo, ChangelogInfo } from '~~/shared/types/changelog'
+import { FetchError } from 'ofetch'
 import type { ExtendedPackageJson } from '~~/shared/utils/package-analysis'
 import { type RepoRef, parseRepoUrl } from '~~/shared/utils/git-providers'
 import { ERROR_CHANGELOG_NOT_FOUND, ERROR_UNGH_API_KEY_EXHAUSTED } from '~~/shared/utils/constants'
@@ -68,50 +64,56 @@ async function checkReleases(
 const MD_REGEX = /(?<=\[.*?(changelog|releases|changes|history|news)\.md.*?\]\()(.*?)(?=\))/i
 const ROOT_ONLY_REGEX = /^\/[^/]+$/
 
-function checkLatestGithubRelease(
+async function checkLatestGithubRelease(
   ref: RepoRef,
   directory?: string,
 ): Promise<ChangelogInfo | false | Error> {
-  return $fetch(`https://ungh.cc/repos/${ref.owner}/${ref.repo}/releases/latest`)
-    .then(r => {
-      const { release } = v.parse(v.object({ release: GithubReleaseSchama }), r)
-
-      const matchedChangelog = release.markdown?.match(MD_REGEX)?.at(0)
-
-      // if no changelog.md or the url doesn't contain /blob/
-      if (!matchedChangelog || !matchedChangelog.includes('/blob/')) {
-        return {
-          provider: ref.provider,
-          type: 'release',
-          repo: `${ref.owner}/${ref.repo}`,
-          link: `https://github.com/${ref.owner}/${ref.repo}/releases`,
-        } satisfies ChangelogReleaseInfo
-      }
+  try {
+    const response = await $fetch(`https://ungh.cc/repos/${ref.owner}/${ref.repo}/releases/latest`)
 
-      const path = matchedChangelog.replace(/^.*\/blob\/[^/]+\//i, '')
+    const { release } = v.parse(v.object({ release: GithubReleaseSchama }), response)
 
-      if (directory && !(path.startsWith(directory) || ROOT_ONLY_REGEX.test(path))) {
-        return false as const
-      }
+    const matchedChangelog = release.markdown?.match(MD_REGEX)?.at(0)
+
+    // if no changelog.md or the url doesn't contain /blob/
+    if (!matchedChangelog || !matchedChangelog.includes('/blob/')) {
       return {
         provider: ref.provider,
-        type: 'md',
-        path,
+        type: 'release',
         repo: `${ref.owner}/${ref.repo}`,
-        link: matchedChangelog,
-      } satisfies ChangelogMarkdownInfo
-    })
-    .catch((e: FetchError) => {
-      if (e.statusCode === 403 || e.statusCode === 429) {
-        // with 403/429 ungh.cc has exhausted it's api keys, returning error to indicate this
-        return createError({
-          statusCode: 502,
-          statusMessage: ERROR_UNGH_API_KEY_EXHAUSTED,
-        })
+        link: `https://github.com/${ref.owner}/${ref.repo}/releases`,
       }
+    }
 
+    const path = matchedChangelog.replace(/^.*\/blob\/[^/]+\//i, '')
+
+    // makes sure that the correct directory is matched
+    if (
+      directory &&
+      !(
+        path.startsWith(directory.endsWith('/') ? directory : `${directory}/`) ||
+        ROOT_ONLY_REGEX.test(path)
+      )
+    ) {
       return false as const
-    })
+    }
+    return {
+      provider: ref.provider,
+      type: 'md',
+      path,
+      repo: `${ref.owner}/${ref.repo}`,
+      link: matchedChangelog,
+    }
+  } catch (e) {
+    if (e instanceof FetchError && (e.statusCode === 403 || e.statusCode === 429)) {
+      return createError({
+        statusCode: 502,
+        statusMessage: ERROR_UNGH_API_KEY_EXHAUSTED,
+      })
+    }
+  }
+
+  return false as const
 }
 
 /// changelog markdown
diff --git a/server/utils/changelog/markdown.ts b/server/utils/changelog/markdown.ts
index 7557f3150a..5a309cc884 100644
--- a/server/utils/changelog/markdown.ts
+++ b/server/utils/changelog/markdown.ts
@@ -1,231 +1,103 @@
-import { type Tokens, marked } from 'marked'
 import {
-  type prefixId as prefixIdFn,
-  ALLOWED_ATTR,
-  ALLOWED_TAGS,
-  calculateSemanticDepth,
+  type ProcessImageUrlFn,
+  type ProcessLinkFn,
+  type ToUserContentIdFn,
+  USER_CONTENT_PREFIX,
+  blockquote,
+  createCodeHighlighter,
+  createHeading,
+  createHtml,
+  createImage,
+  createLink,
+  decodeHashFragment,
   isNpmJsUrlThatCanBeRedirected,
-} from '../readme'
-import { stripHtmlTags, slugify } from '#shared/utils/html'
-import sanitizeHtml from 'sanitize-html'
-import { hasProtocol } from 'ufo'
-
-const EMAIL_REGEX = /^[\w+\-.]+@[\w\-.]+\.[a-z]+$/i
+  markedHeadingExtension,
+  renderToRawHtml,
+  sanitizeRawHTML,
+} from '../mdKit'
+import { slugify } from '#shared/utils/html'
+import { marked } from 'marked'
+import { hasProtocol, joinRelativeURL, parseFilename } from 'ufo'
+import { convertToEmoji } from '#shared/utils/emoji'
 
 export async function changelogRenderer(mdRepoInfo: MarkdownRepoInfo) {
   const renderer = new marked.Renderer({
     gfm: true,
   })
 
-  const shiki = await getShikiHighlighter()
-
-  renderer.link = function ({ href, title, tokens }: Tokens.Link) {
-    const eTitle = escapeHtml(title ?? '')
-    const text = this.parser.parseInline(tokens)
-    const titleAttr = eTitle ? ` title="${eTitle}"` : ''
-    const plainText = escapeHtml(stripHtmlTags(text).trim())
-
-    if (href.startsWith('mailto:') && !EMAIL_REGEX.test(plainText)) {
-      return text
-    }
-
-    const intermediateTitleAttr = `data-title-intermediate="${plainText || eTitle}"`
-
-    return `<a href="${href}"${titleAttr}${intermediateTitleAttr} target="_blank">${text}</a>`
-  }
+  marked.use({
+    tokenizer: {
+      heading: markedHeadingExtension,
+    },
+  })
 
   // GitHub-style callouts: > [!NOTE], > [!TIP], etc.
-  renderer.blockquote = function ({ tokens }: Tokens.Blockquote) {
-    const body = this.parser.parse(tokens)
-
-    const calloutMatch = body.match(/^<p>\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\](?:<br>)?\s*/i)
-
-    if (calloutMatch?.[1]) {
-      const calloutType = calloutMatch[1].toLowerCase()
-      const cleanedBody = body.replace(calloutMatch[0], '<p>')
-      return `<blockquote data-callout="${calloutType}">${cleanedBody}</blockquote>\n`
-    }
-
-    return `<blockquote>${body}</blockquote>\n`
-  }
+  renderer.blockquote = blockquote
 
   // Syntax highlighting for code blocks (uses shared highlighter)
-  renderer.code = ({ text, lang }: Tokens.Code) => {
-    const html = highlightCodeSync(shiki, text, lang || 'text')
-    // Add copy button
-    return `<div class="readme-code-block" >
-  <button type="button" class="readme-copy-button" aria-label="Copy code" check-icon="i-carbon:checkmark" copy-icon="i-carbon:copy" data-copy>
-  <span class="i-carbon:copy" aria-hidden="true"></span>
-  <span class="sr-only">Copy code</span>
-  </button>
-  ${html}
-  </div>`
-  }
+  renderer.code = await createCodeHighlighter()
 
-  return (markdown: string | null, releaseId?: string | number) => {
+  return (markdownBody: string | null, releaseId?: string | number) => {
     // Collect table of contents items during parsing
-    const toc: TocItem[] = []
+    // const toc: TocItem[] = []
 
-    if (!markdown) {
+    if (!markdownBody) {
       return {
         html: null,
-        toc,
+        toc: [],
       }
     }
 
     const idPrefix = releaseId ? `user-content-${releaseId}` : `user-content`
 
-    // Track used heading slugs to handle duplicates (GitHub-style: foo, foo-1, foo-2)
-    const usedSlugs = new Map<string, number>()
+    const lastSemanticLevel = releaseId ? 2 : 1
 
-    let lastSemanticLevel = releaseId ? 2 : 1 // 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)
+    function toUserContentId(id: string) {
+      return `${idPrefix}-${id}`
+    }
 
-      // 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
+    const processLink: ProcessLinkFn = (href: string, _label: string) => {
+      const resolvedHref = resolveUrl(href, mdRepoInfo, toUserContentId)
 
-      // 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}`
+      // Security attributes for external links
+      let extraAttrs =
+        resolvedHref && hasProtocol(resolvedHref, { acceptRelative: true })
+          ? ' rel="nofollow noreferrer noopener" target="_blank"'
+          : ''
 
-      // Prefix with 'user-content-' to avoid collisions with page IDs
-      // (e.g., #install, #dependencies, #versions are used by the package page)
-      const id = `${idPrefix}-${uniqueSlug}`
+      return { resolvedHref, extraAttrs }
+    }
 
-      // Collect TOC item with plain text (HTML stripped & emoji's added)
-      const plainText = convertToEmoji(stripHtmlTags(text))
-        .replace(/&nbsp;?/g, '') // remove non breaking spaces
-        .trim()
-      if (plainText) {
-        toc.push({ text: plainText, id, depth })
-      }
+    renderer.link = createLink(processLink)
 
-      return `<h${semanticLevel} id="${id}" data-level="${depth}">${text} <a href="#${id}"> </a></h${semanticLevel}>\n`
-    }
+    const { heading, toc, processHeading } = createHeading({
+      lastSemanticLevel,
+      toUserContentId,
+    })
+    renderer.heading = heading
 
-    // Helper to prefix id attributes with 'user-content-'
-    const prefixId: typeof prefixIdFn = (tagName: string, attribs: sanitizeHtml.Attributes) => {
-      if (attribs.id && !attribs.id.startsWith('user-content-')) {
-        attribs.id = `${idPrefix}-${attribs.id}`
-      }
-      return { tagName, attribs }
-    }
+    renderer.html = createHtml({ processHeading, processLink })
+
+    const processImageUrl: ProcessImageUrlFn = href =>
+      resolveImageUrl(href, mdRepoInfo, toUserContentId)
+
+    renderer.image = createImage(processImageUrl)
+
+    const rawHtml = renderToRawHtml({ renderer, markdownBody })
 
     return {
-      html: sanitizeRawHTML(
-        convertToEmoji(
-          marked.parse(markdown, {
-            renderer,
-          }) as string,
-        ),
-        mdRepoInfo,
-        prefixId,
-        idPrefix,
-      ),
+      html: sanitizeRawHTML(convertToEmoji(rawHtml), {
+        processImageUrl,
+        processLink,
+        toUserContentId,
+        lastSemanticLevel,
+      }),
       toc,
     }
   }
 }
 
-export function sanitizeRawHTML(
-  rawHtml: string,
-  mdRepoInfo: MarkdownRepoInfo,
-  prefixId: typeof prefixIdFn,
-  idPrefix: string,
-) {
-  return sanitizeHtml(rawHtml, {
-    allowedTags: ALLOWED_TAGS,
-    allowedAttributes: ALLOWED_ATTR,
-    allowedSchemes: ['http', 'https', 'mailto'],
-    // Transform img src URLs (GitHub blob → raw, relative → GitHub raw)
-    transformTags: {
-      h1: (_, attribs) => {
-        return { tagName: 'h3', attribs: { ...attribs, 'data-level': '1' } }
-      },
-      h2: (_, attribs) => {
-        return { tagName: 'h4', attribs: { ...attribs, 'data-level': '2' } }
-      },
-      h3: (_, attribs) => {
-        if (attribs['data-level']) return { tagName: 'h3', attribs: attribs }
-        return { tagName: 'h5', attribs: { ...attribs, 'data-level': '3' } }
-      },
-      h4: (_, attribs) => {
-        if (attribs['data-level']) return { tagName: 'h4', attribs: attribs }
-        return { tagName: 'h6', attribs: { ...attribs, 'data-level': '4' } }
-      },
-      h5: (_, attribs) => {
-        if (attribs['data-level']) return { tagName: 'h5', attribs: attribs }
-        return { tagName: 'h6', attribs: { ...attribs, 'data-level': '5' } }
-      },
-      h6: (_, attribs) => {
-        if (attribs['data-level']) return { tagName: 'h6', attribs: attribs }
-        return { tagName: 'h6', attribs: { ...attribs, 'data-level': '6' } }
-      },
-      img: (tagName, attribs) => {
-        if (attribs.src) {
-          attribs.src = resolveUrl(attribs.src, mdRepoInfo, idPrefix)
-        }
-        return { tagName, attribs }
-      },
-      source: (tagName, attribs) => {
-        if (attribs.src) {
-          attribs.src = resolveUrl(attribs.src, mdRepoInfo, idPrefix)
-        }
-        if (attribs.srcset) {
-          attribs.srcset = attribs.srcset
-            .split(',')
-            .map(entry => {
-              const parts = entry.trim().split(/\s+/)
-              const url = parts[0]
-              if (!url) return entry.trim()
-              const descriptor = parts[1]
-              const resolvedUrl = resolveUrl(url, mdRepoInfo, idPrefix)
-              return descriptor ? `${resolvedUrl} ${descriptor}` : resolvedUrl
-            })
-            .join(', ')
-        }
-        return { tagName, attribs }
-      },
-      a: (tagName, attribs) => {
-        if (!attribs.href) {
-          return { tagName, attribs }
-        }
-
-        let resolvedHref = resolveUrl(attribs.href, mdRepoInfo, idPrefix)
-
-        if (resolvedHref.startsWith('$')) {
-          resolvedHref = resolvedHref.replace('$', '')
-        }
-
-        // Add security attributes for external links
-        if (resolvedHref && hasProtocol(resolvedHref, { acceptRelative: true })) {
-          attribs.rel = 'nofollow noreferrer noopener'
-          attribs.target = '_blank'
-        } else {
-          attribs.target = ''
-        }
-        attribs.href = resolvedHref
-        return { tagName, attribs }
-      },
-      div: prefixId,
-      p: prefixId,
-      span: prefixId,
-      section: prefixId,
-      article: prefixId,
-    },
-  })
-}
-
-interface MarkdownRepoInfo {
+export interface MarkdownRepoInfo {
   /** Raw file URL base (e.g., https://raw.githubusercontent.com/owner/repo/HEAD) */
   rawBaseUrl: string
   /** Blob/rendered file URL base (e.g., https://github.com/owner/repo/blob/HEAD) */
@@ -236,14 +108,14 @@ interface MarkdownRepoInfo {
   path?: string
 }
 
-function resolveUrl(url: string, repoInfo: MarkdownRepoInfo, idPrefix: string) {
+function resolveUrl(url: string, repoInfo: MarkdownRepoInfo, toUserContentId: ToUserContentIdFn) {
   if (!url || url.startsWith('$')) return url
   if (url.startsWith('#')) {
-    if (url.startsWith('#user-content')) {
+    if (url.startsWith(`#${USER_CONTENT_PREFIX}`)) {
       return url
     }
     // Prefix anchor links to match heading IDs (avoids collision with page IDs)
-    return `#${idPrefix}-${slugify(url.slice(1))}`
+    return `#${toUserContentId(slugify(decodeHashFragment(url.slice(1))))}`
   }
   if (hasProtocol(url, { acceptRelative: true })) {
     try {
@@ -281,13 +153,28 @@ function resolveUrl(url: string, repoInfo: MarkdownRepoInfo, idPrefix: string) {
   return url
 }
 
+function resolveImageUrl(
+  url: string,
+  repoInfo: MarkdownRepoInfo,
+  toUserContentId: ToUserContentIdFn,
+): string {
+  // Skip already-proxied URLs (from a previous resolveImageUrl call in the
+  // marked renderer — sanitizeHtml transformTags may call this again)
+  if (url.startsWith('/api/registry/image-proxy')) {
+    return url
+  }
+  const rawUrl = resolveUrl(url, repoInfo, toUserContentId)
+  const { imageProxySecret } = useRuntimeConfig()
+  return toProxiedImageUrl(rawUrl, imageProxySecret)
+}
+
 /**
  * check resolved url that it still contains the base url
- * @returns the resolved url if starting with baseUrl else baseUrl
+ * @returns the resolved url if starting with baseUrl else baseUrl/filename.ext
  */
 function checkResolvedUrl(resolved: string, baseUrl: string) {
   if (resolved.startsWith(baseUrl)) {
     return resolved
   }
-  return baseUrl
+  return joinRelativeURL(baseUrl, parseFilename(resolved) ?? '')
 }
diff --git a/server/utils/mdKit.ts b/server/utils/mdKit.ts
new file mode 100644
index 0000000000..677d1db531
--- /dev/null
+++ b/server/utils/mdKit.ts
@@ -0,0 +1,543 @@
+import { type Tokens, type RendererApi, type Renderer, type TokenizerObject, marked } from 'marked'
+import { highlightCodeSync } from './shiki'
+import { decodeHtmlEntities, stripHtmlTags, slugify } from '#shared/utils/html'
+import { escapeHtml } from './docs/text'
+import sanitizeHtml from 'sanitize-html'
+import { hasProtocol } from 'ufo'
+
+/// for marked
+
+// constands
+const npmJsHosts = new Set(['www.npmjs.com', 'npmjs.com', 'www.npmjs.org', 'npmjs.org'])
+
+/** These path on npmjs.com don't belong to packages or search, so we shouldn't try to replace them with npmx.dev urls */
+const reservedPathsNpmJs = [
+  'products',
+  'login',
+  'signup',
+  'advisories',
+  'blog',
+  'about',
+  'press',
+  'policies',
+]
+
+// blockquote & code
+
+/**
+ * GitHub-style callouts: > [!NOTE], > [!TIP], etc.
+ */
+export const blockquote: RendererApi['blockquote'] = function (
+  this: Renderer<string, string>,
+  { tokens },
+) {
+  const body = this.parser.parse(tokens)
+
+  const calloutMatch = body.match(/^<p>\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\](?:<br>)?\s*/i)
+
+  if (calloutMatch?.[1]) {
+    const calloutType = calloutMatch[1].toLowerCase()
+    const cleanedBody = body.replace(calloutMatch[0], '<p>')
+    return `<blockquote data-callout="${calloutType}">${cleanedBody}</blockquote>\n`
+  }
+
+  return `<blockquote>${body}</blockquote>\n`
+}
+
+/**
+ * created code highlighter with Shiki for Marked
+ */
+export async function createCodeHighlighter(): Promise<RendererApi['code']> {
+  const shiki = await getShikiHighlighter()
+
+  // Syntax highlighting for code blocks (uses shared highlighter)
+  return ({ text, lang }: Tokens.Code) => {
+    const html = highlightCodeSync(shiki, text, lang || 'text')
+    // Add copy button
+    return `<div class="readme-code-block" >
+  <button type="button" class="readme-copy-button" aria-label="Copy code" check-icon="i-lucide:check" copy-icon="i-lucide:copy" data-copy>
+  <span class="i-lucide:copy" aria-hidden="true"></span>
+  <span class="sr-only">Copy code</span>
+  </button>
+  ${html}
+  </div>`
+  }
+}
+
+// link
+export type ProcessLinkFn = (
+  href: string,
+  label: string,
+  // readme.ts also needs the extraAttrs for more things, so can't be a boolean
+) => { resolvedHref: string; extraAttrs: string }
+
+export function decodeHashFragment(value: string): string {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
+}
+
+const EMAIL_REGEX = /^[\w+\-.]+@[\w\-.]+\.[a-z]+$/i
+
+/**
+ * Resolve link URLs, add security attributes, and collect playground links
+ *
+ * — all in a single pass during marked rendering (no deferred processing)
+ */
+export function createLink(processLink: ProcessLinkFn): RendererApi['link'] {
+  return function (this: Renderer<string, string>, { href, title, tokens }: Tokens.Link) {
+    const eTitle = escapeHtml(title ?? '')
+    const text = this.parser.parseInline(tokens)
+    const titleAttr = eTitle ? ` title="${eTitle}"` : ''
+    let plainText = stripHtmlTags(text).trim()
+
+    // If plain text is empty, check if we have an image with alt text
+    if (!plainText && tokens.length === 1 && tokens[0]?.type === 'image') {
+      plainText = tokens[0].text
+    }
+
+    const { resolvedHref, extraAttrs } = processLink(href, plainText || eTitle || '')
+
+    if (!resolvedHref) return text
+
+    // prevents package@1.0.0 being made into an email
+    if (href.startsWith('mailto:') && !EMAIL_REGEX.test(plainText)) {
+      return text
+    }
+
+    return `<a href="${resolvedHref}"${titleAttr}${extraAttrs}>${text}</a>`
+  }
+}
+
+export const isNpmJsUrlThatCanBeRedirected = (url: URL) => {
+  if (!npmJsHosts.has(url.host)) {
+    return false
+  }
+
+  if (
+    url.pathname === '/' ||
+    reservedPathsNpmJs.some(path => url.pathname.startsWith(`/${path}`))
+  ) {
+    return false
+  }
+
+  return true
+}
+
+// image
+
+export type ProcessImageUrlFn = (href: string) => string
+
+export const createImage = function (processImageUrl: ProcessImageUrlFn): RendererApi['image'] {
+  return function (this: Renderer<string, string>, { href, title, text }) {
+    const resolvedHref = processImageUrl(href)
+    const titleAttr = title ? ` title="${escapeHtml(title)}"` : ''
+    const altAttr = text ? ` alt="${escapeHtml(text)}"` : ''
+    return `<img src="${resolvedHref}"${altAttr}${titleAttr}>`
+  }
+}
+
+// heading
+
+/**
+ * Lazy ATX heading extension for marked: allows headings without a space after `#`.
+ *
+ * Reimplements the behavior of markdown-it-lazy-headers
+ * (https://npmx.dev/package/markdown-it-lazy-headers), which is used by npm's own markdown renderer
+ * marky-markdown (https://npmx.dev/package/marky-markdown).
+ *
+ * CommonMark requires a space after # for ATX headings, but many READMEs in the npm registry omit
+ * this space. This extension allows marked to parse these headings the same way npm does.
+ */
+export const markedHeadingExtension: TokenizerObject['heading'] = function (src: string) {
+  // Only match headings where `#` is immediately followed by non-whitespace, non-`#` content.
+  // Normal headings (with space) return false to fall through to marked's default tokenizer.
+  const match = /^ {0,3}(#{1,6})([^\s#][^\n]*)(?:\n+|$)/.exec(src)
+  if (!match) return false
+
+  let text = match[2]!.trim()
+
+  // Strip trailing # characters only if preceded by a space (CommonMark behavior).
+  // e.g., "#heading ##" → "heading", but "#heading#" stays as "heading#"
+  if (text.endsWith('#')) {
+    const stripped = text.replace(/#+$/, '')
+    if (!stripped || stripped.endsWith(' ')) {
+      text = stripped.trim()
+    }
+  }
+
+  return {
+    type: 'heading' as const,
+    raw: match[0]!,
+    depth: match[1]!.length as number,
+    text,
+    tokens: this.lexer.inline(text),
+  }
+}
+
+export const USER_CONTENT_PREFIX = 'user-content-'
+
+// README h1 always becomes h3
+// For deeper levels, ensure sequential order
+// Don't allow jumping more than 1 level deeper than previous
+export function calculateSemanticDepth(
+  depth: number,
+  lastSemanticLevel: number,
+  minSemanticLevel: number,
+) {
+  if (depth === 1) return minSemanticLevel + 1
+  const maxAllowed = Math.min(lastSemanticLevel + 1, 6)
+  return Math.min(depth + minSemanticLevel, maxAllowed)
+}
+
+export function getHeadingPlainText(text: string): string {
+  return decodeHtmlEntities(stripHtmlTags(text).trim())
+}
+
+export function getHeadingSlugSource(text: string): string {
+  return stripHtmlTags(text).trim()
+}
+
+const htmlAnchorRe = /<a(\s[^>]*?)href=(["'])([^"']*)\2([^>]*)>([\s\S]*?)<\/a>/gi
+
+export type ToUserContentIdFn = (id: string) => string
+
+type ProcessHeadingFn = (
+  depth: number,
+  displayHtml: string,
+  plainText: string,
+  slugSource: string,
+  preservedAttrs?: string,
+) => string
+
+export function createHeading(options: {
+  lastSemanticLevel?: number
+  toUserContentId: ToUserContentIdFn
+}) {
+  let { lastSemanticLevel = 2, toUserContentId } = options
+  const minSemanticLevel = lastSemanticLevel
+  const toc: TocItem[] = []
+  const usedSlugs = new Map<string, number>()
+
+  const heading: RendererApi['heading'] = function (
+    this: Renderer<string, string>,
+    { tokens, depth },
+  ) {
+    const displayHtml = this.parser.parseInline(tokens)
+    const plainText = getHeadingPlainText(displayHtml)
+    const slugSource = getHeadingSlugSource(displayHtml)
+    return processHeading(depth, displayHtml, plainText, slugSource)
+  }
+
+  const processHeading: ProcessHeadingFn = function (
+    depth: number,
+    displayHtml: string,
+    plainText: string,
+    slugSource: string,
+    preservedAttrs = '',
+  ) {
+    const semanticLevel = calculateSemanticDepth(depth, lastSemanticLevel, minSemanticLevel)
+    lastSemanticLevel = semanticLevel
+
+    let slug = slugify(slugSource)
+    if (!slug) slug = 'heading'
+
+    const count = usedSlugs.get(slug) ?? 0
+    usedSlugs.set(slug, count + 1)
+    const uniqueSlug = count === 0 ? slug : `${slug}-${count}`
+    const id = toUserContentId(uniqueSlug)
+
+    if (plainText) {
+      toc.push({ text: plainText, id, depth })
+    }
+
+    // The browser doesn't support anchors within anchors and automatically extracts them from each other,
+    // causing a hydration error. To prevent this from happening in such cases, we use the anchor separately
+    if (displayHtml.match(htmlAnchorRe)?.length) {
+      return `<h${semanticLevel} id="${id}" data-level="${depth}"${preservedAttrs}>${displayHtml}<a href="#${id}" aria-hidden="true" tabindex="-1"></a></h${semanticLevel}>\n`
+    }
+
+    return `<h${semanticLevel} id="${id}" data-level="${depth}"${preservedAttrs}><a href="#${id}">${displayHtml}</a></h${semanticLevel}>\n`
+  }
+
+  return { heading, toc, processHeading }
+}
+
+// html
+
+// Extract and preserve allowed attributes from HTML heading tags
+export function extractHeadingAttrs(attrsString: string): string {
+  if (!attrsString) return ''
+  const preserved: string[] = []
+  const alignMatch = /\balign=(["']?)([^"'\s>]+)\1/i.exec(attrsString)
+  if (alignMatch?.[2]) {
+    preserved.push(`align="${alignMatch[2]}"`)
+  }
+  return preserved.length > 0 ? ` ${preserved.join(' ')}` : ''
+}
+
+// Intercept HTML headings so they get id, TOC entry, and correct semantic level.
+// Also intercept raw HTML <a> tags so playground links are collected in the same pass.
+const htmlHeadingRe = /<h([1-6])(\s[^>]*)?>([\s\S]*?)<\/h\1>/gi
+
+function normalizePreservedAnchorAttrs(attrs: string): string {
+  const cleanedAttrs = attrs
+    .replace(/\s+href\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, '')
+    .replace(/\s+rel\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, '')
+    .replace(/\s+target\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, '')
+    .trim()
+
+  return cleanedAttrs ? ` ${cleanedAttrs}` : ''
+}
+
+export function createHtml({
+  processHeading,
+  processLink,
+}: {
+  processHeading: ProcessHeadingFn
+  processLink: ProcessLinkFn
+}) {
+  // function withUserContentPrefix(value: string): string {
+  // return value.startsWith(USER_CONTENT_PREFIX) ? value : `${USER_CONTENT_PREFIX}${value}`
+  // }
+
+  return function ({ text }: Tokens.HTML) {
+    let result = text.replace(htmlHeadingRe, (_, level, attrs = '', inner) => {
+      const depth = parseInt(level)
+      const plainText = getHeadingPlainText(inner)
+      const slugSource = getHeadingSlugSource(inner)
+      const preservedAttrs = extractHeadingAttrs(attrs)
+      return processHeading(depth, inner, plainText, slugSource, preservedAttrs).trimEnd()
+    })
+    // Process raw HTML <a> tags for playground link collection and URL resolution
+    result = result.replace(htmlAnchorRe, (_full, beforeHref, _quote, href, afterHref, inner) => {
+      const label = decodeHtmlEntities(stripHtmlTags(inner).trim())
+      const { resolvedHref, extraAttrs } = processLink(href, label)
+      const preservedAttrs = normalizePreservedAnchorAttrs(`${beforeHref ?? ''}${afterHref ?? ''}`)
+      return `<a${preservedAttrs} href="${resolvedHref}"${extraAttrs}>${inner}</a>`
+    })
+    return result
+  }
+}
+
+// html rendering
+
+export function renderToRawHtml({
+  renderer,
+  markdownBody,
+  frontmatterHtml = '',
+}: {
+  renderer: Renderer
+  markdownBody: string
+  frontmatterHtml?: string
+  lastSemanticLevel?: number
+}) {
+  // Strip trailing whitespace (tabs/spaces) from code block closing fences.
+  // While marky-markdown handles these gracefully, marked fails to recognize
+  // the end of a code block if the closing fences are followed by unexpected whitespaces.
+  const normalizedContent = markdownBody.replace(/^( {0,3}(?:`{3,}|~{3,}))\s*$/gm, '$1')
+  return (
+    frontmatterHtml +
+    (marked.parse(normalizedContent, {
+      renderer,
+    }) as string)
+  )
+}
+
+/// sanatizer
+
+export const ALLOWED_ATTR: Record<string, string[]> = {
+  '*': ['id'], // Allow id on all tags
+  'a': ['href', 'title', 'target', 'rel', 'tabindex', 'aria-hidden'],
+  'img': ['src', 'alt', 'title', 'width', 'height', 'align'],
+  'source': ['src', 'srcset', 'type', 'media'],
+  'button': ['class', 'title', 'type', 'aria-label', 'data-copy'],
+  'th': ['colspan', 'rowspan', 'align', 'valign', 'width'],
+  'td': ['colspan', 'rowspan', 'align', 'valign', 'width'],
+  'h2': ['data-level', 'align'],
+  'h3': ['data-level', 'align'],
+  'h4': ['data-level', 'align'],
+  'h5': ['data-level', 'align'],
+  'h6': ['data-level', 'align'],
+  'blockquote': ['data-callout'],
+  'details': ['open'],
+  'code': ['class'],
+  'pre': ['class'],
+  'span': ['class', 'style'],
+  'div': ['class', 'align'],
+  'p': ['align'],
+}
+
+// allow h1-h6, but replace h1-h2 later since we shift README headings down by 2 levels
+// (page h1 = package name, h2 = "Readme" section, so README h1 → h3)
+export const ALLOWED_TAGS = [
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'p',
+  'br',
+  'hr',
+  'ul',
+  'ol',
+  'li',
+  'blockquote',
+  'pre',
+  'code',
+  'a',
+  'strong',
+  'em',
+  'del',
+  's',
+  'table',
+  'thead',
+  'tbody',
+  'tr',
+  'th',
+  'td',
+  'img',
+  'picture',
+  'source',
+  'details',
+  'summary',
+  'div',
+  'span',
+  'sup',
+  'sub',
+  'kbd',
+  'mark',
+  'button',
+]
+
+export function sanitizeRawHTML(
+  rawHtml: string,
+  {
+    processImageUrl,
+    processLink,
+    toUserContentId,
+    lastSemanticLevel = 2,
+  }: {
+    processImageUrl: ProcessImageUrlFn
+    processLink: ProcessLinkFn
+    toUserContentId: ToUserContentIdFn
+    lastSemanticLevel?: number
+  },
+) {
+  // Helper to prefix id attributes with 'user-content-'
+  function prefixId(tagName: string, attribs: sanitizeHtml.Attributes) {
+    if (attribs.id) {
+      attribs.id = attribs.id.startsWith(USER_CONTENT_PREFIX)
+        ? attribs.id
+        : toUserContentId(attribs.id)
+    }
+    return { tagName, attribs }
+  }
+
+  const h1 = `h${lastSemanticLevel + 1}`,
+    h2 = `h${lastSemanticLevel + 2}`,
+    h3 = `h${lastSemanticLevel + 3}`,
+    h4 = `h${lastSemanticLevel + 4}`
+
+  return sanitizeHtml(rawHtml, {
+    allowedTags: ALLOWED_TAGS,
+    allowedAttributes: ALLOWED_ATTR,
+    allowedSchemes: ['http', 'https', 'mailto'],
+    // disallow styles other than the ones shiki emits
+    allowedStyles: {
+      span: {
+        'color': [/^#[0-9a-f]{3,8}$/i],
+        '--shiki-light': [/^#[0-9a-f]{3,8}$/i],
+      },
+    },
+    transformTags: {
+      // Headings are already processed to correct semantic levels by processHeading()
+      // during the marked rendering pass. The sanitizer just needs to preserve them.
+      // For any stray headings that didn't go through processHeading (shouldn't happen),
+      // we still apply a safe fallback shift.
+      h1: (_, attribs) => {
+        if (attribs['data-level']) return { tagName: 'h1', attribs }
+        return { tagName: h1, attribs: { ...attribs, 'data-level': '1' } }
+      },
+      h2: (_, attribs) => {
+        if (attribs['data-level']) return { tagName: 'h2', attribs }
+        return { tagName: h2, attribs: { ...attribs, 'data-level': '2' } }
+      },
+      h3: (_, attribs) => {
+        if (attribs['data-level']) return { tagName: 'h3', attribs }
+        return { tagName: h3, attribs: { ...attribs, 'data-level': '3' } }
+      },
+      h4: (_, attribs) => {
+        if (attribs['data-level']) return { tagName: 'h4', attribs }
+        return { tagName: h4, attribs: { ...attribs, 'data-level': '4' } }
+      },
+      h5: (_, attribs) => {
+        if (attribs['data-level']) return { tagName: 'h5', attribs }
+        return { tagName: 'h6', attribs: { ...attribs, 'data-level': '5' } }
+      },
+      h6: (_, attribs) => {
+        if (attribs['data-level']) return { tagName: 'h6', attribs }
+        return { tagName: 'h6', attribs: { ...attribs, 'data-level': '6' } }
+      },
+      img: (tagName, attribs) => {
+        if (attribs.src) {
+          attribs.src = processImageUrl(attribs.src)
+        }
+        return { tagName, attribs }
+      },
+      source: (tagName, attribs) => {
+        if (attribs.src) {
+          attribs.src = processImageUrl(attribs.src)
+        }
+        if (attribs.srcset) {
+          attribs.srcset = attribs.srcset
+            .split(',')
+            .map(entry => {
+              const parts = entry.trim().split(/\s+/)
+              const url = parts[0]
+              if (!url) return entry.trim()
+              const descriptor = parts[1]
+              const resolvedUrl = processImageUrl(url)
+              return descriptor ? `${resolvedUrl} ${descriptor}` : resolvedUrl
+            })
+            .join(', ')
+        }
+        return { tagName, attribs }
+      },
+      // Markdown links are fully processed in renderer.link (single-pass).
+      // However, inline HTML <a> tags inside paragraphs are NOT seen by
+      // renderer.html (marked parses them as paragraph tokens, not html tokens).
+      // So we still need to collect playground links here for those cases via processUrl from readme.
+      // The seenUrls set ensures no duplicates across both paths.
+      a: (tagName, attribs) => {
+        if (!attribs.href) {
+          return { tagName, attribs }
+        }
+
+        let { resolvedHref } = processLink(attribs.href, '')
+
+        // for changelog all routes are orianted around the git provider, prefixing with $ set it to npmx
+        if (resolvedHref.startsWith('$')) {
+          resolvedHref = resolvedHref.replace('$', '')
+        }
+
+        // Add security attributes for external links (idempotent)
+        if (resolvedHref && hasProtocol(resolvedHref, { acceptRelative: true })) {
+          attribs.rel = 'nofollow noreferrer noopener'
+          attribs.target = '_blank'
+        }
+        attribs.href = resolvedHref
+        return { tagName, attribs }
+      },
+
+      div: prefixId,
+      p: prefixId,
+      span: prefixId,
+      section: prefixId,
+      article: prefixId,
+    },
+  })
+}
diff --git a/server/utils/readme.ts b/server/utils/readme.ts
index f49e83465a..8edc88ff55 100644
--- a/server/utils/readme.ts
+++ b/server/utils/readme.ts
@@ -1,14 +1,26 @@
-import type { ReadmeResponse, TocItem } from '#shared/types/readme'
-import type { Tokens } from 'marked'
+import type { ReadmeResponse } from '#shared/types/readme'
+import {
+  type ProcessLinkFn,
+  blockquote,
+  createCodeHighlighter,
+  isNpmJsUrlThatCanBeRedirected,
+  createLink,
+  createHeading,
+  createHtml,
+  USER_CONTENT_PREFIX,
+  markedHeadingExtension,
+  renderToRawHtml,
+  createImage,
+  sanitizeRawHTML,
+  decodeHashFragment,
+} from './mdKit'
 import matter from 'gray-matter'
 import { marked } from 'marked'
-import sanitizeHtml from 'sanitize-html'
 import { hasProtocol } from 'ufo'
 import { convertBlobOrFileToRawUrl, type RepositoryInfo } from '#shared/utils/git-providers'
-import { decodeHtmlEntities, stripHtmlTags, slugify } from '#shared/utils/html'
+import { decodeHtmlEntities, slugify } from '#shared/utils/html'
 import { convertToEmoji } from '#shared/utils/emoji'
 import { toProxiedImageUrl } from '#server/utils/image-proxy'
-import { highlightCodeSync } from './shiki'
 import { escapeHtml } from './docs/text'
 
 /**
@@ -139,134 +151,12 @@ function matchPlaygroundProvider(url: string): PlaygroundProvider | null {
   return null
 }
 
-// allow h1-h6, but replace h1-h2 later since we shift README headings down by 2 levels
-// (page h1 = package name, h2 = "Readme" section, so README h1 → h3)
-export const ALLOWED_TAGS = [
-  'h1',
-  'h2',
-  'h3',
-  'h4',
-  'h5',
-  'h6',
-  'p',
-  'br',
-  'hr',
-  'ul',
-  'ol',
-  'li',
-  'blockquote',
-  'pre',
-  'code',
-  'a',
-  'strong',
-  'em',
-  'del',
-  's',
-  'table',
-  'thead',
-  'tbody',
-  'tr',
-  'th',
-  'td',
-  'img',
-  'picture',
-  'source',
-  'details',
-  'summary',
-  'div',
-  'span',
-  'sup',
-  'sub',
-  'kbd',
-  'mark',
-  'button',
-]
-
-export const ALLOWED_ATTR: Record<string, string[]> = {
-  '*': ['id'], // Allow id on all tags
-  'a': ['href', 'title', 'target', 'rel'],
-  'img': ['src', 'alt', 'title', 'width', 'height', 'align'],
-  'source': ['src', 'srcset', 'type', 'media'],
-  'button': ['class', 'title', 'type', 'aria-label', 'data-copy'],
-  'th': ['colspan', 'rowspan', 'align', 'valign', 'width'],
-  'td': ['colspan', 'rowspan', 'align', 'valign', 'width'],
-  'h3': ['data-level', 'align'],
-  'h4': ['data-level', 'align'],
-  'h5': ['data-level', 'align'],
-  'h6': ['data-level', 'align'],
-  'blockquote': ['data-callout'],
-  'details': ['open'],
-  'code': ['class'],
-  'pre': ['class'],
-  'span': ['class', 'style'],
-  'div': ['class', 'align'],
-  'p': ['align'],
-}
-
-function getHeadingPlainText(text: string): string {
-  return decodeHtmlEntities(stripHtmlTags(text).trim())
-}
-
-function getHeadingSlugSource(text: string): string {
-  return stripHtmlTags(text).trim()
-}
-
-/**
- * Lazy ATX heading extension for marked: allows headings without a space after `#`.
- *
- * Reimplements the behavior of markdown-it-lazy-headers
- * (https://npmx.dev/package/markdown-it-lazy-headers), which is used by npm's own markdown renderer
- * marky-markdown (https://npmx.dev/package/marky-markdown).
- *
- * CommonMark requires a space after # for ATX headings, but many READMEs in the npm registry omit
- * this space. This extension allows marked to parse these headings the same way npm does.
- */
 marked.use({
   tokenizer: {
-    heading(src: string) {
-      // Only match headings where `#` is immediately followed by non-whitespace, non-`#` content.
-      // Normal headings (with space) return false to fall through to marked's default tokenizer.
-      const match = /^ {0,3}(#{1,6})([^\s#][^\n]*)(?:\n+|$)/.exec(src)
-      if (!match) return false
-
-      let text = match[2]!.trim()
-
-      // Strip trailing # characters only if preceded by a space (CommonMark behavior).
-      // e.g., "#heading ##" → "heading", but "#heading#" stays as "heading#"
-      if (text.endsWith('#')) {
-        const stripped = text.replace(/#+$/, '')
-        if (!stripped || stripped.endsWith(' ')) {
-          text = stripped.trim()
-        }
-      }
-
-      return {
-        type: 'heading' as const,
-        raw: match[0]!,
-        depth: match[1]!.length as number,
-        text,
-        tokens: this.lexer.inline(text),
-      }
-    },
+    heading: markedHeadingExtension,
   },
 })
 
-/** These path on npmjs.com don't belong to packages or search, so we shouldn't try to replace them with npmx.dev urls */
-const reservedPathsNpmJs = [
-  'products',
-  'login',
-  'signup',
-  'advisories',
-  'blog',
-  'about',
-  'press',
-  'policies',
-]
-
-const npmJsHosts = new Set(['www.npmjs.com', 'npmjs.com', 'www.npmjs.org', 'npmjs.org'])
-
-const USER_CONTENT_PREFIX = 'user-content-'
-
 function withUserContentPrefix(value: string): string {
   return value.startsWith(USER_CONTENT_PREFIX) ? value : `${USER_CONTENT_PREFIX}${value}`
 }
@@ -279,39 +169,6 @@ function toUserContentHash(value: string): string {
   return `#${withUserContentPrefix(value)}`
 }
 
-function decodeHashFragment(value: string): string {
-  try {
-    return decodeURIComponent(value)
-  } catch {
-    return value
-  }
-}
-
-function normalizePreservedAnchorAttrs(attrs: string): string {
-  const cleanedAttrs = attrs
-    .replace(/\s+href\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, '')
-    .replace(/\s+rel\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, '')
-    .replace(/\s+target\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, '')
-    .trim()
-
-  return cleanedAttrs ? ` ${cleanedAttrs}` : ''
-}
-
-export const isNpmJsUrlThatCanBeRedirected = (url: URL) => {
-  if (!npmJsHosts.has(url.host)) {
-    return false
-  }
-
-  if (
-    url.pathname === '/' ||
-    reservedPathsNpmJs.some(path => url.pathname.startsWith(`/${path}`))
-  ) {
-    return false
-  }
-
-  return true
-}
-
 /**
  * Resolve a relative URL to an absolute URL.
  * If repository info is available, resolve to provider's raw file URLs.
@@ -423,24 +280,6 @@ function resolveImageUrl(url: string, packageName: string, repoInfo?: Repository
   return toProxiedImageUrl(rawUrl, imageProxySecret)
 }
 
-// Helper to prefix id attributes with 'user-content-'
-
-export function prefixId(tagName: string, attribs: sanitizeHtml.Attributes) {
-  if (attribs.id) {
-    attribs.id = withUserContentPrefix(attribs.id)
-  }
-  return { tagName, attribs }
-}
-
-// README h1 always becomes h3
-// For deeper levels, ensure sequential order
-// Don't allow jumping more than 1 level deeper than previous
-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)
-}
-
 /**
  * Render YAML frontmatter as a GitHub-style key-value table.
  */
@@ -458,17 +297,6 @@ function renderFrontmatterTable(data: Record<string, unknown>): string {
   return `<table><thead><tr><th>Key</th><th>Value</th></tr></thead><tbody>\n${rows}\n</tbody></table>\n`
 }
 
-// Extract and preserve allowed attributes from HTML heading tags
-function extractHeadingAttrs(attrsString: string): string {
-  if (!attrsString) return ''
-  const preserved: string[] = []
-  const alignMatch = /\balign=(["']?)([^"'\s>]+)\1/i.exec(attrsString)
-  if (alignMatch?.[2]) {
-    preserved.push(`align="${alignMatch[2]}"`)
-  }
-  return preserved.length > 0 ? ` ${preserved.join(' ')}` : ''
-}
-
 export async function renderReadmeHtml(
   content: string,
   packageName: string,
@@ -489,117 +317,29 @@ export async function renderReadmeHtml(
     // If frontmatter parsing fails, render the full content as-is
   }
 
-  const shiki = await getShikiHighlighter()
   const renderer = new marked.Renderer()
 
   // Collect playground links during parsing
   const collectedLinks: PlaygroundLink[] = []
   const seenUrls = new Set<string>()
 
-  // Collect table of contents items during parsing
-  const toc: TocItem[] = []
-
-  // 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
-  // Visual styling preserved via data-level attribute (original depth)
-  let lastSemanticLevel = 2 // Start after h2 (the "Readme" section heading)
-
-  // Shared heading processing for both markdown and HTML headings
-  function processHeading(
-    depth: number,
-    displayHtml: string,
-    plainText: string,
-    slugSource: string,
-    preservedAttrs = '',
-  ) {
-    const semanticLevel = calculateSemanticDepth(depth, lastSemanticLevel)
-    lastSemanticLevel = semanticLevel
-
-    let slug = slugify(slugSource)
-    if (!slug) slug = 'heading'
-
-    const count = usedSlugs.get(slug) ?? 0
-    usedSlugs.set(slug, count + 1)
-    const uniqueSlug = count === 0 ? slug : `${slug}-${count}`
-    const id = toUserContentId(uniqueSlug)
-
-    if (plainText) {
-      toc.push({ text: plainText, id, depth })
-    }
-
-    // The browser doesn't support anchors within anchors and automatically extracts them from each other,
-    // causing a hydration error. To prevent this from happening in such cases, we use the anchor separately
-    if (htmlAnchorRe.test(displayHtml)) {
-      return `<h${semanticLevel} id="${id}" data-level="${depth}"${preservedAttrs}>${displayHtml}<a href="#${id}"></a></h${semanticLevel}>\n`
-    }
-
-    return `<h${semanticLevel} id="${id}" data-level="${depth}"${preservedAttrs}><a href="#${id}">${displayHtml}</a></h${semanticLevel}>\n`
-  }
+  const { toc, heading, processHeading } = createHeading({ toUserContentId })
 
-  const anchorTokenRegex = /^<a(?:\s.+)?\/?>$/
-  renderer.heading = function ({ tokens, depth }: Tokens.Heading) {
-    const isAnchorHeading =
-      anchorTokenRegex.test(tokens[0]?.raw ?? '') && tokens[tokens.length - 1]?.raw === '</a>'
-
-    // for anchor headings, we will ignore user-added id and add our own
-    const tokensWithoutAnchor = isAnchorHeading ? tokens.slice(1, -1) : tokens
-    const displayHtml = this.parser.parseInline(tokensWithoutAnchor)
-    const plainText = getHeadingPlainText(displayHtml)
-    const slugSource = getHeadingSlugSource(displayHtml)
-    return processHeading(depth, displayHtml, plainText, slugSource)
-  }
-
-  // Intercept HTML headings so they get id, TOC entry, and correct semantic level.
-  // Also intercept raw HTML <a> tags so playground links are collected in the same pass.
-  const htmlHeadingRe = /<h([1-6])(\s[^>]*)?>([\s\S]*?)<\/h\1>/gi
-  const htmlAnchorRe = /<a(\s[^>]*?)href=(["'])([^"']*)\2([^>]*)>([\s\S]*?)<\/a>/gi
-  renderer.html = function ({ text }: Tokens.HTML) {
-    let result = text.replace(htmlHeadingRe, (_, level, attrs = '', inner) => {
-      const depth = parseInt(level)
-      const plainText = getHeadingPlainText(inner)
-      const slugSource = getHeadingSlugSource(inner)
-      const preservedAttrs = extractHeadingAttrs(attrs)
-      return processHeading(depth, inner, plainText, slugSource, preservedAttrs).trimEnd()
-    })
-    // Process raw HTML <a> tags for playground link collection and URL resolution
-    result = result.replace(htmlAnchorRe, (_full, beforeHref, _quote, href, afterHref, inner) => {
-      const label = decodeHtmlEntities(stripHtmlTags(inner).trim())
-      const { resolvedHref, extraAttrs } = processLink(href, label)
-      const preservedAttrs = normalizePreservedAnchorAttrs(`${beforeHref ?? ''}${afterHref ?? ''}`)
-      return `<a${preservedAttrs} href="${resolvedHref}"${extraAttrs}>${inner}</a>`
-    })
-    return result
-  }
+  renderer.heading = heading
 
   // Syntax highlighting for code blocks (uses shared highlighter)
-  renderer.code = ({ text, lang }: Tokens.Code) => {
-    const html = highlightCodeSync(shiki, text, lang || 'text')
-    // Add copy button
-    return `<div class="readme-code-block" >
-<button type="button" class="readme-copy-button" aria-label="Copy code" check-icon="i-lucide:check" copy-icon="i-lucide:copy" data-copy>
-<span class="i-lucide:copy" aria-hidden="true"></span>
-<span class="sr-only">Copy code</span>
-</button>
-${html}
-</div>`
-  }
+  renderer.code = await createCodeHighlighter()
 
-  // Resolve image URLs (with GitHub blob → raw conversion)
-  renderer.image = ({ href, title, text }: Tokens.Image) => {
-    const resolvedHref = resolveImageUrl(href, packageName, repoInfo)
-    const titleAttr = title ? ` title="${escapeHtml(title)}"` : ''
-    const altAttr = text ? ` alt="${escapeHtml(text)}"` : ''
-    return `<img src="${resolvedHref}"${altAttr}${titleAttr}>`
+  function processImageUrl(href: string) {
+    return resolveImageUrl(href, packageName, repoInfo)
   }
 
+  renderer.image = createImage(processImageUrl)
+
   // Helper: resolve a link href, collect playground links, and build <a> attributes.
   // Used by both the markdown renderer.link and the HTML <a> interceptor so that
   // all link processing happens in a single pass during marked rendering.
-  function processLink(href: string, label: string): { resolvedHref: string; extraAttrs: string } {
+  const processLink: ProcessLinkFn = (href: string, label: string) => {
     const resolvedHref = resolveUrl(href, packageName, repoInfo)
 
     // Collect playground links
@@ -615,7 +355,7 @@ ${html}
     }
 
     // Security attributes for external links
-    let extraAttrs =
+    const extraAttrs =
       resolvedHref && hasProtocol(resolvedHref, { acceptRelative: true })
         ? ' rel="nofollow noreferrer noopener" target="_blank"'
         : ''
@@ -623,155 +363,18 @@ ${html}
     return { resolvedHref, extraAttrs }
   }
 
-  // Resolve link URLs, add security attributes, and collect playground links
-  // — all in a single pass during marked rendering (no deferred processing)
-  renderer.link = function ({ href, title, tokens }: Tokens.Link) {
-    const text = this.parser.parseInline(tokens)
-    const titleAttr = title ? ` title="${title}"` : ''
-    let plainText = stripHtmlTags(text).trim()
-
-    // If plain text is empty, check if we have an image with alt text
-    if (!plainText && tokens.length === 1 && tokens[0]?.type === 'image') {
-      plainText = tokens[0].text
-    }
-
-    const { resolvedHref, extraAttrs } = processLink(href, plainText || title || '')
-
-    if (!resolvedHref) return text
-
-    return `<a href="${resolvedHref}"${titleAttr}${extraAttrs}>${text}</a>`
-  }
+  renderer.link = createLink(processLink)
+  renderer.html = createHtml({ processHeading, processLink })
 
   // GitHub-style callouts: > [!NOTE], > [!TIP], etc.
-  renderer.blockquote = function ({ tokens }: Tokens.Blockquote) {
-    const body = this.parser.parse(tokens)
+  renderer.blockquote = blockquote
 
-    const calloutMatch = body.match(/^<p>\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\](?:<br>)?\s*/i)
-
-    if (calloutMatch?.[1]) {
-      const calloutType = calloutMatch[1].toLowerCase()
-      const cleanedBody = body.replace(calloutMatch[0], '<p>')
-      return `<blockquote data-callout="${calloutType}">${cleanedBody}</blockquote>\n`
-    }
-
-    return `<blockquote>${body}</blockquote>\n`
-  }
+  const rawHtml = renderToRawHtml({ renderer, markdownBody, frontmatterHtml })
 
-  marked.setOptions({ renderer })
-
-  // Strip trailing whitespace (tabs/spaces) from code block closing fences.
-  // While marky-markdown handles these gracefully, marked fails to recognize
-  // the end of a code block if the closing fences are followed by unexpected whitespaces.
-  const normalizedContent = markdownBody.replace(/^( {0,3}(?:`{3,}|~{3,}))\s*$/gm, '$1')
-  const rawHtml = frontmatterHtml + (marked.parse(normalizedContent) as string)
-
-  const sanitized = sanitizeHtml(rawHtml, {
-    allowedTags: ALLOWED_TAGS,
-    allowedAttributes: ALLOWED_ATTR,
-    allowedSchemes: ['http', 'https', 'mailto'],
-    // disallow styles other than the ones shiki emits
-    allowedStyles: {
-      span: {
-        'color': [/^#[0-9a-f]{3,8}$/i],
-        '--shiki-light': [/^#[0-9a-f]{3,8}$/i],
-      },
-    },
-    // Transform img src URLs (GitHub blob → raw, relative → GitHub raw)
-    transformTags: {
-      // Headings are already processed to correct semantic levels by processHeading()
-      // during the marked rendering pass. The sanitizer just needs to preserve them.
-      // For any stray headings that didn't go through processHeading (shouldn't happen),
-      // we still apply a safe fallback shift.
-      h1: (_, attribs) => {
-        if (attribs['data-level']) return { tagName: 'h1', attribs }
-        return { tagName: 'h3', attribs: { ...attribs, 'data-level': '1' } }
-      },
-      h2: (_, attribs) => {
-        if (attribs['data-level']) return { tagName: 'h2', attribs }
-        return { tagName: 'h4', attribs: { ...attribs, 'data-level': '2' } }
-      },
-      h3: (_, attribs) => {
-        if (attribs['data-level']) return { tagName: 'h3', attribs }
-        return { tagName: 'h5', attribs: { ...attribs, 'data-level': '3' } }
-      },
-      h4: (_, attribs) => {
-        if (attribs['data-level']) return { tagName: 'h4', attribs }
-        return { tagName: 'h6', attribs: { ...attribs, 'data-level': '4' } }
-      },
-      h5: (_, attribs) => {
-        if (attribs['data-level']) return { tagName: 'h5', attribs }
-        return { tagName: 'h6', attribs: { ...attribs, 'data-level': '5' } }
-      },
-      h6: (_, attribs) => {
-        if (attribs['data-level']) return { tagName: 'h6', attribs }
-        return { tagName: 'h6', attribs: { ...attribs, 'data-level': '6' } }
-      },
-      img: (tagName, attribs) => {
-        if (attribs.src) {
-          attribs.src = resolveImageUrl(attribs.src, packageName, repoInfo)
-        }
-        return { tagName, attribs }
-      },
-      source: (tagName, attribs) => {
-        if (attribs.src) {
-          attribs.src = resolveImageUrl(attribs.src, packageName, repoInfo)
-        }
-        if (attribs.srcset) {
-          attribs.srcset = attribs.srcset
-            .split(',')
-            .map(entry => {
-              const parts = entry.trim().split(/\s+/)
-              const url = parts[0]
-              if (!url) return entry.trim()
-              const descriptor = parts[1]
-              const resolvedUrl = resolveImageUrl(url, packageName, repoInfo)
-              return descriptor ? `${resolvedUrl} ${descriptor}` : resolvedUrl
-            })
-            .join(', ')
-        }
-        return { tagName, attribs }
-      },
-      // Markdown links are fully processed in renderer.link (single-pass).
-      // However, inline HTML <a> tags inside paragraphs are NOT seen by
-      // renderer.html (marked parses them as paragraph tokens, not html tokens).
-      // So we still need to collect playground links here for those cases.
-      // The seenUrls set ensures no duplicates across both paths.
-      a: (tagName, attribs) => {
-        if (!attribs.href) {
-          return { tagName, attribs }
-        }
-
-        const resolvedHref = resolveUrl(attribs.href, packageName, repoInfo)
-
-        // Collect playground links from inline HTML <a> tags that weren't
-        // caught by renderer.link or renderer.html
-        const provider = matchPlaygroundProvider(resolvedHref)
-        if (provider && !seenUrls.has(resolvedHref)) {
-          seenUrls.add(resolvedHref)
-          collectedLinks.push({
-            url: resolvedHref,
-            provider: provider.id,
-            providerName: provider.name,
-            // sanitize-html transformTags doesn't provide element text content,
-            // so we fall back to the provider name for the label
-            label: provider.name,
-          })
-        }
-
-        // Add security attributes for external links (idempotent)
-        if (resolvedHref && hasProtocol(resolvedHref, { acceptRelative: true })) {
-          attribs.rel = 'nofollow noreferrer noopener'
-          attribs.target = '_blank'
-        }
-        attribs.href = resolvedHref
-        return { tagName, attribs }
-      },
-      div: prefixId,
-      p: prefixId,
-      span: prefixId,
-      section: prefixId,
-      article: prefixId,
-    },
+  const sanitized = sanitizeRawHTML(rawHtml, {
+    processImageUrl,
+    processLink,
+    toUserContentId,
   })
 
   return {
diff --git a/shared/types/changelog.ts b/shared/types/changelog.ts
index 3ec410d08d..d3e5f5858b 100644
--- a/shared/types/changelog.ts
+++ b/shared/types/changelog.ts
@@ -32,4 +32,5 @@ export interface ReleaseData {
   id: string | number
   publishedAt?: string
   toc?: TocItem[]
+  link: string
 }
diff --git a/test/nuxt/a11y.spec.ts b/test/nuxt/a11y.spec.ts
index 5d0865d77f..ddcd18553d 100644
--- a/test/nuxt/a11y.spec.ts
+++ b/test/nuxt/a11y.spec.ts
@@ -162,6 +162,7 @@ import {
   LinkBase,
   CallToAction,
   ChangelogCard,
+  ChangelogSkeleton,
   ChangelogErrorMsg,
   CodeDirectoryListing,
   CodeFileTree,
@@ -2646,6 +2647,7 @@ describe('component accessibility audits', () => {
             id: 'a11y',
             title: '1.0.0',
             publishedAt: '2026-02-11 10:00:00.000Z',
+            link: 'https://github.com/nuxt/nuxt/releases/tag/v4.4.5',
           },
           tocHeaderClass: 'toc',
         },
@@ -2654,6 +2656,12 @@ describe('component accessibility audits', () => {
       expect(results.violations).toEqual([])
     })
 
+    it('ChangelogSkeleton', async () => {
+      const component = await mountSuspended(ChangelogSkeleton)
+      const results = await runAxe(component)
+      expect(results.violations).toEqual([])
+    })
+
     it('ChangelogErrorMsg should have no accessibility violations for warning variant', async () => {
       const component = await mountSuspended(ChangelogErrorMsg, {
         props: {
diff --git a/test/nuxt/app/utils/header-version-matcher.spec.ts b/test/nuxt/app/utils/header-version-matcher.spec.ts
new file mode 100644
index 0000000000..8bf28c78d5
--- /dev/null
+++ b/test/nuxt/app/utils/header-version-matcher.spec.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { createHeadingVersionMatcher } from '~/utils/header-version-matcher'
+
+describe('createHeadingVersionMatcher', () => {
+  it('should only match version 3.5.1', () => {
+    const isMatching = createHeadingVersionMatcher('3.5.1')
+
+    expect(isMatching('test-pkg@3.5.1')).toBe(true)
+    expect(isMatching('test-pkg: 3.5.1')).toBe(true)
+    expect(isMatching('v3.5.1 (2026-03-03)')).toBe(true)
+    expect(isMatching('3.5.1')).toBe(true)
+    expect(isMatching('3.5.1/3.5.2')).toBe(true)
+    expect(isMatching('v3.5.0/v3.5.1')).toBe(true)
+
+    expect(isMatching('test-pkg@3.5.15')).toBe(false)
+    expect(isMatching('test-pkg: 3.5.15')).toBe(false)
+    expect(isMatching('v3.5.15 (2026-03-03)')).toBe(false)
+    expect(isMatching('3.5.15')).toBe(false)
+    expect(isMatching('3.5.12/3.5.20')).toBe(false)
+    expect(isMatching('3.5.9/3.5.10')).toBe(false)
+  })
+})
diff --git a/test/unit/a11y-component-coverage.spec.ts b/test/unit/a11y-component-coverage.spec.ts
index 1f5570aaa3..cd33053a45 100644
--- a/test/unit/a11y-component-coverage.spec.ts
+++ b/test/unit/a11y-component-coverage.spec.ts
@@ -55,8 +55,8 @@ const SKIPPED_COMPONENTS: Record<string, string> = {
   'SkeletonBlock.vue': 'Already covered indirectly via other component tests',
   'SkeletonInline.vue': 'Already covered indirectly via other component tests',
   'Button/Group.vue': "Wrapper component, tests wouldn't make much sense here",
-  'Changelog/Releases.vue': 'Requires API calls',
-  'Changelog/Markdown.vue': 'Requires API call & only renders markdown html',
+  'Changelog/Releases.vue': 'Requires API calls & only renders ChangelogCard components in a list',
+  'Changelog/Markdown.vue': 'Requires API call & mostly renders markdown html',
   'Translation/StatusByFile.unused.vue': 'Unused component, might be needed in the future',
   'ColorScheme/Img.vue': 'Image component, basic ui',
 }
diff --git a/test/unit/server/utils/changelog/markdown.spec.ts b/test/unit/server/utils/changelog/markdown.spec.ts
new file mode 100644
index 0000000000..78780e1465
--- /dev/null
+++ b/test/unit/server/utils/changelog/markdown.spec.ts
@@ -0,0 +1,519 @@
+import type { MarkdownRepoInfo } from '~~/server/utils/changelog/markdown'
+import { describe, expect, it, vi, beforeAll } from 'vitest'
+
+// testing changelog specific needs, others things are tested at ../readme.spec.ts
+
+beforeAll(() => {
+  vi.stubGlobal(
+    'getShikiHighlighter',
+    vi.fn().mockResolvedValue({
+      getLoadedLanguages: () => [],
+      codeToHtml: (code: string) => `<pre><code>${code}</code></pre>`,
+    }),
+  )
+  vi.stubGlobal(
+    'useRuntimeConfig',
+    vi.fn().mockReturnValue({
+      imageProxySecret: 'test-secret-for-readme-tests',
+    }),
+  )
+})
+
+const { changelogRenderer } = await import('#server/utils/changelog/markdown')
+
+function changelogMdinfo(): MarkdownRepoInfo {
+  return {
+    blobBaseUrl: `https://github.com/test-owner/test-repo/blob/HEAD`,
+    rawBaseUrl: `https://raw.githubusercontent.com/test-owner/test-repo/HEAD`,
+  }
+}
+
+function changelogMdInfoWithPath() {
+  return {
+    blobBaseUrl: `https://github.com/test-owner/test-repo/blob/HEAD`,
+    rawBaseUrl: `https://raw.githubusercontent.com/test-owner/test-repo/HEAD`,
+    path: 'packages/test/changelog.md',
+  }
+}
+
+describe('URL Resolution', () => {
+  describe('resolves from /markdown.md & releases', () => {
+    it('resolves relative .md links to blob URL for rendered viewing', async () => {
+      const info = changelogMdinfo()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[Contributing](./CONTRIBUTING.md)`
+      const result = renderer(markdown)
+
+      expect(result.html).toContain(
+        `href="https://github.com/test-owner/test-repo/blob/HEAD/CONTRIBUTING.md"`,
+      )
+    })
+
+    it('resolves without ./ or / .md links to blob URL', async () => {
+      const info = changelogMdinfo()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[Guide](GUIDE.MD)`
+      const result = renderer(markdown)
+      expect(result.html).toContain(
+        'href="https://github.com/test-owner/test-repo/blob/HEAD/GUIDE.MD"',
+      )
+    })
+
+    it('resolves absolute .md links to blob URL', async () => {
+      const info = changelogMdinfo()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[Security](/SECURITY.MD)`
+
+      const result = renderer(markdown)
+      expect(result.html).toContain(
+        'href="https://github.com/test-owner/test-repo/blob/HEAD/SECURITY.MD"',
+      )
+    })
+
+    it('resolves nested relative .md links to blob URL', async () => {
+      const info = changelogMdinfo()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[API Docs](./docs/api/reference.md)`
+      const result = renderer(markdown)
+
+      expect(result.html).toContain(
+        'href="https://github.com/test-owner/test-repo/blob/HEAD/docs/api/reference.md"',
+      )
+    })
+
+    it('resolves relative .md links with query strings to blob URL', async () => {
+      const info = changelogMdinfo()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[FAQ](./FAQ.md?ref=main)`
+      const result = renderer(markdown)
+
+      expect(result.html).toContain(
+        'href="https://github.com/test-owner/test-repo/blob/HEAD/FAQ.md?ref=main"',
+      )
+    })
+
+    it('resolves relative .md links with anchors to blob URL', async () => {
+      const info = changelogMdinfo()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[Install Section](./CONTRIBUTING.md#installation)`
+      const result = renderer(markdown)
+
+      expect(result.html).toContain(
+        'href="https://github.com/test-owner/test-repo/blob/HEAD/CONTRIBUTING.md#installation"',
+      )
+    })
+
+    it('resolves non-.md files to raw URL (not blob)', async () => {
+      const info = changelogMdinfo()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[Image](./assets/logo.png)`
+      const result = renderer(markdown)
+
+      expect(result.html).toContain(
+        'href="https://raw.githubusercontent.com/test-owner/test-repo/HEAD/assets/logo.png"',
+      )
+    })
+
+    it('resolves to the root when going to far back', async () => {
+      const info = changelogMdinfo()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[License](../../../LICENSE)`
+      const result = renderer(markdown)
+
+      expect(result.html).toContain(
+        'href="https://raw.githubusercontent.com/test-owner/test-repo/HEAD/LICENSE"',
+      )
+    })
+  })
+
+  describe('resolves from a deeper changelog.md', () => {
+    it('resolves relative .md links to blob URL for rendered viewing', async () => {
+      const info = changelogMdInfoWithPath()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[Contributing](./CONTRIBUTING.md)`
+      const result = renderer(markdown)
+
+      expect(result.html).toContain(
+        `href="https://github.com/test-owner/test-repo/blob/HEAD/packages/test/CONTRIBUTING.md"`,
+      )
+    })
+
+    it('resolves without ./ or / .md links to a relative blob URL', async () => {
+      const info = changelogMdInfoWithPath()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[Guide](GUIDE.MD)`
+      const result = renderer(markdown)
+      expect(result.html).toContain(
+        'href="https://github.com/test-owner/test-repo/blob/HEAD/packages/test/GUIDE.MD"',
+      )
+    })
+
+    it('resolves absolute .md links to blob URL', async () => {
+      const info = changelogMdInfoWithPath()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[Security](/SECURITY.MD)`
+
+      const result = renderer(markdown)
+      expect(result.html).toContain(
+        'href="https://github.com/test-owner/test-repo/blob/HEAD/SECURITY.MD"',
+      )
+    })
+
+    it('resolves nested relative .md links to blob URL', async () => {
+      const info = changelogMdInfoWithPath()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[API Docs](./docs/api/reference.md)`
+      const result = renderer(markdown)
+
+      expect(result.html).toContain(
+        'href="https://github.com/test-owner/test-repo/blob/HEAD/packages/test/docs/api/reference.md"',
+      )
+    })
+
+    it('resolves relative .md links with query strings to blob URL', async () => {
+      const info = changelogMdInfoWithPath()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[FAQ](./FAQ.md?ref=main)`
+      const result = renderer(markdown)
+
+      expect(result.html).toContain(
+        'href="https://github.com/test-owner/test-repo/blob/HEAD/packages/test/FAQ.md?ref=main"',
+      )
+    })
+
+    it('resolves relative .md links with anchors to blob URL', async () => {
+      const info = changelogMdInfoWithPath()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[Install Section](./CONTRIBUTING.md#installation)`
+      const result = renderer(markdown)
+
+      expect(result.html).toContain(
+        'href="https://github.com/test-owner/test-repo/blob/HEAD/packages/test/CONTRIBUTING.md#installation"',
+      )
+    })
+
+    it('resolves non-.md files to raw URL (not blob)', async () => {
+      const info = changelogMdInfoWithPath()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[Image](./assets/logo.png)`
+      const result = renderer(markdown)
+
+      expect(result.html).toContain(
+        'href="https://raw.githubusercontent.com/test-owner/test-repo/HEAD/packages/test/assets/logo.png"',
+      )
+    })
+
+    it('resolves to the root when going to far back', async () => {
+      const info = changelogMdInfoWithPath()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[License](../../../LICENSE)`
+      const result = renderer(markdown)
+
+      expect(result.html).toContain(
+        'href="https://raw.githubusercontent.com/test-owner/test-repo/HEAD/LICENSE"',
+      )
+    })
+  })
+
+  describe('resolves full urls', () => {
+    it('leaves absolute .md URLs unchanged', async () => {
+      const info = changelogMdInfoWithPath()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[External Guide](https://example.com/guide.md)`
+      const result = renderer(markdown)
+      expect(result.html).toContain('href="https://example.com/guide.md"')
+    })
+
+    it('leaves absolute non-.md URLs unchanged', async () => {
+      const info = changelogMdinfo()
+      const renderer = await changelogRenderer(info)
+      const markdown = `[Docs](https://docs.example.com/)`
+      const result = renderer(markdown)
+      expect(result.html).toContain('href="https://docs.example.com/"')
+    })
+  })
+
+  describe('anchor links', () => {
+    describe('for changelog.md', () => {
+      it('prefixes anchor links with user-content-', async () => {
+        const info = changelogMdinfo()
+        const renderer = await changelogRenderer(info)
+
+        const markdown = `[Jump to section](#installation)`
+        const result = renderer(markdown)
+
+        expect(result.html).toContain('href="#user-content-installation"')
+      })
+
+      it('normalizes mixed-case heading fragments to lowercase slugs', async () => {
+        const info = changelogMdinfo()
+        const renderer = await changelogRenderer(info)
+        const markdown = `[Associations section](#Associations)`
+        const result = renderer(markdown)
+
+        expect(result.html).toContain('href="#user-content-associations"')
+      })
+    })
+
+    describe('for releases', () => {
+      it('prefixes anchor links with user-content-', async () => {
+        const info = changelogMdinfo()
+        const renderer = await changelogRenderer(info)
+
+        const markdown = `[Jump to section](#installation)`
+        const result = renderer(markdown, '123456789')
+
+        expect(result.html).toContain('href="#user-content-123456789-installation"')
+      })
+
+      it('normalizes mixed-case heading fragments to lowercase slugs', async () => {
+        const info = changelogMdinfo()
+        const renderer = await changelogRenderer(info)
+        const markdown = `[Associations section](#Associations)`
+        const result = renderer(markdown, 123456789)
+
+        expect(result.html).toContain('href="#user-content-123456789-associations"')
+      })
+    })
+  })
+
+  describe('npm.js urls', () => {
+    it('redirects npmjs.com urls to local', async () => {
+      const markdown = `[Some npmjs.com link](https://www.npmjs.com/package/test-pkg)`
+      const info = changelogMdinfo()
+      const renderer = await changelogRenderer(info)
+      const result = renderer(markdown)
+
+      expect(result.html).toContain('href="/package/test-pkg"')
+    })
+
+    it('redirects npmjs.com urls to local (no www and http)', async () => {
+      const markdown = `[Some npmjs.com link](http://npmjs.com/package/test-pkg)`
+      const info = changelogMdinfo()
+      const renderer = await changelogRenderer(info)
+      const result = renderer(markdown)
+
+      expect(result.html).toContain('href="/package/test-pkg"')
+    })
+
+    it('does not redirect npmjs.com to local if they are in the list of exceptions', async () => {
+      const markdown = `[Root Contributing](https://www.npmjs.com/products)`
+      const info = changelogMdinfo()
+      const renderer = await changelogRenderer(info)
+      const result = renderer(markdown)
+
+      expect(result.html).toContain('href="https://www.npmjs.com/products"')
+    })
+
+    it('redirects npmjs.org urls to local', async () => {
+      const markdown = `[Some npmjs.org link](https://www.npmjs.org/package/test-pkg)`
+      const info = changelogMdinfo()
+      const renderer = await changelogRenderer(info)
+      const result = renderer(markdown)
+
+      expect(result.html).toContain('href="/package/test-pkg"')
+    })
+
+    it('redirects npmjs.org urls to local (no www and http)', async () => {
+      const markdown = `[Some npmjs.org link](http://npmjs.org/package/test-pkg)`
+      const info = changelogMdinfo()
+      const renderer = await changelogRenderer(info)
+      const result = renderer(markdown)
+
+      expect(result.html).toContain('href="/package/test-pkg"')
+    })
+  })
+})
+
+describe('Heading & toc resolution', () => {
+  describe('for markdown.md headings', () => {
+    it('should resolve heading starting from h2 & return to h3 at depth 2 correctly', async () => {
+      const info = changelogMdInfoWithPath()
+      const renderer = await changelogRenderer(info)
+      const markdown = `# Vue
+##v3
+###v3.5
+#### v3.5.33
+##### Features
+###### Notes
+##v2
+###v2.7
+#### v2.7.15
+##### Bug fixes
+###### Notes`
+      const result = renderer(markdown)
+
+      expect(result.html)
+        .toBe(`<h2 id="user-content-vue" data-level="1"><a href="#user-content-vue">Vue</a></h2>
+<h3 id="user-content-v3" data-level="2"><a href="#user-content-v3">v3</a></h3>
+<h4 id="user-content-v35" data-level="3"><a href="#user-content-v35">v3.5</a></h4>
+<h5 id="user-content-v3533" data-level="4"><a href="#user-content-v3533">v3.5.33</a></h5>
+<h6 id="user-content-features" data-level="5"><a href="#user-content-features">Features</a></h6>
+<h6 id="user-content-notes" data-level="6"><a href="#user-content-notes">Notes</a></h6>
+<h3 id="user-content-v2" data-level="2"><a href="#user-content-v2">v2</a></h3>
+<h4 id="user-content-v27" data-level="3"><a href="#user-content-v27">v2.7</a></h4>
+<h5 id="user-content-v2715" data-level="4"><a href="#user-content-v2715">v2.7.15</a></h5>
+<h6 id="user-content-bug-fixes" data-level="5"><a href="#user-content-bug-fixes">Bug fixes</a></h6>
+<h6 id="user-content-notes-1" data-level="6"><a href="#user-content-notes-1">Notes</a></h6>
+`)
+      expect(result.toc).toEqual([
+        {
+          depth: 1,
+          id: 'user-content-vue',
+          text: 'Vue',
+        },
+        {
+          depth: 2,
+          id: 'user-content-v3',
+          text: 'v3',
+        },
+        {
+          depth: 3,
+          id: 'user-content-v35',
+          text: 'v3.5',
+        },
+        {
+          depth: 4,
+          id: 'user-content-v3533',
+          text: 'v3.5.33',
+        },
+        {
+          depth: 5,
+          id: 'user-content-features',
+          text: 'Features',
+        },
+        {
+          depth: 6,
+          id: 'user-content-notes',
+          text: 'Notes',
+        },
+        {
+          depth: 2,
+          id: 'user-content-v2',
+          text: 'v2',
+        },
+        {
+          depth: 3,
+          id: 'user-content-v27',
+          text: 'v2.7',
+        },
+        {
+          depth: 4,
+          id: 'user-content-v2715',
+          text: 'v2.7.15',
+        },
+        {
+          depth: 5,
+          id: 'user-content-bug-fixes',
+          text: 'Bug fixes',
+        },
+        {
+          depth: 6,
+          id: 'user-content-notes-1',
+          text: 'Notes',
+        },
+      ])
+    })
+  })
+
+  describe('for releases headings', () => {
+    it('should resolve heading starting from h3 & return to h4 at depth 2 correctly', async () => {
+      const info = changelogMdInfoWithPath()
+      const renderer = await changelogRenderer(info)
+      const markdown = `# Vue
+##v3
+###v3.5
+#### v3.5.33
+##### Features
+###### Notes
+##v2
+###v2.7
+#### v2.7.15
+##### Bug fixes
+###### Notes`
+      const result = renderer(markdown, 123456789)
+
+      expect(result.html)
+        .toBe(`<h3 id="user-content-123456789-vue" data-level="1"><a href="#user-content-123456789-vue">Vue</a></h3>
+<h4 id="user-content-123456789-v3" data-level="2"><a href="#user-content-123456789-v3">v3</a></h4>
+<h5 id="user-content-123456789-v35" data-level="3"><a href="#user-content-123456789-v35">v3.5</a></h5>
+<h6 id="user-content-123456789-v3533" data-level="4"><a href="#user-content-123456789-v3533">v3.5.33</a></h6>
+<h6 id="user-content-123456789-features" data-level="5"><a href="#user-content-123456789-features">Features</a></h6>
+<h6 id="user-content-123456789-notes" data-level="6"><a href="#user-content-123456789-notes">Notes</a></h6>
+<h4 id="user-content-123456789-v2" data-level="2"><a href="#user-content-123456789-v2">v2</a></h4>
+<h5 id="user-content-123456789-v27" data-level="3"><a href="#user-content-123456789-v27">v2.7</a></h5>
+<h6 id="user-content-123456789-v2715" data-level="4"><a href="#user-content-123456789-v2715">v2.7.15</a></h6>
+<h6 id="user-content-123456789-bug-fixes" data-level="5"><a href="#user-content-123456789-bug-fixes">Bug fixes</a></h6>
+<h6 id="user-content-123456789-notes-1" data-level="6"><a href="#user-content-123456789-notes-1">Notes</a></h6>
+`)
+      expect(result.toc).toEqual([
+        {
+          depth: 1,
+          id: 'user-content-123456789-vue',
+          text: 'Vue',
+        },
+        {
+          depth: 2,
+          id: 'user-content-123456789-v3',
+          text: 'v3',
+        },
+        {
+          depth: 3,
+          id: 'user-content-123456789-v35',
+          text: 'v3.5',
+        },
+        {
+          depth: 4,
+          id: 'user-content-123456789-v3533',
+          text: 'v3.5.33',
+        },
+        {
+          depth: 5,
+          id: 'user-content-123456789-features',
+          text: 'Features',
+        },
+        {
+          depth: 6,
+          id: 'user-content-123456789-notes',
+          text: 'Notes',
+        },
+        {
+          depth: 2,
+          id: 'user-content-123456789-v2',
+          text: 'v2',
+        },
+        {
+          depth: 3,
+          id: 'user-content-123456789-v27',
+          text: 'v2.7',
+        },
+        {
+          depth: 4,
+          id: 'user-content-123456789-v2715',
+          text: 'v2.7.15',
+        },
+        {
+          depth: 5,
+          id: 'user-content-123456789-bug-fixes',
+          text: 'Bug fixes',
+        },
+        {
+          depth: 6,
+          id: 'user-content-123456789-notes-1',
+          text: 'Notes',
+        },
+      ])
+    })
+  })
+
+  it("shouldn't resolve package@version to an email", async () => {
+    const info = changelogMdInfoWithPath()
+    const renderer = await changelogRenderer(info)
+    const markdown = '## test-pkg@1.0.0'
+    const result = renderer(markdown)
+
+    expect(result.html).toBe(
+      '<h2 id="user-content-test-pkg100" data-level="2"><a href="#user-content-test-pkg100">test-pkg@1.0.0</a></h2>\n',
+    )
+  })
+})
diff --git a/test/unit/server/utils/readme.spec.ts b/test/unit/server/utils/readme.spec.ts
index dacc2653b7..d24158d777 100644
--- a/test/unit/server/utils/readme.spec.ts
+++ b/test/unit/server/utils/readme.spec.ts
@@ -592,13 +592,13 @@ describe('HTML output', () => {
   })
 
   describe('heading anchors (renderer.heading)', () => {
-    it('strips a full-line anchor wrapper and uses inner text for slug, toc, and permalink', async () => {
+    it('keeps the full-line anchor wrapper and places the link to the heading at the end', async () => {
       const markdown = '## <a href="https://example.com">My Section</a>'
       const result = await renderReadmeHtml(markdown, 'test-pkg')
 
       expect(result.toc).toEqual([{ text: 'My Section', depth: 2, id: 'user-content-my-section' }])
       expect(result.html).toBe(
-        `<h3 id="user-content-my-section" data-level="2"><a href="#user-content-my-section">My Section</a></h3>\n`,
+        `<h3 id="user-content-my-section" data-level="2"><a href="https://example.com" rel="nofollow noreferrer noopener" target="_blank">My Section</a><a href="#user-content-my-section" aria-hidden="true" tabindex="-1"></a></h3>\n`,
       )
     })
 
@@ -610,7 +610,7 @@ describe('HTML output', () => {
         { text: 'See docs for more', depth: 3, id: 'user-content-see-docs-for-more' },
       ])
       expect(result.html).toBe(
-        `<h3 id="user-content-see-docs-for-more" data-level="3">See <a href="https://example.com" rel="nofollow noreferrer noopener" target="_blank">docs</a> for more<a href="#user-content-see-docs-for-more"></a></h3>\n`,
+        `<h3 id="user-content-see-docs-for-more" data-level="3">See <a href="https://example.com" rel="nofollow noreferrer noopener" target="_blank">docs</a> for more<a href="#user-content-see-docs-for-more" aria-hidden="true" tabindex="-1"></a></h3>\n`,
       )
     })
 
@@ -620,7 +620,7 @@ describe('HTML output', () => {
 
       expect(result.toc).toEqual([{ text: 'Guide: page', depth: 2, id: 'user-content-guide-page' }])
       expect(result.html).toBe(
-        '<h3 id="user-content-guide-page" data-level="2">Guide: <a href="https://example.com/page" rel="nofollow noreferrer noopener" target="_blank">page</a><a href="#user-content-guide-page"></a></h3>',
+        '<h3 id="user-content-guide-page" data-level="2">Guide: <a href="https://example.com/page" rel="nofollow noreferrer noopener" target="_blank">page</a><a aria-hidden="true" tabindex="-1" href="#user-content-guide-page"></a></h3>',
       )
     })
   })