fix: page and link generation issue with empty slugs (#80)

Author: HiDeoo

.changeset/khaki-countries-sneeze.md

@@ -0,0 +1,5 @@
+---
+'starlight-typedoc': patch
+---
+
+Fixes a potential page and link generation issue with some declaration reference names such as a function named `$`.

fixtures/basics/src/functions.ts

@@ -29,3 +29,10 @@ export function doThingC() {
 export function doThingFaster() {
   return 'thingB'
 }
+
+/**
+ * A function that print dollars.
+ */
+export function $() {
+  return '$'
+}

packages/starlight-typedoc/libs/starlight.ts

@@ -273,7 +273,8 @@ export function getRelativeURL(url: string, baseUrl: string, pageUrl?: string):
 
   let constructedUrl = typeof baseUrl === 'string' ? baseUrl : ''
   constructedUrl += segments.length > 0 ? `${segments.join('/')}/` : ''
-  constructedUrl += slug(filePath.name)
+  const fileNameSlug = slug(filePath.name)
+  constructedUrl += fileNameSlug || filePath.name
   constructedUrl += '/'
   constructedUrl += anchor && anchor.length > 0 ? `#${anchor}` : ''
 

packages/starlight-typedoc/libs/typedoc.ts

@@ -3,6 +3,7 @@ import path from 'node:path'
 import url from 'node:url'
 
 import type { AstroConfig, AstroIntegrationLogger } from 'astro'
+import { slug } from 'github-slugger'
 import {
   Application,
   PageEvent,
@@ -18,7 +19,7 @@ import type { StarlightTypeDocOptions } from '..'
 
 import { StarlightTypeDocLogger } from './logger'
 import { addFrontmatter } from './markdown'
-import { getStarlightTypeDocOutputDirectory } from './starlight'
+import { getRelativeURL, getStarlightTypeDocOutputDirectory } from './starlight'
 import { StarlightTypeDocTheme } from './theme'
 
 const defaultTypeDocConfig: TypeDocConfig = {
@@ -91,6 +92,7 @@ async function bootstrapApp(
   logger: AstroIntegrationLogger,
 ) {
   const pagesToRemove: string[] = []
+  const outputDirectory = getStarlightTypeDocOutputDirectory(output.directory, output.base)
 
   const app = await Application.bootstrapWithPlugins({
     ...defaultTypeDocConfig,
@@ -106,10 +108,10 @@ async function bootstrapApp(
   app.options.addReader(new TSConfigReader())
   app.renderer.defineTheme('starlight-typedoc', StarlightTypeDocTheme)
   app.renderer.on(PageEvent.BEGIN, (event) => {
-    onRendererPageBegin(event as MarkdownPageEvent, pagination)
+    onRendererPageBegin(event as MarkdownPageEvent, outputDirectory, pagination)
   })
   app.renderer.on(PageEvent.END, (event) => {
-    const shouldRemovePage = onRendererPageEnd(event as MarkdownPageEvent, pagination)
+    const shouldRemovePage = onRendererPageEnd(event as MarkdownPageEvent, outputDirectory, pagination)
     if (shouldRemovePage) {
       pagesToRemove.push(event.filename)
     }
@@ -118,7 +120,7 @@ async function bootstrapApp(
     onRendererEnd(pagesToRemove)
   })
   app.options.addDeclaration({
-    defaultValue: getStarlightTypeDocOutputDirectory(output.directory, output.base),
+    defaultValue: outputDirectory,
     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,
@@ -127,17 +129,20 @@ async function bootstrapApp(
   return app
 }
 
-function onRendererPageBegin(event: MarkdownPageEvent, pagination: boolean) {
+function onRendererPageBegin(event: MarkdownPageEvent, outputDirectory: string, pagination: boolean) {
   if (event.frontmatter) {
-    event.frontmatter['editUrl'] = false
-    event.frontmatter['next'] = pagination
-    event.frontmatter['prev'] = pagination
-    event.frontmatter['title'] = event.model.name
+    event.frontmatter = getModelFrontmatter(event, outputDirectory, {
+      ...event.frontmatter,
+      editUrl: false,
+      next: pagination,
+      prev: pagination,
+      title: event.model.name,
+    })
   }
 }
 
 // Returning `true` will delete the page from the filesystem.
-function onRendererPageEnd(event: MarkdownPageEvent, pagination: boolean) {
+function onRendererPageEnd(event: MarkdownPageEvent, outputDirectory: string, pagination: boolean) {
   if (!event.contents) {
     return false
   } else if (/^.+[/\\]README\.md$/.test(event.url)) {
@@ -149,13 +154,16 @@ function onRendererPageEnd(event: MarkdownPageEvent, pagination: boolean) {
   }
 
   if (!event.frontmatter) {
-    event.contents = addFrontmatter(event.contents, {
-      editUrl: false,
-      next: pagination,
-      prev: pagination,
-      // Wrap in quotes to prevent issue with special characters in frontmatter
-      title: `"${event.model.name}"`,
-    })
+    event.contents = addFrontmatter(
+      event.contents,
+      getModelFrontmatter(event, outputDirectory, {
+        editUrl: false,
+        next: pagination,
+        prev: pagination,
+        // Wrap in quotes to prevent issue with special characters in frontmatter
+        title: `"${event.model.name}"`,
+      }),
+    )
   }
 
   return false
@@ -167,6 +175,20 @@ function onRendererEnd(pagesToRemove: string[]) {
   }
 }
 
+function getModelFrontmatter(
+  event: MarkdownPageEvent,
+  outputDirectory: string,
+  frontmatter: NonNullable<MarkdownPageEvent['frontmatter']>,
+) {
+  const defaultSlug = slug(event.model.name)
+
+  if (defaultSlug.length === 0) {
+    frontmatter['slug'] = getRelativeURL(event.url, outputDirectory, event.url).replaceAll(/^\/|\/$/g, '')
+  }
+
+  return frontmatter
+}
+
 export class NoReflectionsError extends Error {
   constructor() {
     super('Failed to generate TypeDoc documentation.')

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

@@ -68,7 +68,13 @@ test('should generate the proper items for for a single entry point', async ({ d
     },
     {
       label: 'Functions',
-      items: [{ name: 'doThingA' }, { name: 'doThingB' }, { name: 'doThingC' }, { name: 'doThingFaster' }],
+      items: [
+        { name: '$' },
+        { name: 'doThingA' },
+        { name: 'doThingB' },
+        { name: 'doThingC' },
+        { name: 'doThingFaster' },
+      ],
       collapsed: true,
     },
     {

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

@@ -0,0 +1,8 @@
+import { expect, test } from '../test'
+
+test('handles pages with a name that would lead to an empty slug', async ({ docPage }) => {
+  await docPage.goto('functions/$')
+
+  await expect(docPage.content.getByText('A function that print dollars.')).toBeVisible()
+  expect(await docPage.sidebar.locator('a[aria-current="page"]').getAttribute('href')).toBe('/api/functions/$/')
+})

packages/starlight-typedoc/tests/e2e/fixtures/DocPage.ts

@@ -41,7 +41,7 @@ export class DocPage {
     return this.page.getByRole('main')
   }
 
-  get #sidebar() {
+  get sidebar() {
     return this.page.getByRole('navigation', { name: 'Main' })
   }
 
@@ -56,7 +56,7 @@ export class DocPage {
   }
 
   get #typeDocSidebarRootDetails() {
-    return this.#sidebar
+    return this.sidebar
       .getByRole('listitem')
       .locator(`details:has(summary > div > span:has-text("${this.#expectedTypeDocSidebarLabel}"))`)
   }
@@ -66,7 +66,7 @@ export class DocPage {
   }
 
   async getSidebarItems() {
-    return this.#getTypeDocSidebarChildrenItems(this.#sidebar.locator('ul.top-level'))
+    return this.#getTypeDocSidebarChildrenItems(this.sidebar.locator('ul.top-level'))
   }
 
   async #getTypeDocSidebarChildrenItems(list: Locator): Promise<TypeDocSidebarItem[]> {