Add support for Astro 5 (#66)

2026-05-01 11:05:15 +00:00 · 2024-12-17 09:46:45 +01:00
parent 0cac9855f3
commit c4014bc266
35 changed files with 2715 additions and 2392 deletions
--- a/.changeset/short-kangaroos-pay.md
+++ b/.changeset/short-kangaroos-pay.md
@@ -0,0 +1,9 @@
+---
+'starlight-typedoc': minor
+---
+
+Adds support for Astro v5, drops support for Astro v4.
+
+⚠️ **BREAKING CHANGE:** The minimum supported version of Starlight is now `0.30.0`.
+
+Please follow the [upgrade guide](https://github.com/withastro/starlight/releases/tag/%40astrojs/starlight%400.30.0) to update your project.
--- a/.eslintrc.json
+++ b/.eslintrc.json
@@ -1,3 +0,0 @@
-{
-  "extends": ["@hideoo"]
-}
--- a/.gitignore
+++ b/.gitignore
@@ -19,6 +19,7 @@
 build
 coverage
 dist
+dist-multiple-entrypoints
 dist-ssr
 lerna-debug.log*
 logs
--- a/.node-version
+++ b/.node-version
@@ -1 +1 @@
-v18.14.1
+v18.17.1
--- a/.prettierignore
+++ b/.prettierignore
@@ -11,4 +11,4 @@ dist
 dist-ssr
 out
 pnpm-lock.yaml
-src/content/docs/api*
+example/src/content/docs/api*
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -0,0 +1,13 @@
+{
+  "eslint.useFlatConfig": true,
+  "eslint.validate": [
+    "javascript",
+    "javascriptreact",
+    "typescript",
+    "typescriptreact",
+    "html",
+    "vue",
+    "markdown",
+    "astro"
+  ]
+}
--- a/docs/.prettierignore
+++ b/docs/.prettierignore
@@ -1,13 +0,0 @@
-.astro
-.github/blocks
-.next
-.vercel
-.vscode-test
-.vscode-test-web
-build
-coverage
-dist
-dist-ssr
-out
-pnpm-lock.yaml
-src/content/docs/api*
--- a/docs/package.json
+++ b/docs/package.json
@@ -10,17 +10,16 @@
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro",
-    "lint": "eslint . --cache --max-warnings=0",
-    "format": "prettier -w --cache --ignore-unknown ."
+    "lint": "eslint . --cache --max-warnings=0"
  },
  "dependencies": {
-    "@astrojs/starlight": "0.25.0",
-    "@hideoo/starlight-plugins-docs-components": "^0.2.2",
-    "astro": "4.16.10",
-    "sharp": "0.32.6"
+    "@astrojs/starlight": "^0.30.2",
+    "@hideoo/starlight-plugins-docs-components": "^0.3.0",
+    "astro": "^5.0.5",
+    "sharp": "^0.33.5"
  },
  "engines": {
-    "node": ">=18.14.1"
+    "node": ">=18.17.1"
  },
  "packageManager": "pnpm@8.6.3",
  "private": true,
@@ -36,7 +35,8 @@
  "homepage": "https://github.com/HiDeoo/starlight-typedoc",
  "repository": {
    "type": "git",
-    "url": "https://github.com/HiDeoo/starlight-typedoc.git"
+    "url": "https://github.com/HiDeoo/starlight-typedoc.git",
+    "directory": "docs"
  },
  "bugs": "https://github.com/HiDeoo/starlight-typedoc/issues"
 }
--- a/docs/src/content.config.ts
+++ b/docs/src/content.config.ts
@@ -0,0 +1,7 @@
+import { docsLoader } from '@astrojs/starlight/loaders'
+import { docsSchema } from '@astrojs/starlight/schema'
+import { defineCollection } from 'astro:content'
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+}
--- a/docs/src/content/config.ts
+++ b/docs/src/content/config.ts
@@ -1,7 +0,0 @@
-import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'
-import { defineCollection } from 'astro:content'
-
-export const collections = {
-  docs: defineCollection({ schema: docsSchema() }),
-  i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
-}
--- a/docs/src/content/docs/index.mdx
+++ b/docs/src/content/docs/index.mdx
@@ -15,10 +15,10 @@ hero:
    - text: Getting Started
      link: /getting-started/
      icon: rocket
-      variant: primary
    - text: Demo
      link: https://starlight-typedoc-example.vercel.app/api/functions/dothingc/
      icon: external
+      variant: minimal
 ---

 import { Card, CardGrid } from '@astrojs/starlight/components'
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -0,0 +1,3 @@
+import hideoo from '@hideoo/eslint-config'
+
+export default hideoo()
--- a/example/.prettierignore
+++ b/example/.prettierignore
@@ -1 +0,0 @@
-../.prettierignore
--- a/example/.vscode/extensions.json
+++ b/example/.vscode/extensions.json
@@ -1,4 +0,0 @@
-{
-  "recommendations": ["astro-build.astro-vscode"],
-  "unwantedRecommendations": []
-}
--- a/example/.vscode/launch.json
+++ b/example/.vscode/launch.json
@@ -1,11 +0,0 @@
-{
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "command": "./node_modules/.bin/astro dev",
-      "name": "Development server",
-      "request": "launch",
-      "type": "node-terminal"
-    }
-  ]
-}
--- a/example/astro.multiple-entrypoints.config.ts
+++ b/example/astro.multiple-entrypoints.config.ts
@@ -32,6 +32,7 @@ export default defineConfig({
      title: 'Starlight TypeDoc Multiple Entry Points Example',
    }),
  ],
+  outDir: './dist-multiple-entrypoints',
  server: {
    port: 4322,
  },
--- a/example/package.json
+++ b/example/package.json
@@ -11,25 +11,31 @@
    "dev:multiple-entrypoints": "astro dev --config astro.multiple-entrypoints.config.ts",
    "dev:packages-entrypoints": "pnpm -C ../fixtures/packages run build && astro dev --config astro.packages-entrypoints.config.ts",
    "dev:multiple-plugins": "astro dev --config astro.multiple-plugins.config.ts",
-    "start": "astro dev",
    "build": "astro build",
+    "build:single-entrypoints": "astro build --config astro.config.ts",
+    "build:multiple-entrypoints": "astro build --config astro.multiple-entrypoints.config.ts",
+    "build:packages-entrypoints": "pnpm -C ../fixtures/packages run build && astro build --config astro.packages-entrypoints.config.ts",
+    "build:multiple-plugins": "astro build --config astro.multiple-plugins.config.ts",
    "preview": "astro preview",
+    "preview:single-entrypoints": "astro preview --config astro.config.ts",
+    "preview:multiple-entrypoints": "astro preview --config astro.multiple-entrypoints.config.ts",
+    "preview:packages-entrypoints": "astro preview --config astro.packages-entrypoints.config.ts",
+    "preview:multiple-plugins": "astro preview --config astro.multiple-plugins.config.ts",
    "astro": "astro",
-    "lint": "eslint . --cache --max-warnings=0",
-    "format": "prettier -w --cache --ignore-unknown ."
+    "lint": "eslint . --cache --max-warnings=0"
  },
  "dependencies": {
-    "@astrojs/starlight": "0.25.0",
-    "astro": "4.16.10",
-    "sharp": "0.32.6",
+    "@astrojs/starlight": "^0.30.2",
+    "astro": "^5.0.5",
+    "sharp": "^0.33.5",
    "starlight-typedoc": "workspace:*",
-    "typedoc": "0.26.5",
-    "typedoc-plugin-frontmatter": "1.0.0",
-    "typedoc-plugin-markdown": "4.1.1",
-    "typedoc-plugin-mdn-links": "3.0.3"
+    "typedoc": "^0.26.5",
+    "typedoc-plugin-frontmatter": "^1.0.0",
+    "typedoc-plugin-markdown": "^4.1.1",
+    "typedoc-plugin-mdn-links": "^3.0.3"
  },
  "engines": {
-    "node": ">=18.14.1"
+    "node": ">=18.17.1"
  },
  "packageManager": "pnpm@8.6.1",
  "private": true,
@@ -45,7 +51,8 @@
  "homepage": "https://github.com/HiDeoo/starlight-typedoc",
  "repository": {
    "type": "git",
-    "url": "https://github.com/HiDeoo/starlight-typedoc.git"
+    "url": "https://github.com/HiDeoo/starlight-typedoc.git",
+    "directory": "example"
  },
  "bugs": "https://github.com/HiDeoo/starlight-typedoc/issues"
 }
--- a/example/src/content.config.ts
+++ b/example/src/content.config.ts
@@ -1,8 +1,10 @@
-import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'
+import { docsLoader } from '@astrojs/starlight/loaders'
+import { docsSchema } from '@astrojs/starlight/schema'
 import { defineCollection, z } from 'astro:content'

 export const collections = {
  docs: defineCollection({
+    loader: docsLoader(),
    schema: docsSchema({
      extend: z.object({
        banner: z
@@ -16,5 +18,4 @@ export const collections = {
      }),
    }),
  }),
-  i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
 }
--- a/example/src/content/docs/index.mdx
+++ b/example/src/content/docs/index.mdx
@@ -14,11 +14,11 @@ hero:
  actions:
    - text: Check Example
      link: /api/functions/dothingc/
-      icon: right-arrow
-      variant: primary
+      icon: rocket
    - text: Documentation
      link: https://starlight-typedoc.vercel.app/
      icon: external
+      variant: minimal
 ---

 import { Card, CardGrid } from '@astrojs/starlight/components'
--- a/fixtures/basics/package.json
+++ b/fixtures/basics/package.json
@@ -6,10 +6,10 @@
  "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",
  "type": "module",
  "dependencies": {
-    "typescript": "5.1.6"
+    "typescript": "^5.7.2"
  },
  "engines": {
-    "node": ">=18.14.1"
+    "node": ">=18.17.1"
  },
  "packageManager": "pnpm@8.6.1",
  "private": true,
@@ -25,7 +25,8 @@
  "homepage": "https://github.com/HiDeoo/starlight-typedoc",
  "repository": {
    "type": "git",
-    "url": "https://github.com/HiDeoo/starlight-typedoc.git"
+    "url": "https://github.com/HiDeoo/starlight-typedoc.git",
+    "directory": "fixtures/basics"
  },
  "bugs": "https://github.com/HiDeoo/starlight-typedoc/issues"
 }
--- a/fixtures/basics/tsconfig.json
+++ b/fixtures/basics/tsconfig.json
@@ -1,3 +1,3 @@
 {
-  "extends": "../../tsconfig.json"
+  "extends": "@hideoo/tsconfig"
 }
--- a/fixtures/packages/package.json
+++ b/fixtures/packages/package.json
@@ -9,10 +9,10 @@
    "build": "tsc --build"
  },
  "dependencies": {
-    "typescript": "5.1.6"
+    "typescript": "^5.7.2"
  },
  "engines": {
-    "node": ">=18.14.1"
+    "node": ">=18.17.1"
  },
  "packageManager": "pnpm@8.6.1",
  "private": true,
@@ -28,7 +28,8 @@
  "homepage": "https://github.com/HiDeoo/starlight-typedoc",
  "repository": {
    "type": "git",
-    "url": "https://github.com/HiDeoo/starlight-typedoc.git"
+    "url": "https://github.com/HiDeoo/starlight-typedoc.git",
+    "directory": "fixtures/packages"
  },
  "bugs": "https://github.com/HiDeoo/starlight-typedoc/issues"
 }
--- a/package.json
+++ b/package.json
@@ -7,28 +7,30 @@
  "type": "module",
  "scripts": {
    "test": "pnpm --stream -r test",
-    "lint": "pnpm -r lint",
-    "format": "pnpm -r format",
+    "lint": "astro check --noSync && pnpm -r lint",
+    "format": "prettier -w --cache --ignore-unknown .",
    "version": "pnpm changeset version && pnpm i --no-frozen-lockfile"
  },
  "devDependencies": {
-    "@changesets/changelog-github": "0.5.0",
-    "@changesets/cli": "2.27.10",
-    "@hideoo/eslint-config": "2.0.1",
-    "@hideoo/prettier-config": "2.0.0",
-    "@hideoo/tsconfig": "2.0.1",
-    "eslint": "8.48.0",
-    "prettier": "3.0.3",
-    "typescript": "5.1.6"
+    "@astrojs/check": "^0.9.4",
+    "@changesets/changelog-github": "^0.5.0",
+    "@changesets/cli": "^2.27.10",
+    "@hideoo/eslint-config": "^4.0.0",
+    "@hideoo/prettier-config": "^2.0.0",
+    "@hideoo/tsconfig": "^2.0.1",
+    "astro": "^5.0.5",
+    "eslint": "^9.17.0",
+    "prettier": "^3.4.2",
+    "typescript": "^5.7.2"
  },
  "engines": {
-    "node": ">=18.14.1"
+    "node": ">=18.17.1"
  },
  "packageManager": "pnpm@8.6.1",
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": {
-        "typescript": "5.1.6"
+        "typescript": "5.7.2"
      }
    }
  },
--- a/packages/starlight-typedoc/.npmignore
+++ b/packages/starlight-typedoc/.npmignore
@@ -1,5 +1,5 @@
 .eslintcache
+eslint.config.mjs
 playwright.config.ts
 tests
-tsconfig.json
 vitest.config.ts
--- a/packages/starlight-typedoc/.prettierignore
+++ b/packages/starlight-typedoc/.prettierignore
@@ -1 +0,0 @@
-../../.prettierignore
--- a/packages/starlight-typedoc/eslint.config.mjs
+++ b/packages/starlight-typedoc/eslint.config.mjs
@@ -0,0 +1,10 @@
+import hideoo from '@hideoo/eslint-config'
+
+export default hideoo({
+  ignores: ['eslint.config.mjs'],
+  languageOptions: {
+    parserOptions: {
+      project: ['../../tsconfig.json'],
+    },
+  },
+})
--- a/packages/starlight-typedoc/index.ts
+++ b/packages/starlight-typedoc/index.ts
@@ -23,7 +23,9 @@ function makeStarlightTypeDocPlugin(sidebarGroup: SidebarGroup): (options: Starl
    return {
      name: 'starlight-typedoc-plugin',
      hooks: {
-        async setup({ astroConfig, config, logger, updateConfig }) {
+        async setup({ astroConfig, command, config, logger, updateConfig }) {
+          if (command === 'preview') return
+
          const { outputDirectory, reflections } = await generateTypeDoc(options, astroConfig, logger)
          const sidebar = getSidebarFromReflections(
            config.sidebar,
--- a/packages/starlight-typedoc/libs/theme.ts
+++ b/packages/starlight-typedoc/libs/theme.ts
@@ -1,14 +1,7 @@
 import path from 'node:path'

-import {
-  Reflection,
-  type Comment,
-  type CommentTag,
-  type Options,
-  type PageEvent,
-  type CommentDisplayPart,
-} from 'typedoc'
-import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown'
+import { Reflection, type Comment, type CommentTag, type Options, type CommentDisplayPart } from 'typedoc'
+import { MarkdownTheme, MarkdownThemeContext, type MarkdownPageEvent } from 'typedoc-plugin-markdown'

 import { getAsideMarkdown, getRelativeURL } from './starlight'

@@ -16,7 +9,7 @@ const customBlockTagTypes = ['@deprecated'] as const
 const customModifiersTagTypes = ['@alpha', '@beta', '@experimental'] as const

 export class StarlightTypeDocTheme extends MarkdownTheme {
-  override getRenderContext(event: PageEvent<Reflection>): StarlightTypeDocThemeRenderContext {
+  override getRenderContext(event: MarkdownPageEvent): StarlightTypeDocThemeRenderContext {
    return new StarlightTypeDocThemeRenderContext(this, event, this.application.options)
  }
 }
@@ -24,7 +17,7 @@ export class StarlightTypeDocTheme extends MarkdownTheme {
 class StarlightTypeDocThemeRenderContext extends MarkdownThemeContext {
  #markdownThemeContext: MarkdownThemeContext

-  constructor(theme: MarkdownTheme, event: PageEvent<Reflection>, options: Options) {
+  constructor(theme: MarkdownTheme, event: MarkdownPageEvent, options: Options) {
    super(theme, event, options)

    this.#markdownThemeContext = new MarkdownThemeContext(theme, event, options)
--- a/packages/starlight-typedoc/package.json
+++ b/packages/starlight-typedoc/package.json
@@ -20,28 +20,25 @@
    "test:e2e:packages": "cross-env TEST_TYPE=packages pnpm run playwright",
    "test:e2e:plugins": "cross-env TEST_TYPE=plugins pnpm run playwright",
    "playwright": "playwright install --with-deps chromium && playwright test",
-    "lint": "eslint . --cache --max-warnings=0",
-    "format": "prettier -w --cache --ignore-unknown ."
+    "lint": "eslint . --cache --max-warnings=0"
  },
  "dependencies": {
-    "github-slugger": "2.0.0"
+    "github-slugger": "^2.0.0"
  },
  "devDependencies": {
-    "@astrojs/starlight": "0.25.0",
-    "@playwright/test": "1.35.0",
-    "@types/node": "18.16.16",
-    "astro": "4.16.10",
-    "cross-env": "7.0.3",
-    "typescript": "5.1.6",
-    "vitest": "1.0.4"
+    "@playwright/test": "^1.49.1",
+    "@types/node": "^18.19.68",
+    "cross-env": "^7.0.3",
+    "typescript": "^5.7.2",
+    "vitest": "2.1.6"
  },
  "peerDependencies": {
-    "@astrojs/starlight": ">=0.25.0",
+    "@astrojs/starlight": ">=0.30.0",
    "typedoc": ">=0.26.5",
    "typedoc-plugin-markdown": ">=4.1.1"
  },
  "engines": {
-    "node": ">=18.14.1"
+    "node": ">=18.17.1"
  },
  "packageManager": "pnpm@8.6.1",
  "publishConfig": {
@@ -60,7 +57,8 @@
  "homepage": "https://github.com/HiDeoo/starlight-typedoc",
  "repository": {
    "type": "git",
-    "url": "https://github.com/HiDeoo/starlight-typedoc.git"
+    "url": "https://github.com/HiDeoo/starlight-typedoc.git",
+    "directory": "packages/starlight-typedoc"
  },
  "bugs": "https://github.com/HiDeoo/starlight-typedoc/issues"
 }
--- a/packages/starlight-typedoc/playwright.config.ts
+++ b/packages/starlight-typedoc/playwright.config.ts
@@ -13,33 +13,33 @@ export default defineConfig({
    process.env['TEST_TYPE'] === 'basics'
      ? [
          {
-            command: 'pnpm run dev:single-entrypoints',
+            command: 'pnpm build:single-entrypoints && pnpm preview:single-entrypoints',
            cwd: '../../example',
            reuseExistingServer: !process.env['CI'],
            url: 'http://localhost:4321',
          },
          {
-            command: 'pnpm run dev:multiple-entrypoints',
+            command: 'pnpm build:multiple-entrypoints && pnpm preview:multiple-entrypoints',
            cwd: '../../example',
            reuseExistingServer: !process.env['CI'],
            url: 'http://localhost:4322/multiple-entrypoints/',
          },
        ]
      : process.env['TEST_TYPE'] === 'plugins'
-      ? [
-          {
-            command: 'pnpm run dev:multiple-plugins',
-            cwd: '../../example',
-            reuseExistingServer: !process.env['CI'],
-            url: 'http://localhost:4321/multiple-plugins/',
-          },
-        ]
-      : [
-          {
-            command: 'pnpm run dev:packages-entrypoints',
-            cwd: '../../example',
-            reuseExistingServer: !process.env['CI'],
-            url: 'http://localhost:4321/packages-entrypoints/',
-          },
-        ],
+        ? [
+            {
+              command: 'pnpm build:multiple-plugins && pnpm preview:multiple-plugins',
+              cwd: '../../example',
+              reuseExistingServer: !process.env['CI'],
+              url: 'http://localhost:4321/multiple-plugins/',
+            },
+          ]
+        : [
+            {
+              command: 'pnpm build:packages-entrypoints && pnpm preview:packages-entrypoints',
+              cwd: '../../example',
+              reuseExistingServer: !process.env['CI'],
+              url: 'http://localhost:4321/packages-entrypoints/',
+            },
+          ],
 })
--- a/packages/starlight-typedoc/tests/e2e/fixtures/DocPage.ts
+++ b/packages/starlight-typedoc/tests/e2e/fixtures/DocPage.ts
@@ -13,10 +13,10 @@ export class DocPage {
    const baseDir = this.#useMultipleEntryPoints
      ? 'multiple-entrypoints/api-multiple-entrypoints'
      : this.#usePackagesEntryPoints
-      ? 'packages-entrypoints/api-packages-entrypoints'
-      : this.#useMultiplePlugins
-      ? 'multiple-plugins'
-      : 'api'
+        ? 'packages-entrypoints/api-packages-entrypoints'
+        : this.#useMultiplePlugins
+          ? 'multiple-plugins'
+          : 'api'
    const baseUrl = `http://localhost:${this.#useMultipleEntryPoints ? 4322 : 4321}/${baseDir}`

    await this.page.goto(`${baseUrl}${url.startsWith('/') ? url : `/${url}`}${url.endsWith('/') ? '' : '/'}`)
--- a/packages/starlight-typedoc/tests/unit/typedoc.test.ts
+++ b/packages/starlight-typedoc/tests/unit/typedoc.test.ts
@@ -199,6 +199,9 @@ function generateTestTypeDoc(
      info() {
        // noop
      },
+      warn() {
+        // noop
+      },
    } as unknown as AstroIntegrationLogger,
  )
 }
--- a/packages/starlight-typedoc/tsconfig.json
+++ b/packages/starlight-typedoc/tsconfig.json
@@ -1,6 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "incremental": false
-  }
-}
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,3 +1,4 @@
 {
-  "extends": "@hideoo/tsconfig"
+  "extends": "@hideoo/tsconfig",
+  "include": ["docs/.astro/types.d.ts", "**/*"]
 }