fix: prevent generation of empty references sidebar group

fixtures/basics/src/shared.ts

@@ -1,3 +1,5 @@
+export { doThingA as doThingARef } from './functions'
+
 /**
  * This is a string variable.
  */

packages/starlight-typedoc/libs/starlight.ts

@@ -2,10 +2,18 @@ import path from 'node:path'
 
 import type { StarlightPlugin } from '@astrojs/starlight/types'
 import { slug } from 'github-slugger'
-import { type DeclarationReflection, type ProjectReflection, ReflectionKind } from 'typedoc'
+import {
+  type DeclarationReflection,
+  type ProjectReflection,
+  ReflectionKind,
+  ReferenceReflection,
+  type ReflectionGroup,
+} from 'typedoc'
 
 import type { StarlightTypeDocSidebarOptions } from '..'
 
+const externalLinkRegex = /^(http|ftp)s?:\/\//
+
 const sidebarDefaultOptions = {
   collapsed: false,
   label: 'API',
@@ -24,13 +32,13 @@ export function getSidebarFromReflections(
   sidebar: StarlightUserConfigSidebar,
   options: StarlightTypeDocSidebarOptions = {},
   reflections: ProjectReflection | DeclarationReflection,
-  outputDirectory: string,
+  baseOutputDirectory: string,
 ): StarlightUserConfigSidebar {
   if (!sidebar || sidebar.length === 0) {
     return sidebar
   }
 
-  const sidebarGroup = getSidebarGroupFromReflections(options, reflections, outputDirectory)
+  const sidebarGroup = getSidebarGroupFromReflections(options, reflections, baseOutputDirectory, baseOutputDirectory)
 
   function replaceSidebarGroupPlaceholder(group: SidebarManualGroup): SidebarGroup {
     if (group.label === starlightTypeDocSidebarGroupLabel.toString()) {
@@ -57,7 +65,7 @@ export function getSidebarFromReflections(
 function getSidebarGroupFromPackageReflections(
   options: StarlightTypeDocSidebarOptions,
   reflections: ProjectReflection | DeclarationReflection,
-  outputDirectory: string,
+  baseOutputDirectory: string,
 ): SidebarGroup {
   const groups = (reflections.children ?? []).map((child) => {
     if (!child.url) {
@@ -66,7 +74,13 @@ function getSidebarGroupFromPackageReflections(
 
     const url = path.parse(child.url)
 
-    return getSidebarGroupFromReflections(options, child, `${outputDirectory}/${url.dir}`, child.name)
+    return getSidebarGroupFromReflections(
+      options,
+      child,
+      baseOutputDirectory,
+      `${baseOutputDirectory}/${url.dir}`,
+      child.name,
+    )
   })
 
   return {
@@ -79,6 +93,7 @@ function getSidebarGroupFromPackageReflections(
 function getSidebarGroupFromReflections(
   options: StarlightTypeDocSidebarOptions,
   reflections: ProjectReflection | DeclarationReflection,
+  baseOutputDirectory: string,
   outputDirectory: string,
   label?: string,
 ): SidebarGroup {
@@ -105,11 +120,16 @@ function getSidebarGroupFromReflections(
             return getSidebarGroupFromReflections(
               { collapsed: true, label: child.name },
               child,
+              baseOutputDirectory,
               `${outputDirectory}/${isParentKindModule ? url.dir.split('/').slice(1).join('/') : url.dir}`,
             )
           })
         }
 
+        if (isReferenceReflectionGroup(group)) {
+          return getReferencesSidebarGroup(group, baseOutputDirectory)
+        }
+
         return {
           collapsed: true,
           label: group.title,
@@ -123,16 +143,85 @@ function getSidebarGroupFromReflections(
   }
 }
 
+function getReferencesSidebarGroup(
+  group: ReflectionGroup,
+  baseOutputDirectory: string,
+): SidebarManualGroup | undefined {
+  const referenceItems: LinkItem[] = group.children
+    .map((child) => {
+      const reference = child as ReferenceReflection
+      let target = reference.tryGetTargetReflectionDeep()
+
+      if (!target) {
+        return undefined
+      }
+
+      if (target.kindOf(ReflectionKind.TypeLiteral) && target.parent) {
+        target = target.parent
+      }
+
+      if (!target.url) {
+        return undefined
+      }
+
+      return {
+        label: reference.name,
+        link: getRelativeURL(target.url, getStarlightTypeDocOutputDirectory(baseOutputDirectory)),
+      }
+    })
+    .filter((item): item is LinkItem => item !== undefined)
+
+  if (referenceItems.length === 0) {
+    return undefined
+  }
+
+  return {
+    label: group.title,
+    items: referenceItems,
+  }
+}
+
 export function getAsideMarkdown(type: AsideType, title: string, content: string) {
   return `:::${type}[${title}]
 ${content}
 :::`
 }
 
+export function getRelativeURL(url: string | undefined, baseUrl: string): string | null {
+  if (!url) {
+    return null
+  } else if (externalLinkRegex.test(url)) {
+    return url
+  }
+
+  const filePath = path.parse(url)
+  const [, anchor] = filePath.base.split('#')
+  const segments = filePath.dir
+    .split('/')
+    .map((segment) => slug(segment))
+    .filter((segment) => segment !== '')
+
+  let constructedUrl = typeof baseUrl === 'string' ? baseUrl : ''
+  constructedUrl += segments.length > 0 ? `${segments.join('/')}/` : ''
+  constructedUrl += slug(filePath.name)
+  constructedUrl += '/'
+  constructedUrl += anchor && anchor.length > 0 ? `#${anchor}` : ''
+
+  return constructedUrl
+}
+
+export function getStarlightTypeDocOutputDirectory(outputDirectory: string, base = '') {
+  return path.posix.join(base, `/${outputDirectory}${outputDirectory.endsWith('/') ? '' : '/'}`)
+}
+
 function isSidebarManualGroup(item: NonNullable<StarlightUserConfigSidebar>[number]): item is SidebarManualGroup {
   return 'items' in item
 }
 
+function isReferenceReflectionGroup(group: ReflectionGroup) {
+  return group.children.every((child) => child instanceof ReferenceReflection)
+}
+
 type SidebarGroup =
   | SidebarManualGroup
   | {

packages/starlight-typedoc/libs/theme.ts

@@ -1,16 +1,11 @@
-import path from 'node:path'
-
-import { slug } from 'github-slugger'
 import { Reflection, type Comment, type CommentTag, type Options, type PageEvent } from 'typedoc'
 import { MarkdownTheme, MarkdownThemeRenderContext } from 'typedoc-plugin-markdown'
 
-import { getAsideMarkdown } from './starlight'
+import { getAsideMarkdown, getRelativeURL } from './starlight'
 
 const customBlockTagTypes = ['@deprecated'] as const
 const customModifiersTagTypes = ['@alpha', '@beta', '@experimental'] as const
 
-const externalLinkRegex = /^(http|ftp)s?:\/\//
-
 export class StarlightTypeDocTheme extends MarkdownTheme {
   override getRenderContext(event: PageEvent<Reflection>) {
     return new StarlightTypeDocThemeRenderContext(event, this.application.options)
@@ -26,27 +21,10 @@ class StarlightTypeDocThemeRenderContext extends MarkdownThemeRenderContext {
   }
 
   override relativeURL: (url: string | undefined) => string | null = (url) => {
-    if (!url) {
-      return null
-    } else if (externalLinkRegex.test(url)) {
-      return url
-    }
+    const outputDirectory = this.options.getValue('starlight-typedoc-output')
+    const baseUrl = typeof outputDirectory === 'string' ? outputDirectory : ''
 
-    const filePath = path.parse(url)
-    const [, anchor] = filePath.base.split('#')
-    const segments = filePath.dir
-      .split('/')
-      .map((segment) => slug(segment))
-      .filter((segment) => segment !== '')
-    const baseUrl = this.options.getValue('starlight-typedoc-output')
-
-    let constructedUrl = typeof baseUrl === 'string' ? baseUrl : ''
-    constructedUrl += segments.length > 0 ? `${segments.join('/')}/` : ''
-    constructedUrl += slug(filePath.name)
-    constructedUrl += '/'
-    constructedUrl += anchor && anchor.length > 0 ? `#${anchor}` : ''
-
-    return constructedUrl
+    return getRelativeURL(url, baseUrl)
   }
 
   override comment: (

packages/starlight-typedoc/libs/typedoc.ts

@@ -15,6 +15,7 @@ import type { StarlightTypeDocOptions } from '..'
 
 import { StarlightTypeDocLogger } from './logger'
 import { addFrontmatter } from './markdown'
+import { getStarlightTypeDocOutputDirectory } from './starlight'
 import { StarlightTypeDocTheme } from './theme'
 
 const defaultTypeDocConfig: TypeDocConfig = {
@@ -92,7 +93,7 @@ async function bootstrapApp(
     onRendererPageEnd(event, pagination)
   })
   app.options.addDeclaration({
-    defaultValue: path.posix.join(base, `/${outputDirectory}${outputDirectory.endsWith('/') ? '' : '/'}`),
+    defaultValue: getStarlightTypeDocOutputDirectory(outputDirectory, base),
     help: 'The starlight-typedoc output directory containing the generated documentation markdown files relative to the `src/content/docs/` directory.',
     name: 'starlight-typedoc-output',
     type: ParameterType.String,

packages/starlight-typedoc/tests/e2e/basics/sidebar.test.ts

@@ -41,6 +41,11 @@ test('should generate the proper items for for a single entry point', async ({ d
   const items = await docPage.getTypeDocSidebarItems()
 
   expect(items).toMatchObject([
+    {
+      label: 'References',
+      items: [{ name: 'doThingARef' }],
+      collapsed: true,
+    },
     {
       label: 'Enumerations',
       items: [{ name: 'ANumericEnum' }, { name: 'AStringEnum' }],