feat!: bump minimum required typedoc-plugin-markdown version to `4.…

…0.0`

docs/src/content/docs/getting-started.mdx

@@ -16,11 +16,7 @@ import { PackageManagers } from '@hideoo/starlight-plugins-docs-components'
 
 1. Starlight TypeDoc is a Starlight [plugin](https://starlight.astro.build/reference/plugins/). Install it and its peer dependencies using your favorite package manager:
 
-   <PackageManagers pkg="starlight-typedoc typedoc typedoc-plugin-markdown@next" />
-
-   :::note
-   The Starlight TypeDoc package requires at least the version `4.0.0-next.59` of `typedoc-plugin-markdown`, hence the `@next` tag in the installation command.
-   :::
+   <PackageManagers pkg="starlight-typedoc typedoc typedoc-plugin-markdown" />
 
 2. Configure the plugin in your Starlight [configuration](https://starlight.astro.build/reference/configuration/#plugins) in the `astro.config.mjs` file.
 

example/package.json

@@ -22,8 +22,8 @@
     "astro": "4.11.1",
     "sharp": "0.32.6",
     "starlight-typedoc": "workspace:*",
-    "typedoc": "0.25",
-    "typedoc-plugin-markdown": "4.0.0-next.59",
+    "typedoc": "0.26.2",
+    "typedoc-plugin-markdown": "4.1.0",
     "typedoc-plugin-mdn-links": "3.0.3"
   },
   "engines": {

packages/starlight-typedoc/libs/typedoc.ts

@@ -1,13 +1,15 @@
+import fs from 'node:fs'
 import path from 'node:path'
 
 import type { AstroIntegrationLogger } from 'astro'
 import {
   Application,
-  type DeclarationReflection,
   PageEvent,
   TSConfigReader,
   type TypeDocOptions,
   ParameterType,
+  type Reflection,
+  RendererEvent,
 } from 'typedoc'
 import type { PluginOptions } from 'typedoc-plugin-markdown'
 
@@ -76,6 +78,8 @@ async function bootstrapApp(
   base: string,
   logger: AstroIntegrationLogger,
 ) {
+  const pagesToRemove: string[] = []
+
   const app = await Application.bootstrapWithPlugins({
     ...defaultTypeDocConfig,
     ...markdownPluginConfig,
@@ -87,10 +91,15 @@ async function bootstrapApp(
   })
   app.logger = new StarlightTypeDocLogger(logger)
   app.options.addReader(new TSConfigReader())
-  // @ts-expect-error - Invalid theme typing
   app.renderer.defineTheme('starlight-typedoc', StarlightTypeDocTheme)
-  app.renderer.on(PageEvent.END, (event: PageEvent<DeclarationReflection>) => {
-    onRendererPageEnd(event, pagination)
+  app.renderer.on(PageEvent.END, (event: PageEvent<Reflection>) => {
+    const shouldRemovePage = onRendererPageEnd(event, pagination)
+    if (shouldRemovePage) {
+      pagesToRemove.push(event.filename)
+    }
+  })
+  app.renderer.on(RendererEvent.END, () => {
+    onRendererEnd(pagesToRemove)
   })
   app.options.addDeclaration({
     defaultValue: getStarlightTypeDocOutputDirectory(outputDirectory, base),
@@ -102,13 +111,16 @@ async function bootstrapApp(
   return app
 }
 
-function onRendererPageEnd(event: PageEvent<DeclarationReflection>, pagination: boolean) {
+// Returning `true` will delete the page from the filesystem.
+function onRendererPageEnd(event: PageEvent<Reflection>, pagination: boolean) {
   if (!event.contents) {
-    return
+    return false
   } else if (/^.+[/\\]README\.md$/.test(event.url)) {
     // Do not save `README.md` files for multiple entry points.
-    event.preventDefault()
-    return
+    // It is no longer supported in TypeDoc 0.26.0 to call `event.preventDefault()` to prevent the file from being saved.
+    // https://github.com/TypeStrong/typedoc/commit/6e6b3b662c92b3d4bc24b6c6c0c6e227e063c759
+    // event.preventDefault()
+    return true
   }
 
   event.contents = addFrontmatter(event.contents, {
@@ -118,6 +130,14 @@ function onRendererPageEnd(event: PageEvent<DeclarationReflection>, pagination:
     // Wrap in quotes to prevent issue with special characters in frontmatter
     title: `"${event.model.name}"`,
   })
+
+  return false
+}
+
+function onRendererEnd(pagesToRemove: string[]) {
+  for (const page of pagesToRemove) {
+    fs.rmSync(page, { force: true })
+  }
 }
 
 export type TypeDocConfig = Partial<Omit<TypeDocOptions, 'entryPoints' | 'tsconfig'> & PluginOptions>

packages/starlight-typedoc/package.json

@@ -37,8 +37,8 @@
   "peerDependencies": {
     "@astrojs/starlight": ">=0.15.0",
     "astro": ">=4.0.0",
-    "typedoc": ">=0.25.0",
-    "typedoc-plugin-markdown": ">=4.0.0-next.59"
+    "typedoc": ">=0.26.0",
+    "typedoc-plugin-markdown": ">=4.0.0"
   },
   "engines": {
     "node": ">=18.14.1"

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

@@ -65,7 +65,7 @@ test('should disable edit links', async ({ docPage }) => {
 test('should support TypeDoc plugins', async ({ docPage }) => {
   await docPage.goto('classes/foo')
 
-  const mdnLink = docPage.page.getByRole('link', { exact: true, name: 'HTMLElement ↗️' })
+  const mdnLink = docPage.page.getByRole('link', { exact: true, name: 'HTMLElement' })
 
   await expect(mdnLink).toBeVisible()
 

packages/starlight-typedoc/tests/unit/typedoc.test.ts

@@ -15,6 +15,7 @@ const starlightTypeDocOptions = {
 
 beforeAll(() => {
   vi.spyOn(fs, 'mkdirSync').mockReturnValue(undefined)
+  vi.spyOn(fs, 'rmSync').mockReturnValue(undefined)
   vi.spyOn(fs, 'writeFileSync').mockReturnValue(undefined)
 })
 
@@ -89,11 +90,11 @@ test('should not add `README.md` module files for multiple entry points', async
     entryPoints: ['../../fixtures/basics/src/Bar.ts', '../../fixtures/basics/src/Foo.ts'],
   })
 
-  const writeFileSyncSpy = vi.mocked(fs.writeFileSync)
-  const filePaths = writeFileSyncSpy.mock.calls.map((call) => call[0].toString())
+  const rmSyncSpy = vi.mocked(fs.rmSync)
+  const filePaths = rmSyncSpy.mock.calls.map((call) => call[0].toString())
 
-  expect(writeFileSyncSpy).toHaveBeenCalled()
-  expect(filePaths.some((filePath) => /\/(?:Bar|Foo)\/README\.md$/.test(filePath))).toBe(false)
+  expect(rmSyncSpy).toHaveBeenCalled()
+  expect(filePaths.filter((filePath) => /\/(?:Bar|Foo)\/README\.md$/.test(filePath)).length).toBe(2)
 })
 
 test('should support overriding typedoc-plugin-markdown readme page generation', async () => {