Merge pull request #100 from HiDeoo/hd-astro-5

.changeset/rude-lemons-battle.md

@@ -0,0 +1,13 @@
+---
+'starlight-blog': 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.
+
+Note that the [`legacy.collections` flag](https://docs.astro.build/en/reference/legacy-flags/#collections) is not supported by this plugin and you should update your collections to use Astro's new Content Layer API.
+
+⚠️ **BREAKING CHANGE:** The generated RSS feed no longer includes content of blog posts due to a [regression](https://github.com/withastro/astro/issues/12669) in Astro v5. The feature will be restored in a future release. If you rely on this feature, please stay on a previous version of Starlight and Astro in the meantime.

.node-version

@@ -1 +1 @@
-v18.14.1
+v18.17.1

.prettierignore

@@ -11,3 +11,4 @@ dist
 dist-ssr
 out
 pnpm-lock.yaml
+test-results

.vscode/settings.json

@@ -1,5 +1,5 @@
 {
-  "eslint.experimental.useFlatConfig": true,
+  "eslint.useFlatConfig": true,
   "eslint.validate": [
     "javascript",
     "javascriptreact",

docs/package.json

@@ -11,18 +11,17 @@
     "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.28.3",
-    "@hideoo/starlight-plugins-docs-components": "^0.2.2",
-    "astro": "4.16.4",
-    "sharp": "0.32.5",
+    "@astrojs/starlight": "^0.30.1",
+    "@hideoo/starlight-plugins-docs-components": "^0.3.0",
+    "astro": "^5.0.5",
+    "sharp": "^0.33.5",
     "starlight-blog": "workspace:*"
   },
   "engines": {
-    "node": ">=18.14.1"
+    "node": ">=18.17.1"
   },
   "packageManager": "pnpm@8.6.9",
   "private": true,
@@ -37,7 +36,8 @@
   "homepage": "https://github.com/HiDeoo/starlight-blog",
   "repository": {
     "type": "git",
-    "url": "https://github.com/HiDeoo/starlight-blog.git"
+    "url": "https://github.com/HiDeoo/starlight-blog.git",
+    "directory": "docs"
   },
   "bugs": "https://github.com/HiDeoo/starlight-blog/issues"
 }

docs/src/content/config.ts → docs/src/content.config.ts

@@ -1,12 +1,14 @@
+import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders'
 import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'
 import { defineCollection } from 'astro:content'
 import { blogSchema } from 'starlight-blog/schema'
 
 export const collections = {
   docs: defineCollection({
+    loader: docsLoader(),
     schema: docsSchema({
       extend: (context) => blogSchema(context),
     }),
   }),
-  i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
+  i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
 }

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

@@ -49,18 +49,20 @@ import { PackageManagers } from '@hideoo/starlight-plugins-docs-components'
    })
    ```
 
-3. Starlight Blog uses Astro’s [content collections](https://docs.astro.build/en/guides/content-collections/), which are configured in the `src/content/config.ts` file.
+3. Starlight Blog uses Astro’s [content collections](https://docs.astro.build/en/guides/content-collections/), which are configured in the `src/content.config.ts` file.
 
    Update the content config file to add support for customizing individual blog posts using their frontmatter:
 
    ```diff lang="ts"
-   // src/content/config.ts
+   // src/content.config.ts
    import { defineCollection } from 'astro:content';
+   import { docsLoader } from '@astrojs/starlight/loaders';
    import { docsSchema } from '@astrojs/starlight/schema';
    +import { blogSchema } from 'starlight-blog/schema'
 
    export const collections = {
      docs: defineCollection({
+       loader: docsLoader(),
        schema: docsSchema({
    +      extend: (context) => blogSchema(context)
        })

docs/src/content/docs/index.mdx

@@ -18,7 +18,7 @@ hero:
     - text: Demo
       link: /blog
       variant: minimal
-      icon: external
+      icon: right-arrow
 ---
 
 import { Card, CardGrid } from '@astrojs/starlight/components'

package.json

@@ -7,24 +7,25 @@
   "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": "3.0.0",
-    "@hideoo/prettier-config": "2.0.0",
-    "@hideoo/tsconfig": "2.0.1",
-    "astro": "4.16.4",
-    "eslint": "8.56.0",
-    "prettier": "3.0.3",
-    "prettier-plugin-astro": "0.12.0",
-    "typescript": "5.2.2"
+    "@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",
+    "prettier-plugin-astro": "^0.14.1",
+    "typescript": "^5.7.2"
   },
   "engines": {
-    "node": ">=18.14.1"
+    "node": ">=18.17.1"
   },
   "packageManager": "pnpm@8.6.9",
   "private": true,

packages/starlight-blog/.gitignore

@@ -1 +1,2 @@
 src
+test-results

packages/starlight-blog/.npmignore

@@ -1,7 +1,8 @@
 .eslintcache
-.prettierignore
+eslint.config.mjs
 playwright.config.ts
 src
+test-results
 tests
-tsconfig.json
-tsconfig.tsbuildinfo
+vitest.config.ts
+vitest.workspace.ts

packages/starlight-blog/components/Preview.astro

@@ -21,7 +21,7 @@ const Excerpt = await getBlogEntryExcerpt(entry)
 <article class="preview">
   <header>
     <h2>
-      <a href={getRelativeUrl(`/${getPathWithLocale(entry.slug, locale)}`)}>{entry.data.title}</a>
+      <a href={getRelativeUrl(`/${getPathWithLocale(entry.id, locale)}`)}>{entry.data.title}</a>
     </h2>
     <Metadata entry={entry} {locale} />
   </header>

packages/starlight-blog/env.d.ts

@@ -1,29 +1,3 @@
-declare module 'astro:content' {
-  export interface AstroCollectionEntry<TData> {
-    body: string
-    collection: string
-    data: TData
-    id: string
-    render: () => Promise<{
-      Content: import('astro').MarkdownInstance<object>['Content']
-    }>
-    slug: string
-  }
-
-  export function getCollection<TData>(
-    collection: string,
-    filter?: (entry: AstroCollectionEntry<TData>) => boolean,
-  ): Promise<AstroCollectionEntry<TData>[]>
-
-  export function getEntry<TData>(collection: string, slug: string): Promise<AstroCollectionEntry<TData>>
-}
-
-declare module 'astro:container' {
-  export function loadRenderers(
-    renderers: import('astro').AstroRenderer[],
-  ): Promise<import('astro').SSRLoadedRenderer[]>
-}
-
 declare namespace App {
   type StarlightLocals = import('@astrojs/starlight').StarlightLocals
   interface Locals extends StarlightLocals {}

packages/starlight-blog/eslint.config.mjs

@@ -0,0 +1,18 @@
+import hideoo from '@hideoo/eslint-config'
+
+export default hideoo(
+  {
+    ignores: ['eslint.config.mjs'],
+    languageOptions: {
+      parserOptions: {
+        project: ['../../tsconfig.json'],
+      },
+    },
+  },
+  {
+    files: ['**/*.d.ts'],
+    rules: {
+      '@typescript-eslint/no-empty-object-type': 'off',
+    },
+  },
+)

packages/starlight-blog/index.ts

@@ -98,7 +98,9 @@ export default function starlightBlogPlugin(userConfig?: StarlightBlogUserConfig
                   plugins: [
                     vitePluginStarlightBlogConfig(config, {
                       description: starlightConfig.description,
+                      rootDir: astroConfig.root.pathname,
                       site: astroConfig.site,
+                      srcDir: astroConfig.srcDir.pathname,
                       title: starlightConfig.title,
                       titleDelimiter: starlightConfig.titleDelimiter,
                       trailingSlash: astroConfig.trailingSlash,

packages/starlight-blog/libs/content.ts

@@ -1,10 +1,10 @@
 import type { GetStaticPathsResult } from 'astro'
-import type { z } from 'astro/zod'
-import { getCollection, getEntry, type AstroCollectionEntry } from 'astro:content'
+import { type CollectionEntry, getCollection, getEntry, render } from 'astro:content'
 import starlightConfig from 'virtual:starlight/user-config'
 import config from 'virtual:starlight-blog-config'
+import context from 'virtual:starlight-blog-context'
 
-import type { blogSchema, StarlightBlogAuthor } from '../schema'
+import type { StarlightBlogAuthor } from '../schema'
 
 import { getEntryAuthors } from './authors'
 import { DefaultLocale, getLangFromLocale, type Locale } from './i18n'
@@ -58,8 +58,8 @@ export async function getBlogEntry(slug: string, locale: Locale): Promise<Starli
   const entries = await getBlogEntries(locale)
 
   const entryIndex = entries.findIndex((entry) => {
-    if (entry.slug === stripLeadingSlash(stripTrailingSlash(slug))) return true
-    if (locale) return entry.slug === stripLeadingSlash(stripTrailingSlash(getPathWithLocale(slug, undefined)))
+    if (entry.id === stripLeadingSlash(stripTrailingSlash(slug))) return true
+    if (locale) return entry.id === stripLeadingSlash(stripTrailingSlash(getPathWithLocale(slug, undefined)))
     return false
   })
   const entry = entries[entryIndex]
@@ -72,12 +72,12 @@ export async function getBlogEntry(slug: string, locale: Locale): Promise<Starli
 
   const prevEntry = entries[entryIndex - 1]
   const prevLink = prevEntry
-    ? { href: getRelativeUrl(`/${getPathWithLocale(prevEntry.slug, locale)}`), label: prevEntry.data.title }
+    ? { href: getRelativeUrl(`/${getPathWithLocale(prevEntry.id, locale)}`), label: prevEntry.data.title }
     : undefined
 
   const nextEntry = entries[entryIndex + 1]
   const nextLink = nextEntry
-    ? { href: getRelativeUrl(`/${getPathWithLocale(nextEntry.slug, locale)}`), label: nextEntry.data.title }
+    ? { href: getRelativeUrl(`/${getPathWithLocale(nextEntry.id, locale)}`), label: nextEntry.data.title }
     : undefined
 
   return {
@@ -101,29 +101,42 @@ export function getBlogEntryMetadata(entry: StarlightBlogEntry, locale: Locale):
 }
 
 export async function getBlogEntries(locale: Locale) {
-  const docEntries = await getCollection<StarlightEntryData>('docs')
-  const blogEntries: AstroCollectionEntry<StarlightEntryData>[] = []
+  const docEntries = await getCollection('docs')
+  const blogEntries: StarlightEntry[] = []
+
+  const contentRelativePath = `${context.srcDir.replace(context.rootDir, '')}content/docs/`
 
   for (const entry of docEntries) {
     if (import.meta.env.MODE === 'production' && entry.data.draft === true) continue
 
+    const fileRelativePath = entry.filePath?.replace(contentRelativePath, '')
+
     const isDefaultLocaleEntry =
-      entry.id.startsWith(`${getPathWithLocale(config.prefix, DefaultLocale)}/`) &&
-      entry.id !== `${getPathWithLocale(config.prefix, DefaultLocale)}/index.mdx`
+      fileRelativePath?.startsWith(`${getPathWithLocale(config.prefix, DefaultLocale)}/`) &&
+      fileRelativePath !== `${getPathWithLocale(config.prefix, DefaultLocale)}/index.mdx`
 
     if (isDefaultLocaleEntry) {
       if (locale === DefaultLocale) {
         blogEntries.push(entry)
         continue
       }
 
+      // Briefly override `console.warn()` to silence logging when a localized entry is not found.
+      const warn = console.warn
+      // eslint-disable-next-line @typescript-eslint/no-empty-function
+      console.warn = () => {}
+
       try {
-        const localizedEntry = await getEntry<StarlightEntryData>('docs', getPathWithLocale(entry.slug, locale))
+        const localizedEntry = await getEntry('docs', getPathWithLocale(entry.id, locale))
+        if (!localizedEntry) throw new Error('Unavailable localized entry.')
         if (localizedEntry.data.draft === true) throw new Error('Draft localized entry.')
         blogEntries.push(localizedEntry)
       } catch {
         blogEntries.push(entry)
       }
+
+      // Restore the original `console.warn()` implementation.
+      console.warn = warn
     }
   }
 
@@ -139,7 +152,7 @@ export async function getBlogEntryExcerpt(entry: StarlightBlogEntry) {
     return entry.data.excerpt
   }
 
-  const { Content } = await entry.render()
+  const { Content } = await render(entry)
 
   return Content
 }
@@ -204,13 +217,11 @@ function validateBlogEntry(entry: StarlightEntry): asserts entry is StarlightBlo
   }
 }
 
-type StarlightEntryData = z.infer<ReturnType<typeof blogSchema>> & { draft?: boolean; title: string }
-type StarlightEntry = AstroCollectionEntry<StarlightEntryData>
+type StarlightEntry = CollectionEntry<'docs'>
 
 export type StarlightBlogEntry = StarlightEntry & {
   data: {
     date: Date
-    lastUpdated?: Date | boolean
   }
 }