fix: ensure HMR works properly for page outline

The client-side based implementation in #1281 makes HMR update for the
outlines flaky and unreliable.

The headers payload for each page chunk is relatively cheap in return
for the correctness, since they are inlined as a JSON string.

__tests__/unit/client/theme-default/composables/outline.test.ts

@@ -7,14 +7,23 @@ describe('client/theme-default/composables/outline', () => {
         resolveHeaders(
           [
             {
-              level: 2,
+              level: 1,
-              title: 'h2 - 1',
+              title: 'h1 - 1',
-              link: '#h2-1'
+              link: '#h1-1',
-            },
+              children: [
-            {
+                {
-              level: 3,
+                  level: 2,
-              title: 'h3 - 1',
+                  title: 'h2 - 1',
-              link: '#h3-1'
+                  link: '#h2-1',
+                  children: [
+                    {
+                      level: 3,
+                      title: 'h3 - 1',
+                      link: '#h3-1'
+                    }
+                  ]
+                }
+              ]
             }
           ],
           [2, 3]
@@ -42,12 +51,14 @@ describe('client/theme-default/composables/outline', () => {
             {
               level: 2,
               title: 'h2 - 1',
-              link: '#h2-1'
+              link: '#h2-1',
-            },
+              children: [
-            {
+                {
-              level: 3,
+                  level: 3,
-              title: 'h3 - 1',
+                  title: 'h3 - 1',
-              link: '#h3-1'
+                  link: '#h3-1'
+                }
+              ]
             }
           ],
           2
@@ -68,42 +79,52 @@ describe('client/theme-default/composables/outline', () => {
             {
               level: 2,
               title: 'h2 - 1',
-              link: '#h2-1'
+              link: '#h2-1',
-            },
+              children: [
-            {
+                {
-              level: 3,
+                  level: 3,
-              title: 'h3 - 1',
+                  title: 'h3 - 1',
-              link: '#h3-1'
+                  link: '#h3-1',
-            },
+                  children: [
-            {
+                    {
-              level: 4,
+                      level: 4,
-              title: 'h4 - 1',
+                      title: 'h4 - 1',
-              link: '#h4-1'
+                      link: '#h4-1'
-            },
+                    }
-            {
+                  ]
-              level: 3,
+                },
-              title: 'h3 - 2',
+                {
-              link: '#h3-2'
+                  level: 3,
-            },
+                  title: 'h3 - 2',
-            {
+                  link: '#h3-2',
-              level: 4,
+                  children: [
-              title: 'h4 - 2',
+                    {
-              link: '#h4-2'
+                      level: 4,
+                      title: 'h4 - 2',
+                      link: '#h4-2'
+                    }
+                  ]
+                }
+              ]
             },
             {
               level: 2,
               title: 'h2 - 2',
-              link: '#h2-2'
+              link: '#h2-2',
-            },
+              children: [
-            {
+                {
-              level: 3,
+                  level: 3,
-              title: 'h3 - 3',
+                  title: 'h3 - 3',
-              link: '#h3-3'
+                  link: '#h3-3',
-            },
+                  children: [
-            {
+                    {
-              level: 4,
+                      level: 4,
-              title: 'h4 - 3',
+                      title: 'h4 - 3',
-              link: '#h4-3'
+                      link: '#h4-3'
+                    }
+                  ]
+                }
+              ]
             }
           ],
           'deep'

docs/.vitepress/config.ts

@@ -14,12 +14,6 @@ export default defineConfig({
 
   head: [['meta', { name: 'theme-color', content: '#3c8772' }]],
 
-  markdown: {
-    headers: {
-      level: [0, 0]
-    }
-  },
-
   themeConfig: {
     nav: nav(),
 

src/client/app/components/Content.ts

@@ -1,17 +1,13 @@
-import { defineComponent, h, onUpdated } from 'vue'
+import { defineComponent, h } from 'vue'
 import { useRoute } from '../router.js'
 
 export const Content = defineComponent({
   name: 'VitePressContent',
   props: {
-    onContentUpdated: Function,
     as: { type: [Object, String], default: 'div' }
   },
   setup(props) {
     const route = useRoute()
-    onUpdated(() => {
-      props.onContentUpdated?.()
-    })
     return () =>
       h(props.as, { style: { position: 'relative' } }, [
         route.component ? h(route.component) : null

src/client/theme-default/components/VPDoc.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { useRoute } from 'vitepress'
-import { computed, provide, ref } from 'vue'
+import { computed } from 'vue'
 import { useSidebar } from '../composables/sidebar.js'
 import VPDocAside from './VPDocAside.vue'
 import VPDocFooter from './VPDocFooter.vue'
@@ -11,9 +11,6 @@ const { hasSidebar, hasAside } = useSidebar()
 const pageName = computed(() =>
   route.path.replace(/[./]+/g, '_').replace(/_html$/, '')
 )
-
-const onContentUpdated = ref()
-provide('onContentUpdated', onContentUpdated)
 </script>
 
 <template>
@@ -42,7 +39,7 @@ provide('onContentUpdated', onContentUpdated)
         <div class="content-container">
           <slot name="doc-before" />
           <main class="main">
-            <Content class="vp-doc" :class="pageName" :onContentUpdated="onContentUpdated" />
+            <Content class="vp-doc" :class="pageName" />
           </main>
           <slot name="doc-footer-before" />
           <VPDocFooter />

src/client/theme-default/components/VPDocAsideOutline.vue

@@ -1,26 +1,20 @@
 <script setup lang="ts">
-import type { DefaultTheme } from 'vitepress/theme'
+import { computed, ref } from 'vue'
-import { computed, inject, ref, type Ref } from 'vue'
 import { useData } from '../composables/data.js'
 import {
-  getHeaders,
+  resolveHeaders,
-  useActiveAnchor,
+  useActiveAnchor
-  type MenuItem
 } from '../composables/outline.js'
 import VPDocAsideOutlineItem from './VPDocAsideOutlineItem.vue'
 
-const { frontmatter, theme } = useData()
+const { frontmatter, page, theme } = useData()
 
-const pageOutline = computed<DefaultTheme.Config['outline']>(
+const headers = computed(() => {
-  () => frontmatter.value.outline ?? theme.value.outline
+  return resolveHeaders(
-)
+    page.value.headers,
-
+    frontmatter.value.outline ?? theme.value.outline
-const onContentUpdated = inject('onContentUpdated') as Ref<() => void>
+  )
-onContentUpdated.value = () => {
+})
-  headers.value = getHeaders(pageOutline.value, theme.value.outlineBadges)
-}
-
-const headers = ref<MenuItem[]>([])
 const hasOutline = computed(() => headers.value.length > 0)
 
 const container = ref()

src/client/theme-default/composables/outline.ts

@@ -11,41 +11,14 @@ export type MenuItem = Omit<Header, 'slug' | 'children'> & {
   children?: MenuItem[]
 }
 
-export function getHeaders(
-  pageOutline: DefaultTheme.Config['outline'],
-  outlineBadges: DefaultTheme.Config['outlineBadges']
-) {
-  if (pageOutline === false) return []
-  let updatedHeaders: MenuItem[] = []
-
-  document
-    .querySelectorAll<HTMLHeadingElement>('h2, h3, h4, h5, h6')
-    .forEach((el) => {
-      if (el.textContent && el.id) {
-        let title = el.textContent
-
-        if (outlineBadges === false) {
-          const clone = el.cloneNode(true) as HTMLElement
-          for (const child of clone.querySelectorAll('.VPBadge')) {
-            child.remove()
-          }
-          title = clone.textContent || ''
-        }
-
-        updatedHeaders.push({
-          level: Number(el.tagName[1]),
-          title: title.replace(/\s+#\s*$/, ''),
-          link: `#${el.id}`
-        })
-      }
-    })
-  return resolveHeaders(updatedHeaders, pageOutline)
-}
-
 export function resolveHeaders(
   headers: MenuItem[],
-  range?: Exclude<DefaultTheme.Config['outline'], false>
+  range?: DefaultTheme.Config['outline']
 ) {
+  if (range === false) {
+    return []
+  }
+
   const levelsRange =
     (typeof range === 'object' && !Array.isArray(range)
       ? range.level
@@ -58,51 +31,38 @@ export function resolveHeaders(
       ? [2, 6]
       : levelsRange
 
-  return groupHeaders(headers, levels)
+  const isInRange = (h: MenuItem): boolean =>
+    h.level >= levels[0] && h.level <= levels[1]
+
+  return filterHeaders(headers, isInRange)
 }
 
-function groupHeaders(headers: MenuItem[], levelsRange: [number, number]) {
+function filterHeaders(
+  headers: MenuItem[],
+  isInRange: (h: MenuItem) => boolean
+) {
   const result: MenuItem[] = []
 
   headers = headers.map((h) => ({ ...h }))
-  headers.forEach((h, index) => {
+  headers.forEach((h) => {
-    if (h.level >= levelsRange[0] && h.level <= levelsRange[1]) {
+    if (isInRange(h)) {
-      if (addToParent(index, headers, levelsRange)) {
+      if (h.children) {
-        result.push(h)
+        const filteredChildren = filterHeaders(h.children, isInRange)
+        if (filteredChildren.length) {
+          h.children = filteredChildren
+        } else {
+          delete h.children
+        }
       }
+      result.push(h)
+    } else if (h.children) {
+      result.push(...filterHeaders(h.children, isInRange))
     }
   })
 
   return result
 }
 
-function addToParent(
-  currIndex: number,
-  headers: MenuItem[],
-  levelsRange: [number, number]
-) {
-  if (currIndex === 0) {
-    return true
-  }
-
-  const currentHeader = headers[currIndex]
-  for (let index = currIndex - 1; index >= 0; index--) {
-    const header = headers[index]
-
-    if (
-      header.level < currentHeader.level &&
-      header.level >= levelsRange[0] &&
-      header.level <= levelsRange[1]
-    ) {
-      if (header.children == null) header.children = []
-      header.children.push(currentHeader)
-      return false
-    }
-  }
-
-  return true
-}
-
 export function useActiveAnchor(
   container: Ref<HTMLElement>,
   marker: Ref<HTMLElement>

template/.vitepress/theme/style.css

@@ -1,4 +1,9 @@
 <% if (defaultTheme) { %>/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/**
  * Colors
  * -------------------------------------------------------------------------- */