feat(theme): support dynamic headers and nesting in outline (#1281)

Co-authored-by: fi3ework <fi3ework@gmail.com>

__tests__/client/theme-default/composables/outline.spec.ts

@@ -0,0 +1,166 @@
+import { describe, test, expect } from 'vitest'
+import * as outline from 'client/theme-default/composables/outline'
+
+describe('client/theme-default/composables/outline', () => {
+  describe('resolveHeader', () => {
+    test('levels range', () => {
+      expect(
+        outline.resolveHeaders(
+          [
+            {
+              level: 2,
+              title: 'h2 - 1',
+              link: '#h2-1'
+            },
+            {
+              level: 3,
+              title: 'h3 - 1',
+              link: '#h3-1'
+            }
+          ],
+          [2, 3]
+        )
+      ).toEqual([
+        {
+          level: 2,
+          title: 'h2 - 1',
+          link: '#h2-1',
+          children: [
+            {
+              level: 3,
+              title: 'h3 - 1',
+              link: '#h3-1'
+            }
+          ]
+        }
+      ])
+    })
+
+    test('specific level', () => {
+      expect(
+        outline.resolveHeaders(
+          [
+            {
+              level: 2,
+              title: 'h2 - 1',
+              link: '#h2-1'
+            },
+            {
+              level: 3,
+              title: 'h3 - 1',
+              link: '#h3-1'
+            }
+          ],
+          2
+        )
+      ).toEqual([
+        {
+          level: 2,
+          title: 'h2 - 1',
+          link: '#h2-1'
+        }
+      ])
+    })
+
+    test('complex deep', () => {
+      expect(
+        outline.resolveHeaders(
+          [
+            {
+              level: 2,
+              title: 'h2 - 1',
+              link: '#h2-1'
+            },
+            {
+              level: 3,
+              title: 'h3 - 1',
+              link: '#h3-1'
+            },
+            {
+              level: 4,
+              title: 'h4 - 1',
+              link: '#h4-1'
+            },
+            {
+              level: 3,
+              title: 'h3 - 2',
+              link: '#h3-2'
+            },
+            {
+              level: 4,
+              title: 'h4 - 2',
+              link: '#h4-2'
+            },
+            {
+              level: 2,
+              title: 'h2 - 2',
+              link: '#h2-2'
+            },
+            {
+              level: 3,
+              title: 'h3 - 3',
+              link: '#h3-3'
+            },
+            {
+              level: 4,
+              title: 'h4 - 3',
+              link: '#h4-3'
+            }
+          ],
+          'deep'
+        )
+      ).toEqual([
+        {
+          level: 2,
+          title: 'h2 - 1',
+          link: '#h2-1',
+          children: [
+            {
+              level: 3,
+              title: 'h3 - 1',
+              link: '#h3-1',
+              children: [
+                {
+                  level: 4,
+                  title: 'h4 - 1',
+                  link: '#h4-1'
+                }
+              ]
+            },
+            {
+              level: 3,
+              title: 'h3 - 2',
+              link: '#h3-2',
+              children: [
+                {
+                  level: 4,
+                  title: 'h4 - 2',
+                  link: '#h4-2'
+                }
+              ]
+            }
+          ]
+        },
+        {
+          level: 2,
+          title: 'h2 - 2',
+          link: '#h2-2',
+          children: [
+            {
+              level: 3,
+              title: 'h3 - 3',
+              link: '#h3-3',
+              children: [
+                {
+                  level: 4,
+                  title: 'h4 - 3',
+                  link: '#h4-3'
+                }
+              ]
+            }
+          ]
+        }
+      ])
+    })
+  })
+})

docs/.vitepress/config.ts

@@ -9,6 +9,12 @@ export default defineConfig({
   lastUpdated: true,
   cleanUrls: 'without-subfolders',
 
+  markdown: {
+    headers: {
+      level: [0, 0]
+    }
+  },
+
   themeConfig: {
     nav: nav(),
 

docs/config/frontmatter-configs.md

@@ -212,3 +212,10 @@ If you want the right aside component in `doc` layout not to be shown, set this
 aside: false
 ---
 ```
+
+## outline
+
+- Type: `number | [number, number] | 'deep' | false`
+- Default: `2`
+
+The levels of header in the outline to display for the page. It's same as [config.themeConfig.outline](../config/theme-configs#outline), and it overrides the theme config.

docs/config/theme-configs.md

@@ -135,6 +135,13 @@ interface SidebarItem {
 }
 ```
 
+## outline
+
+- Type: `number | [number, number] | 'deep' | false`
+- Default: `2`
+
+The levels of header to display in the outline. You can specify a particular level by passing a number, or you can provide a level range by passing a tuple containing the bottom and upper limits. When passing `'deep'` which equals `[2, 6]`, all header levels are shown in the outline except `h1`. Set `false` to hide outline.
+
 ## outlineTitle
 
 - Type: `string`

examples/configured/__test__/outline.spec.ts

@@ -18,15 +18,27 @@ describe('outline', () => {
     expect(outlineLinksContent).toEqual([
       'h2 - 1',
       'h3 - 1',
+      'h4 - 1',
       'h3 - 2',
+      'h4 - 2',
       'h2 - 2',
-      'h3 - 3'
+      'h3 - 3',
+      'h4 - 3'
     ])
 
     const linkHrefs = await outlineLinksLocator.evaluateAll((element) =>
       element.map((element) => element.getAttribute('href'))
     )
 
-    expect(linkHrefs).toEqual(['#h2-1', '#h3-1', '#h3-2', '#h2-2', '#h3-3'])
+    expect(linkHrefs).toEqual([
+      '#h2-1',
+      '#h3-1',
+      '#h4-1',
+      '#h3-2',
+      '#h4-2',
+      '#h2-2',
+      '#h3-3',
+      '#h4-3'
+    ])
   })
 })

src/client/app/components/Content.ts

@@ -1,10 +1,16 @@
-import { defineComponent, h } from 'vue'
+import { defineComponent, h, onUpdated } from 'vue'
 import { useRoute } from '../router.js'
 
 export const Content = defineComponent({
   name: 'VitePressContent',
-  setup() {
+  props: {
+    onContentUpdated: Function
+  },
+  setup(props) {
     const route = useRoute()
+    onUpdated(() => {
+      props.onContentUpdated?.()
+    })
     return () =>
       h('div', { 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 { computed } from 'vue'
 import { useRoute } from 'vitepress'
+import { computed, provide, ref } from 'vue'
 import { useSidebar } from '../composables/sidebar.js'
 import VPDocAside from './VPDocAside.vue'
 import VPDocFooter from './VPDocFooter.vue'
@@ -11,6 +11,9 @@ const { hasSidebar, hasAside } = useSidebar()
 const pageName = computed(() =>
   route.path.replace(/[./]+/g, '_').replace(/_html$/, '')
 )
+
+const onContentUpdated = ref()
+provide('onContentUpdated', onContentUpdated)
 </script>
 
 <template>
@@ -39,7 +42,7 @@ const pageName = computed(() =>
         <div class="content-container">
           <slot name="doc-before" />
           <main class="main">
-            <Content class="vp-doc" :class="pageName" />
+            <Content class="vp-doc" :class="pageName" :onContentUpdated="onContentUpdated" />
           </main>
           <slot name="doc-footer-before" />
           <VPDocFooter />

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

@@ -3,15 +3,15 @@ import { useData } from 'vitepress'
 import VPDocAsideOutline from './VPDocAsideOutline.vue'
 import VPDocAsideCarbonAds from './VPDocAsideCarbonAds.vue'
 
-const { page, theme } = useData()
+const { theme } = useData()
 </script>
 
 <template>
   <div class="VPDocAside">
     <slot name="aside-top" />
 
     <slot name="aside-outline-before" />
-    <VPDocAsideOutline v-if="page.headers.length" />
+    <VPDocAsideOutline />
     <slot name="aside-outline-after" />
 
     <div class="spacer" />

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

@@ -1,14 +1,27 @@
 <script setup lang="ts">
-import { ref } from 'vue'
 import { useData } from 'vitepress'
+import type { DefaultTheme } from 'vitepress/theme'
+import { computed, inject, ref, type Ref } from 'vue'
 import {
-  useOutline,
-  useActiveAnchor
+  getHeaders,
+  useActiveAnchor,
+  type MenuItem
 } from '../composables/outline.js'
+import VPDocAsideOutlineItem from './VPDocAsideOutlineItem.vue'
 
-const { page, frontmatter, theme } = useData()
+const { frontmatter, theme } = useData()
 
-const { hasOutline } = useOutline()
+const pageOutline = computed<DefaultTheme.Config['outline']>(
+  () => frontmatter.value.outline ?? theme.value.outline
+)
+
+const onContentUpdated = inject('onContentUpdated') as Ref<() => void>
+onContentUpdated.value = () => {
+  headers.value = getHeaders(pageOutline.value)
+}
+
+const headers = ref<MenuItem[]>([])
+const hasOutline = computed(() => headers.value.length > 0)
 
 const container = ref()
 const marker = ref()
@@ -37,23 +50,7 @@ function handleClick({ target: el }: Event) {
         <span class="visually-hidden" id="doc-outline-aria-label">
           Table of Contents for current page
         </span>
-
-        <ul class="root">
-          <li
-            v-for="{ title, link, children } in page.headers"
-          >
-            <a class="outline-link" :href="link" @click="handleClick">
-              {{ title }}
-            </a>
-            <ul v-if="children && frontmatter.outline === 'deep'">
-              <li v-for="{ title, link } in children">
-                <a class="outline-link nested" :href="link" @click="handleClick">
-                  {{ title }}
-                </a>
-              </li>
-            </ul>
-          </li>
-        </ul>
+        <VPDocAsideOutlineItem :headers="headers" :root="true" :onClick="handleClick" />
       </nav>
     </div>
   </div>
@@ -94,29 +91,4 @@ function handleClick({ target: el }: Event) {
   font-size: 13px;
   font-weight: 600;
 }
-
-.outline-link {
-  display: block;
-  line-height: 28px;
-  color: var(--vp-c-text-2);
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  transition: color 0.5s;
-}
-
-.outline-link:hover,
-.outline-link.active {
-  color: var(--vp-c-text-1);
-  transition: color 0.25s;
-}
-
-.outline-link.nested {
-  padding-left: 13px;
-}
-
-.root {
-  position: relative;
-  z-index: 1;
-}
 </style>