diff --git a/app/pages/package-code/[[org]]/[packageName]/v/[version]/[...filePath].vue b/app/pages/package-code/[[org]]/[packageName]/v/[version]/[...filePath].vue
index 7d42e6ef3..2202494d7 100644
--- a/app/pages/package-code/[[org]]/[packageName]/v/[version]/[...filePath].vue
+++ b/app/pages/package-code/[[org]]/[packageName]/v/[version]/[...filePath].vue
@@ -13,6 +13,7 @@ definePageMeta({
     '/package/code/:packageName/v/:version/:filePath(.*)?',
     // '/code/@:org?/:packageName/v/:version/:filePath(.*)?',
   ],
+  scrollMargin: 160,
 })
 
 const route = useRoute('code')
diff --git a/app/pages/package-docs/[...path].vue b/app/pages/package-docs/[...path].vue
index fe60f7fb0..da1038e34 100644
--- a/app/pages/package-docs/[...path].vue
+++ b/app/pages/package-docs/[...path].vue
@@ -7,6 +7,7 @@ definePageMeta({
   name: 'docs',
   path: '/package-docs/:path+',
   alias: ['/package/docs/:path+', '/docs/:path+'],
+  scrollMargin: 180,
 })
 
 const route = useRoute('docs')
diff --git a/app/pages/package/[[org]]/[name]/index.vue b/app/pages/package/[[org]]/[name]/index.vue
index 20f211960..ba122fbfc 100644
--- a/app/pages/package/[[org]]/[name]/index.vue
+++ b/app/pages/package/[[org]]/[name]/index.vue
@@ -2,6 +2,7 @@
 // stub page to help with paths
 definePageMeta({
   name: 'package',
+  scrollMargin: 150,
 })
 </script>
 
diff --git a/app/router.options.ts b/app/router.options.ts
index 180dd68e9..a6d9db7cc 100644
--- a/app/router.options.ts
+++ b/app/router.options.ts
@@ -3,13 +3,18 @@ import type { RouterConfig } from 'nuxt/schema'
 export default {
   scrollBehavior(to, _from, savedPosition) {
     // If the browser has a saved position (e.g. back/forward navigation), restore it
+
     if (savedPosition) {
       return savedPosition
     }
-
     // If navigating to a hash anchor, scroll to it
     if (to.hash) {
-      return { el: to.hash, behavior: 'smooth' }
+      const { scrollMargin } = to.meta
+      return {
+        el: to.hash,
+        behavior: 'smooth',
+        top: typeof scrollMargin == 'number' ? scrollMargin : 70,
+      }
     }
 
     // Otherwise, scroll to the top of the page
diff --git a/app/types/routeMeta.ts b/app/types/routeMeta.ts
new file mode 100644
index 000000000..491bd5a99
--- /dev/null
+++ b/app/types/routeMeta.ts
@@ -0,0 +1,12 @@
+import '#app'
+import '#vue-router'
+
+declare module '#app' {
+  interface PageMeta {
+    /**
+     * top margin in pixels for scrolling to an element
+     * @default 70
+     */
+    scrollMargin?: number
+  }
+}