diff --git a/astro.sidebar.ts b/astro.sidebar.ts index 5392673a160ac..2b2b98ce93c1d 100644 --- a/astro.sidebar.ts +++ b/astro.sidebar.ts @@ -147,9 +147,6 @@ export const sidebar = [ 'reference/experimental-flags/live-content-collections', 'reference/experimental-flags/client-prerender', 'reference/experimental-flags/content-intellisense', - 'reference/experimental-flags/preserve-scripts-order', - 'reference/experimental-flags/heading-id-compat', - 'reference/experimental-flags/static-import-meta-env', 'reference/experimental-flags/chrome-devtools-workspace', 'reference/experimental-flags/fail-on-prerender-conflict', ], diff --git a/src/content/docs/en/getting-started.mdx b/src/content/docs/en/getting-started.mdx index ec9c01835d6d2..9b70bb453fd03 100644 --- a/src/content/docs/en/getting-started.mdx +++ b/src/content/docs/en/getting-started.mdx @@ -5,6 +5,9 @@ i18nReady: true tableOfContents: false editUrl: false next: false +banner: + content: | + Astro v6 is here! Learn how to upgrade your site hero: title: Astro Docs tagline: Guides, resources, and API references to help you build with Astro. diff --git a/src/content/docs/en/guides/deploy/microsoft-azure.mdx b/src/content/docs/en/guides/deploy/microsoft-azure.mdx index 57ffa6ddf0360..dfb03cdcd3785 100644 --- a/src/content/docs/en/guides/deploy/microsoft-azure.mdx +++ b/src/content/docs/en/guides/deploy/microsoft-azure.mdx @@ -38,7 +38,7 @@ The GitHub action yaml that is created for you assumes the use of node 14. This ``` "engines": { - "node": ">=18.0.0" + "node": ">=22.12.0" }, ``` diff --git a/src/content/docs/en/guides/deploy/netlify.mdx b/src/content/docs/en/guides/deploy/netlify.mdx index 449e8fd034873..795ab2bdb7d5c 100644 --- a/src/content/docs/en/guides/deploy/netlify.mdx +++ b/src/content/docs/en/guides/deploy/netlify.mdx @@ -99,7 +99,7 @@ You can also create a new site on Netlify and link up your Git repository by ins ### Set a Node.js version -If you are using a legacy [build image](https://docs.netlify.com/configure-builds/get-started/#build-image-selection) (Xenial) on Netlify, make sure that your Node.js version is set. Astro requires `v18.20.8` or `v20.3.0` or higher. +If you are using a legacy [build image](https://docs.netlify.com/configure-builds/get-started/#build-image-selection) (Xenial) on Netlify, make sure that your Node.js version is set. Astro requires `v22.12.0` or higher. You can [specify your Node.js version in Netlify](https://docs.netlify.com/configure-builds/manage-dependencies/#node-js-and-javascript) using: - a [`.nvmrc`](https://github.com/nvm-sh/nvm#nvmrc) file in your base directory. diff --git a/src/content/docs/en/guides/endpoints.mdx b/src/content/docs/en/guides/endpoints.mdx index 3329a1bd64dad..51f9c9c65904b 100644 --- a/src/content/docs/en/guides/endpoints.mdx +++ b/src/content/docs/en/guides/endpoints.mdx @@ -47,6 +47,8 @@ import type { APIRoute } from "astro"; export const GET: APIRoute = async ({ params, request }) => {...} ``` +Note that endpoints whose URLs include a file extension (e.g. `src/pages/sitemap.xml.ts`) can only be accessed without a trailing slash (e.g. `/sitemap.xml`), regardless of your [`build.trailingSlash`](/en/reference/configuration-reference/#trailingslash) configuration. + ### `params` and Dynamic routing Endpoints support the same [dynamic routing](/en/guides/routing/#dynamic-routes) features that pages do. Name your file with a bracketed parameter name and export a [`getStaticPaths()` function](/en/reference/routing-reference/#getstaticpaths). Then, you can access the parameter using the `params` property passed to the endpoint function: diff --git a/src/content/docs/en/guides/environment-variables.mdx b/src/content/docs/en/guides/environment-variables.mdx index 1b8c4f73848c7..bcbe5b53c66d6 100644 --- a/src/content/docs/en/guides/environment-variables.mdx +++ b/src/content/docs/en/guides/environment-variables.mdx @@ -58,7 +58,6 @@ Astro includes a few environment variables out of the box: - `import.meta.env.DEV`: `true` if your site is running in development; `false` otherwise. Always the opposite of `import.meta.env.PROD`. - `import.meta.env.BASE_URL`: The base URL your site is being served from. This is determined by the [`base` config option](/en/reference/configuration-reference/#base). - `import.meta.env.SITE`: This is set to [the `site` option](/en/reference/configuration-reference/#site) specified in your project's `astro.config`. -- `import.meta.env.ASSETS_PREFIX`: The prefix for Astro-generated asset links if the [`build.assetsPrefix` config option](/en/reference/configuration-reference/#buildassetsprefix) is set. This can be used to create asset links not handled by Astro. Use them like any other environment variable. diff --git a/src/content/docs/en/guides/images.mdx b/src/content/docs/en/guides/images.mdx index 976b26a22f436..91fbbbec33997 100644 --- a/src/content/docs/en/guides/images.mdx +++ b/src/content/docs/en/guides/images.mdx @@ -51,7 +51,7 @@ All native HTML tags, including `` and ``, are also available in `.ast For all images in `.astro` files, **the value of the image `src` attribute is determined by the location of your image file**: - A local image from your project `src/` folder uses an import from the file's relative path. - + The image and picture components use the named import directly (e.g. `src={rocket}`), while the `` tag uses the `src` object property of the import (e.g. `src={rocket.src}`). - Remote and `public/` images use a URL path. @@ -321,7 +321,7 @@ import myImage from '../assets/my_image.png'; // Image is 1600x900 Responsive images are images that adjust to improve performance across different devices. These images can resize to fit their container, and can be served in different sizes depending on your visitor's screen size and resolution. -With [responsive image properties](/en/reference/modules/astro-assets/#responsive-image-properties) applied to the `` or `` components, Astro will automatically generate the required `srcset` and `sizes` values for your images, and apply the necessary [styles to ensure they resize correctly](#responsive-image-styles). +With the [layout property](/en/reference/modules/astro-assets/#layout) applied to the `` or `` components, Astro will automatically generate the required `srcset` and `sizes` values for your images, and apply the necessary [styles to ensure they resize correctly](#responsive-image-styles). When this responsive behavior is [configured globally with `image.layout`](/en/reference/configuration-reference/#imagelayout), it will apply to all image components and also to any local and remote images using [the Markdown `![]()` syntax](/en/guides/images/#images-in-markdown-files). @@ -396,7 +396,7 @@ The global styles applied by Astro will depend on the layout type, and are desig The styles use the [`:where()` pseudo-class](https://developer.mozilla.org/en-US/docs/Web/CSS/:where), which has a [specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Specificity) of 0, meaning that it is easy to override with your own styles. Any CSS selector will have a higher specificity than `:where()`, so you can easily override the styles by adding your own styles to target the image. -You can override the `object-fit` and `object-position` styles on a per-image basis by setting the `fit` and `position` props on the `` or `` component. +You can override the `object-fit` and `object-position` styles on a per-image basis by setting the `fit` and `position` props on the `` or `` component. #### Responsive images with Tailwind 4 diff --git a/src/content/docs/en/guides/internationalization.mdx b/src/content/docs/en/guides/internationalization.mdx index e210b84c37816..70b4bbdea9db8 100644 --- a/src/content/docs/en/guides/internationalization.mdx +++ b/src/content/docs/en/guides/internationalization.mdx @@ -170,15 +170,11 @@ Set this option when all routes will have their `/locale/` prefix in their URL a - URLs without a locale prefix, (e.g. `example.com/about/`) will return a 404 (not found) status code unless you specify a [fallback strategy](#fallback). -### `redirectToDefaultLocale` +#### Opting out of redirects for the home URL -

+Even with your default locale routes prefixed, this behaviour does not apply by default to your site's index page. This allows you to have a home page that exists outside of your configured locale structure, where all of your localized routes are prefixed except the home URL of your site. -Configures whether or not the home URL (`/`) generated by `src/pages/index.astro` will redirect to `/`. - -Setting `prefixDefaultLocale: true` will also automatically set `redirectToDefaultLocale: true` in your `routing` config object. By default, the required `src/pages/index.astro` file will automatically redirect to the index page of your default locale. - -You can opt out of this behavior by [setting `redirectToDefaultLocale: false`](/en/reference/configuration-reference/#i18nroutingredirecttodefaultlocale). This allows you to have a site home page that exists outside of your configured locale folder structure. +You can opt out of this behavior so that your main site URL will also redirect to a prefixed, localized route for your default locale. When `prefixDefaultLocale: true` is set, you can additionally configure `redirectToDefaultLocale: true`. This will ensure that the home URL (`/`) generated by `src/pages/index.astro` will redirect to `/[defaultLocale]/`. ### `manual` diff --git a/src/content/docs/en/guides/upgrade-to/v5.mdx b/src/content/docs/en/guides/upgrade-to/v5.mdx index e807eaf133de5..f66c46dba673d 100644 --- a/src/content/docs/en/guides/upgrade-to/v5.mdx +++ b/src/content/docs/en/guides/upgrade-to/v5.mdx @@ -1112,7 +1112,7 @@ function useRoute(route: IntegrationRouteData) { } ``` -See the [API reference for `IntegrationRouteData`](/en/reference/integrations-reference/#integrationroutedata-type-reference). +See the API reference for `IntegrationRouteData`. ### Changed: `distURL` is now an array (Integrations API) @@ -1139,7 +1139,7 @@ if (route.distURL) { } ``` -See the [API reference for `IntegrationRouteData`](/en/reference/integrations-reference/#integrationroutedata-type-reference). +See the [API reference for `IntegrationRouteData`. ### Changed: Arguments passed to `app.render()` (Adapter API) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx new file mode 100644 index 0000000000000..a96344079bc9d --- /dev/null +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -0,0 +1,933 @@ +--- +title: Upgrade to Astro v6 +description: How to upgrade your project to Astro v6.0. +sidebar: + label: v6.0 +i18nReady: true +--- +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import { Steps } from '@astrojs/starlight/components'; +import ReadMore from '~/components/ReadMore.astro' +import SourcePR from '~/components/SourcePR.astro' + +This guide will help you migrate from Astro v5 to Astro v6. + +Need to upgrade an older project to v5 first? See our [older migration guide](/en/guides/upgrade-to/v5/). + +Need to see the v5 docs? Visit this [older version of the docs site (unmaintained v5.xx snapshot)](https://v5.docs.astro.build/). + +## Upgrade Astro + +Update your project's version of Astro to the latest version using your package manager: + + + + ```shell + # Upgrade Astro and official integrations together + npx @astrojs/upgrade + ``` + + + ```shell + # Upgrade Astro and official integrations together + pnpm dlx @astrojs/upgrade + ``` + + + ```shell + # Upgrade Astro and official integrations together + yarn dlx @astrojs/upgrade + ``` + + + +You can also [upgrade your Astro integrations manually](/en/guides/integrations-guide/#manual-upgrading) if needed, and you may also need to upgrade other dependencies in your project. + +:::note[Need to continue?] +After upgrading Astro, you may not need to make any changes to your project at all! + +But, if you notice errors or unexpected behavior, please check below for what has changed that might need updating in your project. +::: + +Astro v6.0 includes [potentially breaking changes](#breaking-changes), as well as the removal and deprecation of some features. + +If your project doesn't work as expected after upgrading to v6.0, check this guide for an overview of all breaking changes and instructions on how to update your codebase. + +See [the Astro changelog](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md) for full release notes. + +## Dependency Upgrades + +Any major upgrades to Astro's dependencies may cause breaking changes in your project. + +### Node 22 + + + +Node 18 reached its End of Life in March 2025 and Node 20 is scheduled to reach its End of Life in April 2026. + +Astro v6.0 drops Node 18 and Node 20 support entirely so that all Astro users can take advantage of Node's more modern features. + +#### What should I do? + +Check that both your development environment and your deployment environment are using **Node `22.12.0` or higher**. + + +1. Check your local version of Node using: + + ```sh + node -v + ``` + +2. Check your [deployment environment's](/en/guides/deploy/) own documentation to verify that they support Node 22. + + You can specify Node `22.12.0` for your Astro project either in a dashboard configuration setting or a `.nvmrc` file. + + ```bash title=".nvmrc" + 22.12.0 + ``` + + +### Vite 7.0 + + + +Astro v6.0 upgrades to Vite v7.0 as the development server and production bundler. + +#### What should I do? + +If you are using Vite-specific plugins, configuration, or APIs, check the [Vite migration guide](https://vite.dev/guide/migration) for their breaking changes and upgrade your project as needed. + +## Legacy + +The following features are now considered legacy features. They should function normally but are no longer recommended and are in maintenance mode. They will see no future improvements and documentation will not be updated. These features will eventually be deprecated, and then removed entirely. + +## Deprecated + +The following deprecated features are no longer supported and are no longer documented. Please update your project accordingly. + +Some deprecated features may temporarily continue to function until they are completely removed. Others may silently have no effect, or throw an error prompting you to update your code. + +### Deprecated: `Astro` in `getStaticPaths()` + + + +In Astro 5.x, it was possible to access an `Astro` object inside `getStaticPaths()`. However, despite being typed the same as the `Astro` object accessible in the frontmatter, this object only had `site` and `generator` properties. This could lead to confusion about which `Astro` object properties were available inside `getStaticPaths()`. + +Astro 6.0 deprecates this object for `getStaticPaths()` to avoid confusion and improves error handling when attempting to access `Astro` values that are unavailable. Using `Astro.site` or `Astro.generator` within `getStaticPaths()` will now log a deprecation warning, and accessing any other property will throw a specific error with a helpful message. In a future major version, this object will be removed entirely, and accessing `Astro.site` or `Astro.generator` will also throw an error. + +#### What should I do? + +Update your `getStaticPaths()` function if you were attempting to access any `Astro` properties inside its scope. Remove `Astro.generator` entirely, and replace all occurrences of `Astro.site()` with `import.meta.env.SITE`: + +```astro title="src/pages/blog/[slug].astro" del={5,6} ins={7} +--- +import { getPages } from "../../../utils/data"; + +export async function getStaticPaths() { + console.log(Astro.generator); + return getPages(Astro.site); + return getPages(import.meta.env.SITE); +} +--- +``` + +Read more about [built-in environment variables such as `import.meta.env.SITE`](/en/guides/environment-variables/#default-environment-variables) that are accessible when [using `getStaticPaths()` to dynamically generate static routes](/en/guides/routing/#static-ssg-mode). + +### Deprecated: `import.meta.env.ASSETS_PREFIX` + + + +In Astro 5.x, it was possible to access `build.assetsPrefix` in your Astro config via the built-in environment variable `import.meta.env.ASSETS_PREFIX`. However, Astro v5.7.0 introduced the `astro:config` virtual model to expose a non-exhaustive, serializable, type-safe version of the Astro configuration which included access to `build.assetsPrefix` directly. This became the preferred way to access the prefix for Astro-generated asset links when set, although the environment variable still existed. + +Astro 6.0 deprecates this variable in favor of `build.assetsPrefix` from the `astro:config/server` module. + +#### What should I do? + +Replace any occurances of `import.meta.env.ASSETS_PREFIX` with the `build.assetsPrefix` import from `astro:config/server`. This is a drop-in replacement to provide the existing value, and no other changes to your code should be necessary: + +```ts del={4} ins={2,5} +import { someLogic } from "./utils" +import { build } from "astro:config/server" + +someLogic(import.meta.env.ASSETS_PREFIX) +someLogic(build.assetsPrefix) +``` + +Read more about the [`astro:config` virtual modules](/en/reference/modules/astro-config/). + +## Removed + +The following features have now been entirely removed from the code base and can no longer be used. Some of these features may have continued to work in your project even after deprecation. Others may have silently had no effect. + +Projects now containing these removed features will be unable to build, and there will no longer be any supporting documentation prompting you to remove these features. + + +### Removed: legacy content collections + + + +In Astro 5.x, it was still possible to use [the original Content Collections API first introduced in Astro v2.0](https://astro.build/blog/introducing-content-collections/), **either through a `legacy` configuration flag or via built-in backwards compatibility**. These methods allowed you to upgrade to Astro v5 even if you were not yet ready or able to update your existing content collections to those powered by the new Content Layer API. + +**Astro v6.0 removes this previously deprecated Content Collections API support entirely, including the `legacy.collections` flag **and some existing backwards compatibility that was not previously behind a flag**. All content collections must now use [the Content Layer API introduced in Astro v5.0](https://astro.build/blog/content-layer-deep-dive/) that powers all content collections. **No backwards compatibility support is available.** + +#### What should I do? + +If you had previously enabled the legacy flag, you must remove it. + +```ts title="astro.config.mjs" del={5} +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + legacy: { + collections: true, + } +}) +``` + +Additionally, if you did not upgrade your collections for Astro v5.0, ensure that your content collections are **fully updated** for the new API. + +Astro v5.x included some automatic backwards compatibility to allow content collections to continue to work even if they had not been updated to use the new API. Therefore, your v5 collections may contain one or more legacy features that need updating to the newer API for v6, even if your project was previously error-free. + +If you have [content collections errors](/en/reference/error-reference/#content-collection-errors) or warnings after upgrading to v6, use the following list to help you identify and upgrade any legacy features that may exist in your code. + +##### If you have... + +
+no content collections configuration file +Create `src/content.config.ts` and [define your collections](/en/guides/content-collections/#defining-collections) in it. +
+ +
+a configuration file located at `src/content/config.ts` / ([`LegacyContentConfigError`](/en/reference/errors/legacy-content-config-error/)) +Rename and move this file to `src/content.config.ts` +
+ +
+a collection that does not define a `loader`/ ([`ContentCollectionMissingALoaderError`](/en/reference/errors/content-collection-missing-loader/)) + +Import [Astro's built-in `glob()` loader](/en/guides/content-collections/#built-in-loaders) and define the `pattern` and `base` for your collection entries: + +```ts ins={3,6} +// src/content.config.ts +import { defineCollection, z } from 'astro:content'; +import { glob } from 'astro/loaders'; + +const blog = defineCollection({ + loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }), + schema: z.object({ + title: z.string(), + description: z.string(), + pubDate: z.coerce.date(), + updatedDate: z.coerce.date().optional(), + }), +}); +``` +
+ +
+a collection that defines a collection type (`type: 'content'` or `type: 'data'`) / ([`ContentCollectionInvalidTypeError`](/en/reference/errors/content-collection-invalid-type/)) +There are no longer different types of collections. This must be deleted from your collection definition. + +```ts del={7} +// src/content.config.ts +import { defineCollection, z } from 'astro:content'; +import { glob } from 'astro/loaders'; + +const blog = defineCollection({ + // For content layer you no longer define a `type` + type: 'content', + loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }), + schema: z.object({ + title: z.string(), + description: z.string(), + pubDate: z.coerce.date(), + updatedDate: z.coerce.date().optional(), + }), +}); +``` +
+ +
+legacy collection querying methods `getDataEntryById()` and `getEntryBySlug()` / ([`GetEntryDeprecationError`](/en/reference/errors/get-entry-deprecation-error/)) +Replace both methods with [`getEntry()`](/en/reference/modules/astro-content/#getentry). + +
+ +
+legacy collection querying and rendering methods that depend on a `slug` property / ([`ContentSchemaContainsSlugError`](/en/reference/errors/content-schema-contains-slug-error/)) +Previously, the `id` was based on the filename, and there was a `slug` property that could be used in a URL. Now the [CollectionEntry](/en/reference/modules/astro-content/#collectionentry) `id` is a slug. If you need access to the filename (previously available as the `id`), use the `filePath` property. Replace instances of `slug` with `id`: + +```astro ins={6} del={5} title="src/pages/[slug].astro" +--- +export async function getStaticPaths() { + const posts = await getCollection('blog'); + return posts.map((post) => ({ + params: { slug: post.slug }, + params: { slug: post.id }, + props: post, + })); +} +--- +``` +
+ +
+content rendered using `entry.render()` +Collection entries no longer have a `render()` method. Instead, import the `render()` function from `astro:content` and use `render(entry)`: + +```astro title="src/pages/index.astro" ins=", render" del={6} ins={7} +--- +import { getEntry, render } from 'astro:content'; + +const post = await getEntry('pages', 'homepage'); + +const { Content, headings } = await post.render(); +const { Content, headings } = await render(post); +--- + +``` + +
+ + See [the Astro v5 upgrade guide](/en/guides/upgrade-to/v5/#legacy-v20-content-collections-api) for previous guidance about backwards compatibility of legacy collections in Astro v5 and full step-by-step instructions for upgrading legacy collections to the new Content Layer API. + + +### Removed: `` component + + + +In Astro 5.0, the `` component was renamed to `` to clarify the role of the component. The new name makes it more clear that the features you get from Astro's `` routing component are slightly different from the native CSS-based MPA router. However, a deprecated version of the `` component still existed and may have functioned in Astro 5.x. + +Astro 6.0 removes the `` component entirely and it can no longer be used in your project. Update to the `` component to continue to use these features. + +#### What should I do? + +Replace all occurrences of the `ViewTransitions` import and component with `ClientRouter`: + +```astro title="src/layouts/MyLayout.astro" del={1,7} ins={2,8} +import { ViewTransitions } from 'astro:transitions'; +import { ClientRouter } from 'astro:transitions'; + + + + ... + + + + +``` + +Read more about [view transitions and client-side routing in Astro](/en/guides/view-transitions/). + +### Removed: `emitESMImage()` + + + +In Astro 5.6.2, the `emitESMImage()` function was deprecated in favor of `emitImageMetadata()`, which removes two deprecated arguments that were not meant to be exposed for public use: `_watchMode` and `experimentalSvgEnabled`. + +Astro 6.0 removes `emitESMImage()` entirely. Update to `emitImageMetadata()` to keep your current behavior. + +#### What should I do? + +Replace all occurrences of the `emitESMImage()` with `emitImageMetadata()` and remove unused arguments: + +```ts del={1,5} ins={2,6} +import { emitESMImage } from 'astro/assets/utils'; +import { emitImageMetadata } from 'astro/assets/utils'; + +const imageId = '/images/photo.jpg'; +const result = await emitESMImage(imageId, false, false); +const result = await emitImageMetadata(imageId); +``` + +Read more about [`emitImageMetadata()`](/en/reference/image-service-reference/#emitimagemetadata). + +### Removed: `Astro.glob()` + + + +In Astro 5.0, `Astro.glob()` was deprecated in favor of using `getCollection()` to query your collections, and `import.meta.glob()` to query other source files in your project. + +Astro 6.0 removes `Astro.glob()` entirely. Update to `import.meta.glob()` to keep your current behavior. + +#### What should I do? + +Replace all use of `Astro.glob()` with `import.meta.glob()`. Note that `import.meta.glob()` no longer returns a `Promise`, so you may have to update your code accordingly. You should not require any updates to your [glob patterns](/en/guides/imports/#glob-patterns). + +```astro title="src/pages/blog.astro" del={2} ins={3} +--- +const posts = await Astro.glob('./posts/*.md'); +const posts = Object.values(import.meta.glob('./posts/*.md', { eager: true })); +--- + +{posts.map((post) =>
  • {post.frontmatter.title}
    • )} +``` + +Where appropriate, consider using [content collections](/en/guides/content-collections/) to organize your content, which has its own newer, more performant querying functions. + +You may also wish to consider using glob packages from NPM, such as [`fast-glob`](https://www.npmjs.com/package/fast-glob). + +Learn more about [importing files with `import.meta.glob`](/en/guides/imports/#importmetaglob). + +### Removed: `routes` on `astro:build:done` hook (Integration API) + + + +In Astro 5.0, accessing `routes` on the `astro:build:done` hook was deprecated. + +Astro 6.0 removes the `routes` array passed to this hook entirely. Instead, the `astro:routes:resolved` hook should be used. + +#### What should I do? + +Remove any instance of `routes` passed to `astro:build:done` and replace it with the new `astro:routes:resolved` hook. Access `distURL` on the newly exposed `assets` map: + +```js title="my-integration.mjs" ins={2,6-8,11,13-18} del={10} +const integration = () => { + let routes + return { + name: 'my-integration', + hooks: { + 'astro:routes:resolved': (params) => { + routes = params.routes + }, + 'astro:build:done': ({ + routes + assets + }) => { + for (const route of routes) { + const distURL = assets.get(route.pattern) + if (distURL) { + Object.assign(route, { distURL }) + } + } + console.log(routes) + } + } + } +} +``` + +Learn more about [the Integration API `astro:routes:resolved` hook](/en/reference/integrations-reference/#astroroutesresolved) for building integrations. + +### Removed: `entryPoints` on `astro:build:ssr` hook (Integration API) + + + +In Astro 5.0, [`functionPerRoute` was deprecated](/en/guides/upgrade-to/v5/#deprecated-functionperroute-adapter-api). That meant that `entryPoints` on the `astro:build:ssr` hook was always empty. + +Astro 6.0 removes the `entryPoints` map passed to this hook entirely. + +#### What should I do? + +Remove any instance of `entryPoints` passed to `astro:build:ssr`: + +```js title="my-integration.mjs" del={6} +const integration = () => { + return { + name: 'my-integration', + hooks: { + 'astro:build:ssr': (params) => { + someLogic(params.entryPoints) + }, + } + } +} +``` + +### Removed: old `app.render()` signature (Adapter API) + + + +In Astro 4.0, the `app.render()` signature that allowed passing `routeData` and `locals` as optional arguments was deprecated in favor of a single optional `renderOptions` argument. + +Astro 6.0 removes this signature entirely. Attempting to pass these separate arguments will now cause an error in your project. + +#### What should I do? + +Review your `app.render` calls and pass `routeData` and `locals` as properties of an object instead of as multiple independent arguments: + +```ts title="my-adapter/entrypoint.ts" del={1} ins={2} +app.render(request, routeData, locals) +app.render(request, { routeData, locals }) +``` + +Learn more about the [Adapter API](/en/reference/adapter-reference/). + +### Removed: `app.setManifestData()` (Adapter API) + + + +In Astro 5.0, the `app.setManifestData()` method was available on `App` and `NodeApp`, but is no longer used nor needed. + +Astro 6.0 removes this method entirely. + +#### What should I do? + +Remove any call to `app.setManifestData()`. If you need to update the manifest, create a new `App` instance. + +Learn more about the [Adapter API](/en/reference/adapter-reference/). + +### Removed: `handleForms` prop for the `` component + + + +In Astro 4.0, the `handleForms` prop of the `` component was deprecated, as it was no longer necessary to opt in to handling `submit` events for `form` elements. This functionality has been built in by default and the property, if still included in your project, silently had no impact on form submission. + +Astro 6.0 removes this prop entirely and it now must be removed to avoid errors in your project. + +#### What should I do? + +Remove the `handleForms` property from your `` component if it exists. It has provided no additional functionality, and so removing it should not change any behavior in your project: + +```astro title="src/pages/index.astro" del="handleForms" +--- +import { ClientRouter } from "astro:transitions"; +--- + + + + + + + + +``` + +Learn more about [transitions with forms](/en/guides/view-transitions/#transitions-with-forms). + +### Removed: `prefetch()` `with` option + + + +In Astro 4.8.4, the `with` option of the programmatic `prefetch()` function was deprecated in favor of a more sensible default behavior that no longer required specifying the priority of prefetching for each page. + +Astro 6.0 removes this option entirely and it is no longer possible to configure the priority of prefetching by passing the `with` option. Attempting to do so will now cause errors. + +By default, Astro's prefetching now uses an automatic approach that will always try to use ` + +In Astro 5.5.6, the `ActionAPIContext.rewrite` method was deprecated because custom endpoints should be used instead of rewrites. + +Astro 6.0 removes the `rewrite()` method from `ActionAPIContext` entirely and it may no longer be used. + +#### What should I do? + +Review your Actions handlers and remove any call to `rewrite()`: + + +```ts title="src/actions/index.ts" del={10} +import { defineAction } from 'astro:actions'; +import { z } from 'astro:schema'; + +export const server = { + getGreeting: defineAction({ + input: z.object({ + // ... + }), + handler: async (input, context) => { + context.rewrite('/') + // ... + } + }) +} +``` + +Learn more about [rewrites](/en/guides/routing/#rewrites). + +### Experimental Flags + +Experimental flags allow you to opt in to features while they are in early development. Astro may also use experimental flags to test breaking changes to default behavior. The following experimental flags have been removed in Astro 6.0 and are now stable, or the new default behavior. + +Remove these experimental flags from your Astro config if you were previously using them: + +```js del={5-8} title="astro.config.mjs" +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + experimental: { + liveContentCollections: true, + preserveScriptOrder: true, + staticImportMetaEnv: true, + headingIdCompat: true, + }, +}) +``` + +#### Experimental features now stable: + +- `liveContentCollections` (See the updated [content collections docs](/en/guides/content-collections/) to learn more about live collections.) + +#### New default or recommended behavior: + +- `preserveScriptOrder` (See below for breaking changes to [default ` + +``` + +Read more about [using `script`](/en/guides/client-side-scripts/) and [`style`](/en/guides/styling/) tags. + +## Breaking Changes + +The following changes are considered breaking changes in Astro v5.0. Breaking changes may or may not provide temporary backwards compatibility. If you were using these features, you may have to update your code as recommended in each entry. + +### Changed: endpoints with a file extension cannot be accessed with a trailing slash + + + +In Astro v5.0, custom endpoints whose URL ended in a file extension (e.g. `/src/pages/sitemap.xml.ts` ) could be accessed with a trailing slash (`/sitemap.xml/`) or without (`/sitemap.xml`), regardless of the value configured for `build.trailingSlash`. + +In Astro v6.0, these endpoints can only be accessed without a trailing slash. This is true regardless of your `build.trailingSlash` configuration. + +#### What should I do? + +Review your links to your custom endpoints that include a file extension in the URL and remove any trailing slashes: + +```html del={1} ins={2} title="src/pages/index.astro" +Sitemap +Sitemap +``` + +Learn more about [custom endpoints](/en/guides/endpoints/). + +### Changed: `import.meta.env` values are always inlined + + + +In Astro 5.13, the `experimental.staticImportMetaEnv` flag was introduced to update the behavior when accessing `import.meta.env` directly to align with [Vite's handling of environment variables](https://vite.dev/guide/env-and-mode.html#env-variables) and ensures that `import.meta.env` values are always inlined. + +In Astro 5.x, non-public environment variables were replaced by a reference to `process.env`. Additionally, Astro could also convert the value type of your environment variables used through `import.meta.env`, which could prevent access to some values such as the strings `"true"` (which was converted to a boolean value), and `"1"` (which was converted to a number). + +Astro 6 removes this experimental flag and makes this the new default behavior in Astro: `import.meta.env` values are always inlined and never coerced. + +#### What should I do? + +If you were previously using this experimental feature, you must [remove this experimental flag from your configuration](#experimental-flags) as it no longer exists. + +If you were relying on coercion, you may need to update your project code to apply it manually: + +```ts title="src/components/MyComponent.astro" del={1} ins={2} +const enabled: boolean = import.meta.env.ENABLED; +const enabled: boolean = import.meta.env.ENABLED === "true"; +``` + +If you were relying on the transformation into `process.env`, you may need to update your project code to apply it manually: + +```ts title="src/components/MyComponent.astro" del={1} ins={2} +const enabled: boolean = import.meta.env.DB_PASSWORD; +const enabled: boolean = process.env.DB_PASSWORD; +``` + +You may also need to update types: + +```ts title="src/env.d.ts" del={3-4} ins={5,12-16} +interface ImportMetaEnv { + readonly PUBLIC_POKEAPI: string; + readonly DB_PASSWORD: string; + readonly ENABLED: boolean; + readonly ENABLED: string; +} + +interface ImportMeta { + readonly env: ImportMetaEnv; +} + +namespace NodeJS { + interface ProcessEnv { + DB_PASSWORD: string; + } +} +``` + +If you need more control over environment variables in Astro, we recommend you use `astro:env`. + +Learn more about [environment variables](/en/guides/environment-variables/) in Astro, including `astro:env`. + +### Changed: Cropping by default in default image service + + + +In Astro 5.0, the default image service would only apply cropping when the `fit` option was provided. + +Astro 6.0 applies cropping by default without requiring setting the `fit` option. + +#### What should I do? + +No changes are needed to your existing cropped images as the `fit` property is still valid. However, if you were previously setting `fit` to `contain` (its default value) in order to crop your images, you may now remove this option and still achieve the same cropping behavior by specifying `width` and `height` alone: + +```ts title="src/components/MyImage.astro" del={5} ins={6} +--- +import { Image } from 'astro:assets'; +import myImage from '../assets/photo.jpg'; +--- + + +``` + +### Changed: Never upscale images in default image service + + + +In Astro 5.0, the default image service would upscale images when the requested dimensions were larger than the source image. + +Astro 6.0 removes this behavior: the default image service never upscales images. + +#### What should I do? + +Review your images and update dimensions as needed. If you do need to upscale images, you may consider upscaling the images manually or using a custom image service that supports upscaling. + +### Changed: Markdown heading ID generation + + + +In Astro 5.x, an additional default processing step to Markdown stripped trailing hyphens from the end of IDs for section headings ending in special characters. This provided a cleaner `id` value, but could lead to incompatibilities rendering your Markdown across platforms. + +In Astro 5.5, the `experimental.headingIdCompat` flag was introduced to allow you to make the IDs generated by Astro for Markdown headings compatible with common platforms like GitHub and npm, using the popular [`github-slugger`](https://github.com/Flet/github-slugger) package. + +Astro 6.0 removes this experimental flag and makes this the new default behavior in Astro: trailing hyphens from the end of IDs for headings ending in special characters are no longer removed. + +#### What should I do? + +If you have manual links to headings, you may need to update the anchor link value with a new trailing hyphen. For example, the following Markdown heading: + +```md +## `` +``` + +will now generate the following HTML with a trailing hyphen in the heading `id`: + +```html ins="-" +

    <Picture />

    +``` + +and must now be linked to as: + +```markdown ins="-" +See [the Picture component](/en/guides/images/#picture-) for more details. +``` + +If you were previously using the experimental feature to enforce trailing hyphens, you must [remove this experimental flag from your configuration](#experimental-flags) as it no longer exists. + +If you were previously using the `rehypeHeadingIds` plugin directly to enforce compatibility, remove the `headingIdCompat` option as it no longer exists: + +```js title="astro.config.mjs" del={8} ins={9} +import { defineConfig } from 'astro/config'; +import { rehypeHeadingIds } from '@astrojs/markdown-remark'; +import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source'; + +export default defineConfig({ + markdown: { + rehypePlugins: [ + [rehypeHeadingIds, { headingIdCompat: true }], + [rehypeHeadingIds], + otherPluginThatReliesOnHeadingIDs, + ], + }, +}); +``` + +If you want to keep the old ID generation for backward compatibility reasons, you can create a custom rehype plugin that will generate headings IDs like Astro 5.x. This will allow you to continue to use your existing anchor links without adding trailing hyphens. + +
    + +Create a custom rehype plugin to strip trailing hyphens + + + +1. Install required dependencies: + + + + ```sh + npm i github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string + ``` + + + ```sh + pnpm add github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string + ``` + + + ```sh + yarn add github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string + ``` + + + +2. Create a custom rehype plugin that will generate headings IDs like Astro v5: + + ```js title="plugins/rehype-slug.mjs" + import GithubSlugger from 'github-slugger'; + import { headingRank } from 'hast-util-heading-rank'; + import { visit } from 'unist-util-visit'; + import { toString } from 'hast-util-to-string'; + + const slugs = new GithubSlugger(); + + export function rehypeSlug() { + /** + * @param {import('hast').Root} tree + */ + return (tree) => { + slugs.reset(); + visit(tree, 'element', (node) => { + if (headingRank(node) && !node.properties.id) { + let slug = slugs.slug(toString(node)); + // Strip trailing hyphens like in Astro v5 and below: + if (slug.endsWith('-')) slug = slug.slice(0, -1); + node.properties.id = slug; + } + }); + }; + } + ``` + +3. Add the custom plugin to your Markdown configuration in `astro.config.mjs`: + + ```js title="astro.config.mjs" ins={2} ins="rehypeSlug" + import { defineConfig } from 'astro/config'; + import { rehypeSlug } from './plugins/rehype-slug'; + + export default defineConfig({ + markdown: { + rehypePlugins: [rehypeSlug], + }, + }); + ``` + + + +
    + +Learn more about [Heading IDs](/en/guides/markdown-content/#heading-ids). + +### Changed: `getStaticPaths()` cannot return `params` of type number + + + +In Astro 5.x, `getStaticPaths()` could return `params` of type number, which would always be stringified by Astro. However, that could be confusing because it conflicted with `Astro.params` types. + +Astro 6.0 removes this behavior: `getStaticPaths()` must now return string or undefined `params` values. + +#### What should I do? + +Review your dynamic routes using `getStaticPaths()` and convert any number params to strings: + +```astro title="src/pages/post/[id]/[label].astro" del={6,13} ins={7,14} +--- +export function getStaticPaths() { + return [ + { + params: { + id: 1, + id: "1", + label: "foo", + } + }, + { + params: { + id: 2, + id: "2", + label: "bar", + } + }, + ] +} +--- +``` + +Learn more about [dynamic SSG routes with `getStaticPaths()`](/en/guides/routing/#static-ssg-mode). + +## Community Resources + +Know a good resource for Astro v5.0? [Edit this page](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/upgrade-to/v6.mdx) and add a link below! + +## Known Issues + +Please check [Astro's issues on GitHub](https://github.com/withastro/astro/issues/) for any reported issues, or to file an issue yourself. diff --git a/src/content/docs/en/install-and-setup.mdx b/src/content/docs/en/install-and-setup.mdx index d5986b397a2d3..8571d24b98b94 100644 --- a/src/content/docs/en/install-and-setup.mdx +++ b/src/content/docs/en/install-and-setup.mdx @@ -21,7 +21,7 @@ Prefer to try Astro in your browser? Visit [astro.new](https://astro.new/) to br ## Prerequisites -- **Node.js** - `v18.20.8` or `v20.3.0`, `v22.0.0` or higher. (`v19` and `v21` are not supported.) +- **Node.js** - `v22.12.0` or higher. Odd-numbered versions like `v23` are not supported. - **Text editor** - We recommend [VS Code](https://code.visualstudio.com/) with our [Official Astro extension](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode). - **Terminal** - Astro is accessed through its command-line interface (CLI). diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 0fe4a723b68a3..45bc1e4156b80 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -479,7 +479,7 @@ If not provided, Astro will fallback to its default behavior for fetching error **Default:** `app.match(request)`

    -Provide a value for [`integrationRouteData`](/en/reference/integrations-reference/#integrationroutedata-type-reference) if you already know the route to render. Doing so will bypass the internal call to [`app.match`](#appmatch) to determine the route to render. +Provide a value for `integrationRouteData` if you already know the route to render. Doing so will bypass the internal call to [`app.match`](#appmatch) to determine the route to render. ```js "routeData" const routeData = app.match(request); diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 8bcdbedcee4bb..bd6c7f2b044e5 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -1048,118 +1048,3 @@ Loads a session by ID. In normal use, a session is loaded automatically from the - - -### Deprecated object properties - -#### `Astro.glob()` - -:::caution[Deprecated in v5.0] -Use [Vite's `import.meta.glob`](https://vite.dev/guide/features.html#glob-import) to query project files. - -`Astro.glob('../pages/post/*.md')` can be replaced with: - -`Object.values(import.meta.glob('../pages/post/*.md', { eager: true }));` - -See the [imports guide](/en/guides/imports/#importmetaglob) for more information and usage. -::: - -`Astro.glob()` is a way to load many local files into your static site setup. - -```astro ---- -// src/components/my-component.astro -const posts = await Astro.glob('../pages/post/*.md'); // returns an array of posts that live at ./src/pages/post/*.md ---- - -
    -{posts.slice(0, 3).map((post) => ( -
    -

    {post.frontmatter.title}

    -

    {post.frontmatter.description}

    - Read more -
    -))} -
    -``` - -`.glob()` only takes one parameter: a relative URL glob of which local files you'd like to import. It’s asynchronous and returns an array of the exports from matching files. - -`.glob()` can't take variables or strings that interpolate them, as they aren't statically analyzable. (See [the imports guide](/en/guides/imports/#supported-values) for a workaround.) This is because `Astro.glob()` is a wrapper of Vite's [`import.meta.glob()`](https://vite.dev/guide/features.html#glob-import). - -:::note -You can also use `import.meta.glob()` itself in your Astro project. You may want to do this when: -- You need this feature in a file that isn't `.astro`, like an API route. `Astro.glob()` is only available in `.astro` files, while `import.meta.glob()` is available anywhere in the project. -- You don't want to load each file immediately. `import.meta.glob()` can return functions that import the file content, rather than returning the content itself. Note that this import includes all styles and scripts for any imported files. These will be bundled and added to the page whether or not a file is actually used, as this is decided by static analysis, not at runtime. -- You want access to each file's path. `import.meta.glob()` returns a map of a file's path to its content, while `Astro.glob()` returns a list of content. -- You want to pass multiple patterns; for example, you want to add a "negative pattern" that filters out certain files. `import.meta.glob()` can optionally take an array of glob strings, rather than a single string. - -Read more in the [Vite documentation](https://vite.dev/guide/features.html#glob-import). -::: - -##### Markdown Files - -Markdown files loaded with `Astro.glob()` return the following `MarkdownInstance` interface: - -```ts -export interface MarkdownInstance> { - /* Any data specified in this file's YAML/TOML frontmatter */ - frontmatter: T; - /* The absolute file path of this file */ - file: string; - /* The rendered path of this file */ - url: string | undefined; - /* Astro Component that renders the contents of this file */ - Content: AstroComponentFactory; - /** (Markdown only) Raw Markdown file content, excluding layout HTML and YAML/TOML frontmatter */ - rawContent(): string; - /** (Markdown only) Markdown file compiled to HTML, excluding layout HTML */ - compiledContent(): string; - /* Function that returns an array of the h1...h6 elements in this file */ - getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>; - default: AstroComponentFactory; -} -``` - -You can optionally provide a type for the `frontmatter` variable using a TypeScript generic. - -```astro ---- -interface Frontmatter { - title: string; - description?: string; -} -const posts = await Astro.glob('../pages/post/*.md'); ---- - -
      - {posts.map(post =>
    • {post.frontmatter.title}
      • )} -
    -``` - -##### Astro Files - -Astro files have the following interface: - -```ts -export interface AstroInstance { - /* The file path of this file */ - file: string; - /* The URL for this file (if it is in the pages directory) */ - url: string | undefined; - default: AstroComponentFactory; -} -``` - -##### Other Files - -Other files may have various different interfaces, but `Astro.glob()` accepts a TypeScript generic if you know exactly what an unrecognized file type contains. - -```ts ---- -interface CustomDataFile { - default: Record; -} -const data = await Astro.glob('../data/**/*.js'); ---- -``` diff --git a/src/content/docs/en/reference/configuration-reference.mdx b/src/content/docs/en/reference/configuration-reference.mdx index 4e30098a4ecb4..c6dbc501e3452 100644 --- a/src/content/docs/en/reference/configuration-reference.mdx +++ b/src/content/docs/en/reference/configuration-reference.mdx @@ -1587,14 +1587,14 @@ export default defineConfig({

    **Type:** `boolean`
    -**Default:** `true`
    +**Default:** `false`

    Configures whether or not the home URL (`/`) generated by `src/pages/index.astro` will redirect to `/[defaultLocale]` when `prefixDefaultLocale: true` is set. -Set `redirectToDefaultLocale: false` to disable this automatic redirection at the root of your site: +Set `redirectToDefaultLocale: true` to enable this automatic redirection at the root of your site: ```js // astro.config.mjs export default defineConfig({ @@ -1603,7 +1603,7 @@ export default defineConfig({ locales: ["en", "fr"], routing: { prefixDefaultLocale: true, - redirectToDefaultLocale: false + redirectToDefaultLocale: true } } }) diff --git a/src/content/docs/en/reference/errors/astro-glob-no-match.mdx b/src/content/docs/en/reference/errors/astro-glob-no-match.mdx index 0e440b87c3717..e0f6b9d83d6b6 100644 --- a/src/content/docs/en/reference/errors/astro-glob-no-match.mdx +++ b/src/content/docs/en/reference/errors/astro-glob-no-match.mdx @@ -17,8 +17,3 @@ import DontEditWarning from '~/components/DontEditWarning.astro' ## What went wrong? `Astro.glob()` did not return any matching files. There might be a typo in the glob pattern. - -**See Also:** -- [Astro.glob](/en/reference/api-reference/#astroglob) - - diff --git a/src/content/docs/en/reference/errors/astro-glob-used-outside.mdx b/src/content/docs/en/reference/errors/astro-glob-used-outside.mdx index 0046b3892b504..f3473054c151f 100644 --- a/src/content/docs/en/reference/errors/astro-glob-used-outside.mdx +++ b/src/content/docs/en/reference/errors/astro-glob-used-outside.mdx @@ -17,8 +17,3 @@ import DontEditWarning from '~/components/DontEditWarning.astro' ## What went wrong? `Astro.glob()` can only be used in `.astro` files. You can use [`import.meta.glob()`](https://vite.dev/guide/features.html#glob-import) instead to achieve the same result. - -**See Also:** -- [Astro.glob](/en/reference/api-reference/#astroglob) - - diff --git a/src/content/docs/en/reference/errors/content-collection-invalid-type.mdx b/src/content/docs/en/reference/errors/content-collection-invalid-type.mdx new file mode 100644 index 0000000000000..79332174c63d2 --- /dev/null +++ b/src/content/docs/en/reference/errors/content-collection-invalid-type.mdx @@ -0,0 +1,23 @@ +--- +# NOTE: This file is auto-generated from 'scripts/error-docgen.mjs' +# Do not make edits to it directly, they will be overwritten. +# Instead, change this file: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts +# Translators, please remove this note and the component. + +title: Content collection invalid type. +i18nReady: true +githubURL: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts +--- + +import DontEditWarning from '~/components/DontEditWarning.astro' + + + + +> Invalid collection type "data". Remove the type from your collection definition in your content config file. + +### What went wrong? + +Content collections should no longer have a type field. Remove this field from your content config file. + +See the [Astro 6 migration guide](/en/guides/upgrade-to/v6/#removed-legacy-content-collections) for more information. \ No newline at end of file diff --git a/src/content/docs/en/reference/errors/content-collection-missing-loader.mdx b/src/content/docs/en/reference/errors/content-collection-missing-loader.mdx new file mode 100644 index 0000000000000..224406aa602c6 --- /dev/null +++ b/src/content/docs/en/reference/errors/content-collection-missing-loader.mdx @@ -0,0 +1,24 @@ +--- +# NOTE: This file is auto-generated from 'scripts/error-docgen.mjs' +# Do not make edits to it directly, they will be overwritten. +# Instead, change this file: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts +# Translators, please remove this note and the component. + +title: Content collection missing loader. +i18nReady: true +githubURL: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts +--- + +import DontEditWarning from '~/components/DontEditWarning.astro' + + + + +> Collections must have a loader defined. Check your collection definitions in your content config file. + +### What went wrong? + +A content collection is missing a loader definition. Make sure that each collection in your content config file has a loader. + +**See Also:** +- [Content collections configuration](/en/guides/content-collections/#defining-the-collection-loader) diff --git a/src/content/docs/en/reference/errors/legacy-content-config-error.mdx b/src/content/docs/en/reference/errors/legacy-content-config-error.mdx new file mode 100644 index 0000000000000..8dcd318ea0da5 --- /dev/null +++ b/src/content/docs/en/reference/errors/legacy-content-config-error.mdx @@ -0,0 +1,26 @@ +--- +# NOTE: This file is auto-generated from 'scripts/error-docgen.mjs' +# Do not make edits to it directly, they will be overwritten. +# Instead, change this file: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts +# Translators, please remove this note and the component. + +title: Legacy content config error. +i18nReady: true +githubURL: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts +--- + +import DontEditWarning from '~/components/DontEditWarning.astro' + + + + +> Legacy content config file found. + +### What went wrong? + +A legacy content config file was found. Move the file to `src/content.config.ts` and update any collection definitions if needed. + +See the [Astro 6 migration guide](/en/guides/upgrade-to/v6/#removed-legacy-content-collections) for more information. + +**See Also:** +- [Content collections configuration](/en/guides/content-collections/#the-collection-config-file) diff --git a/src/content/docs/en/reference/experimental-flags/heading-id-compat.mdx b/src/content/docs/en/reference/experimental-flags/heading-id-compat.mdx deleted file mode 100644 index a19d1c9d01e49..0000000000000 --- a/src/content/docs/en/reference/experimental-flags/heading-id-compat.mdx +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Experimental Markdown heading ID compatibility -sidebar: - label: Markdown heading ID compatibility -i18nReady: true ---- - -import Since from '~/components/Since.astro' - -

    - -**Type:** `boolean`
    -**Default:** `false`
    - -

    - -The `experimental.headingIdCompat` flag makes the IDs generated by Astro for Markdown headings compatible with common platforms like GitHub and npm. - -To enable heading ID compatibility, set the flag to `true` in your Astro configuration: - -```js title="astro.config.mjs" ins={4-6} -import { defineConfig } from "astro/config" - -export default defineConfig({ - experimental: { - headingIdCompat: true, - } -}) -``` - -## Usage - -This experimental flag allows you to retain the trailing hyphens on the end of IDs for Markdown headings ending in special characters, creating IDs compatible with those generated by other common platforms. It requires no specific usage and only affects how Astro generates the `id` for your headings written using Markdown syntax. - -Astro, like many platforms, uses the popular [`github-slugger`](https://github.com/Flet/github-slugger) package to convert the text content of a Markdown heading to a slug to use in IDs. This experimental flag allows you to omit Astro's additional default processing step that strips a trailing hyphen from the end of IDs for headings ending in special characters. - -For example, the following Markdown heading: - -```md -## `` -``` - -will generate the following HTML in Astro by default: - -```html "picture" -

    <Picture />

    -``` - -Using `experimental.headingIdCompat`, the same Markdown will generate the following HTML, which is identical to that of platforms such as GitHub: - -```html "picture-" -

    <Picture />

    -``` - -In a future major version, Astro will switch to use the compatible ID style by default, but you can opt in to the future behavior early using the `experimental.headingIdCompat` flag. - -## Usage with `rehypeHeadingIds` plugin - -If you are [using the `rehypeHeadingIds` plugin](/en/guides/markdown-content/#heading-ids-and-plugins) directly, opt in to the compatibility mode when passing the plugin in your Astro configuration: - - -```js title="astro.config.mjs" {8} -import { defineConfig } from 'astro/config'; -import { rehypeHeadingIds } from '@astrojs/markdown-remark'; -import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source'; - -export default defineConfig({ - markdown: { - rehypePlugins: [ - [rehypeHeadingIds, { headingIdCompat: true }], - otherPluginThatReliesOnHeadingIDs, - ], - }, -}); -``` diff --git a/src/content/docs/en/reference/experimental-flags/preserve-scripts-order.mdx b/src/content/docs/en/reference/experimental-flags/preserve-scripts-order.mdx deleted file mode 100644 index 429fb416c60d5..0000000000000 --- a/src/content/docs/en/reference/experimental-flags/preserve-scripts-order.mdx +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Experimental preserve scripts order -sidebar: - label: Preserve scripts order -i18nReady: true ---- - -import Since from '~/components/Since.astro' - -

    - - **Type:** `boolean`
    - **Default:** `false`
    - -

    - -Renders multiple ` - - - -``` - -After compiling, Astro's default behavior will create an inline style where `yellow` appears first, and then `red`. This means the `red` background is applied. Similarly with the two scripts, the word `world!` is logged first, and then `hello` second: - -```css -body {background:#ff0} body {background:red} -``` - -```js -console.log("world!") -console.log("hello") -``` - -When `experimental.preserveScriptOrder` is set to `true`, the rendering order of ` - - - -``` - -Después de la compilación, el comportamiento predeterminado de Astro creará un estilo en línea donde `yellow` aparece primero, y luego `red`. Esto significa que se aplica el fondo `red`. De manera similar con los dos scripts, la palabra `world!` se registra primero, y luego `hello` en segundo lugar: - -```css -body {background:#ff0} body {background:red} -``` - -```js -console.log("world!") -console.log("hello") -``` - -Cuando `experimental.preserveScriptOrder` se establece en `true`, el orden de renderizado de las etiquetas ` - - - -``` - -Après la compilation, le comportement par défaut d'Astro crée un style en ligne où `yellow` apparaît en premier, puis `red`. Cela signifie que l'arrière-plan `red` est appliqué. De même, avec les deux scripts, le mot `world!` est affiché en premier, suivi de `hello` : - -```css -body {background:#ff0} body {background:red} -``` - -```js -console.log("world!") -console.log("hello") -``` - -Lorsque `experimental.preserveScriptOrder` est définie sur `true`, l'ordre de restitution des balises ` - - - -``` - -컴파일 후 Astro의 기본 동작은 `yellow`가 먼저 나타나고 `red`가 다음에 나타나는 인라인 스타일을 생성합니다. 이는 `red` 배경이 적용됨을 의미합니다. 두 스크립트의 경우 `world!`가 먼저 기록되고 `hello`가 다음에 기록됩니다. - -```css -body {background:#ff0} body {background:red} -``` - -```js -console.log("world!") -console.log("hello") -``` - -`experimental.preserveScriptOrder`가 `true`로 설정되면 ` - - - -``` - -在编译后，Astro 的默认行为会创建一个内联样式，其中 `yellow` 首先出现，然后是 `red`。这意味着最终应用的是 `red` 背景。类似地，对于两个脚本，会先打印 `world!`，然后是 `hello`： - -```css -body {background:#ff0} body {background:red} -``` - -```js -console.log("world!") -console.log("hello") -``` - -当 `experimental.preserveScriptOrder` 设置为 `true` 时，`