fix(docs): replace outdated Astro docs links (#15199)

ArmandPhilippot · web-flow · commit d8e64ef77ef3 · 2026-01-15T16:56:40.000+01:00
* fix: update outdated links to Astro Docs

* some were correctly redirected, but might as well use the new links
* some used the right page, but the section has been renamed or removed
* some were no longer targeting the correct page

* docs: add changeset
diff --git a/.changeset/great-jokes-enjoy.md b/.changeset/great-jokes-enjoy.md
@@ -0,0 +1,8 @@
+---
+'@astrojs/language-server': patch
+'@astrojs/netlify': patch
+'@astrojs/rss': patch
+'astro': patch
+---
+
+Fixes the links to Astro Docs so that they match the current docs structure.
diff --git a/examples/blog/src/content/blog/using-mdx.mdx b/examples/blog/src/content/blog/using-mdx.mdx
@@ -9,7 +9,7 @@ This theme comes with the [@astrojs/mdx](https://docs.astro.build/en/guides/inte
 
 ## Why MDX?
 
-MDX is a special flavor of Markdown that supports embedded JavaScript & JSX syntax. This unlocks the ability to [mix JavaScript and UI Components into your Markdown content](https://docs.astro.build/en/guides/markdown-content/#mdx-features) for things like interactive charts or alerts.
+MDX is a special flavor of Markdown that supports embedded JavaScript & JSX syntax. This unlocks the ability to [mix JavaScript and UI Components into your Markdown content](https://docs.astro.build/en/guides/integrations-guide/mdx/#mdx-in-astro) for things like interactive charts or alerts.
 
 If you have existing content authored in MDX, this integration will hopefully make migrating to Astro a breeze.
 
@@ -27,5 +27,5 @@ import HeaderLink from '../../components/HeaderLink.astro';
 ## More Links
 
 - [MDX Syntax Documentation](https://mdxjs.com/docs/what-is-mdx)
-- [Astro Usage Documentation](https://docs.astro.build/en/guides/markdown-content/#markdown-and-mdx-pages)
+- [Astro Usage Documentation](https://docs.astro.build/en/basics/astro-pages/#markdownmdx-pages)
 - **Note:** [Client Directives](https://docs.astro.build/en/reference/directives-reference/#client-directives) are still required to create interactive components. Otherwise, all components in your MDX will render as static HTML (no JavaScript) by default.
diff --git a/examples/portfolio/src/layouts/BaseLayout.astro b/examples/portfolio/src/layouts/BaseLayout.astro
@@ -1,6 +1,6 @@
 ---
 // Learn about using Astro layouts:
-// https://docs.astro.build/en/core-concepts/layouts/
+// https://docs.astro.build/en/basics/layouts/
 
 import Footer from '../components/Footer.astro';
 // Component Imports
diff --git a/examples/portfolio/src/pages/work/[...slug].astro b/examples/portfolio/src/pages/work/[...slug].astro
@@ -13,7 +13,7 @@ interface Props {
 
 // This is a dynamic route that generates a page for every Markdown file in src/content/
 // Read more about dynamic routes and this `getStaticPaths` function in the Astro docs:
-// https://docs.astro.build/en/core-concepts/routing/#dynamic-routes
+// https://docs.astro.build/en/guides/routing/#dynamic-routes
 export async function getStaticPaths() {
 	const work = await getCollection('work');
 	return work.map((entry) => ({
diff --git a/examples/with-mdx/src/pages/index.mdx b/examples/with-mdx/src/pages/index.mdx
@@ -18,7 +18,7 @@ Published on: {new Intl.DateTimeFormat('en', {dateStyle: 'long'}).format(publish
 
 ## Syntax highlighting
 
-We also support syntax highlighting in MDX out-of-the-box! This example uses the default [Shiki](https://shiki.style) theme. See the [MDX integration docs](https://docs.astro.build/en/guides/integrations-guide/mdx/#syntax-highlighting) for configuration options.
+We also support syntax highlighting in MDX out-of-the-box! This example uses the default [Shiki](https://shiki.style) theme. See the [MDX integration docs](https://docs.astro.build/en/guides/integrations-guide/mdx/#configuration) for configuration options.
 
 ```astro
 ---
diff --git a/examples/with-nanostores/README.md b/examples/with-nanostores/README.md
@@ -8,4 +8,4 @@ npm create astro@latest -- --template with-nanostores
 [![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/astro/tree/latest/examples/with-nanostores)
 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/withastro/astro?devcontainer_path=.devcontainer/with-nanostores/devcontainer.json)
 
-This example showcases using [`nanostores`](https://github.com/nanostores/nanostores) to provide shared state between components of any framework. [**Read our documentation on sharing state**](https://docs.astro.build/en/core-concepts/sharing-state/) for a complete breakdown of this project, along with guides to use React, Vue, Svelte, or Solid!
+This example showcases using [`nanostores`](https://github.com/nanostores/nanostores) to provide shared state between components of any framework. [**Read our documentation on sharing state**](https://docs.astro.build/en/recipes/sharing-state-islands/) for a complete breakdown of this project, along with guides to use React, Vue, Svelte, or Solid!
diff --git a/packages/astro-rss/README.md b/packages/astro-rss/README.md
@@ -26,7 +26,7 @@ The `<description>` attribute of your RSS feed's output xml.
 
 Type: `string (required)`
 
-The base URL to use when generating RSS item links. We recommend using the [endpoint context object](https://docs.astro.build/en/reference/api-reference/#contextsite), which includes the `site` configured in your project's `astro.config.*`:
+The base URL to use when generating RSS item links. We recommend using the [endpoint context object](https://docs.astro.build/en/reference/api-reference/#site), which includes the `site` configured in your project's `astro.config.*`:
 
 ```ts
 import rss from '@astrojs/rss';
@@ -87,7 +87,7 @@ Type: `string (optional)`
 
 The full text content of the item suitable for presentation as HTML. If used, you should also provide a short article summary in the `description` field.
 
-To render Markdown content from a glob result or from a content collection, see the [content rendering guide](https://docs.astro.build/en/guides/rss/#including-full-post-content).
+To render Markdown content from a glob result or from a content collection, see the [content rendering guide](https://docs.astro.build/en/recipes/rss/#including-full-post-content).
 
 #### `categories`
 
@@ -304,10 +304,8 @@ MIT
 
 Copyright (c) 2023–present [Astro][astro]
 
-[docs]: https://docs.astro.build/en/guides/rss/
-[astro-endpoints]: https://docs.astro.build/en/core-concepts/astro-pages/#non-html-pages
+[docs]: https://docs.astro.build/en/recipes/rss/
 [astro]: https://astro.build/
-[docs]: https://docs.astro.build/en/guides/integrations-guide/alpinejs/
 [contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md
 [coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md
 [community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md
diff --git a/packages/astro-rss/src/index.ts b/packages/astro-rss/src/index.ts
@@ -13,7 +13,7 @@ export type RSSOptions = {
 	description: z.infer<typeof rssOptionsValidator>['description'];
 	/**
 	 * Specify the base URL to use for RSS feed links.
-	 * We recommend using the [endpoint context object](https://docs.astro.build/en/reference/api-reference/#contextsite),
+	 * We recommend using the [endpoint context object](https://docs.astro.build/en/reference/api-reference/#site),
 	 * which includes the `site` configured in your project's `astro.config.*`
 	 */
 	site: z.infer<typeof rssOptionsValidator>['site'] | URL;
@@ -72,7 +72,7 @@ const rssOptionsValidator = z.object({
 			if (!Array.isArray(items)) {
 				console.warn(
 					colors.yellow(
-						'[RSS] Passing a glob result directly has been deprecated. Please migrate to the `pagesGlobToRssItems()` helper: https://docs.astro.build/en/guides/rss/',
+						'[RSS] Passing a glob result directly has been deprecated. Please migrate to the `pagesGlobToRssItems()` helper: https://docs.astro.build/en/recipes/rss/',
 					),
 				);
 				return pagesGlobToRssItems(items);
@@ -116,7 +116,7 @@ async function validateRssOptions(rssOptions: RSSOptions) {
 					return [
 						message,
 						`The \`items\` property requires at least the \`title\` or \`description\` key. They must be properly typed, as well as \`pubDate\` and \`link\` keys if provided.`,
-						`Check your collection's schema, and visit https://docs.astro.build/en/guides/rss/#generating-items for more info.`,
+						`Check your collection's schema, and visit https://docs.astro.build/en/recipes/rss/#generating-items for more info.`,
 					].join('\n');
 				}
 
@@ -133,7 +133,7 @@ export function pagesGlobToRssItems(items: GlobResult): Promise<ValidatedRSSFeed
 			const { url, frontmatter } = await getInfo();
 			if (url === undefined || url === null) {
 				throw new Error(
-					`[RSS] You can only glob entries within 'src/pages/' when passing import.meta.glob() directly. Consider mapping the result to an array of RSSFeedItems. See the RSS docs for usage examples: https://docs.astro.build/en/guides/rss/#2-list-of-rss-feed-objects`,
+					`[RSS] You can only glob entries within 'src/pages/' when passing import.meta.glob() directly. Consider mapping the result to an array of RSSFeedItems. See the RSS docs for usage examples: https://docs.astro.build/en/recipes/rss/`,
 				);
 			}
 			const parsedResult = rssSchema
diff --git a/packages/astro/env.d.ts b/packages/astro/env.d.ts
@@ -11,7 +11,7 @@ type Astro = import('./dist/types/public/context.js').AstroGlobal;
 /**
  * Astro global available in all contexts in .astro files
  *
- * [Astro documentation](https://docs.astro.build/en/reference/api-reference/#astro-global)
+ * [Astro documentation](https://docs.astro.build/en/reference/api-reference/)
  */
 declare const Astro: Readonly<Astro>;
 
diff --git a/packages/astro/src/core/build/generate.ts b/packages/astro/src/core/build/generate.ts
@@ -452,14 +452,14 @@ function getInvalidRouteSegmentError(
 	const invalidParam = /^Expected "([^"]+)"/.exec(e.message)?.[1];
 	const received = invalidParam ? staticPath.params[invalidParam] : undefined;
 	let hint =
-		'Learn about dynamic routes at https://docs.astro.build/en/core-concepts/routing/#dynamic-routes';
+		'Learn about dynamic routes at https://docs.astro.build/en/guides/routing/#dynamic-routes';
 	if (invalidParam && typeof received === 'string') {
 		const matchingSegment = route.segments.find(
 			(segment) => segment[0]?.content === invalidParam,
 		)?.[0];
 		const mightBeMissingSpread = matchingSegment?.dynamic && !matchingSegment?.spread;
 		if (mightBeMissingSpread) {
-			hint = `If the param contains slashes, try using a rest parameter: **[...${invalidParam}]**. Learn more at https://docs.astro.build/en/core-concepts/routing/#dynamic-routes`;
+			hint = `If the param contains slashes, try using a rest parameter: **[...${invalidParam}]**. Learn more at https://docs.astro.build/en/guides/routing/#dynamic-routes`;
 		}
 	}
 	return new AstroError({
diff --git a/packages/astro/src/types/public/common.ts b/packages/astro/src/types/public/common.ts
@@ -5,7 +5,7 @@ import type { APIContext } from './context.js';
 /**
  * getStaticPaths() options
  *
- * [Astro Reference](https://docs.astro.build/en/reference/api-reference/#getstaticpaths)
+ * [Astro Reference](https://docs.astro.build/en/reference/routing-reference/#getstaticpaths)
  */
 export interface GetStaticPathsOptions {
 	paginate: PaginateFunction;
@@ -24,7 +24,7 @@ export type GetStaticPathsResultKeyed = GetStaticPathsResult & {
 /**
  * Return an array of pages to generate for a [dynamic route](https://docs.astro.build/en/guides/routing/#dynamic-routes). (**SSG Only**)
  *
- * [Astro Reference](https://docs.astro.build/en/reference/api-reference/#getstaticpaths)
+ * [Astro Reference](https://docs.astro.build/en/reference/routing-reference/#getstaticpaths)
  */
 export type GetStaticPaths = (
 	options: GetStaticPathsOptions,
@@ -33,7 +33,7 @@ export type GetStaticPaths = (
 /**
  * paginate() Options
  *
- * [Astro reference](https://docs.astro.build/en/reference/api-reference/#paginate)
+ * [Astro reference](https://docs.astro.build/en/reference/routing-reference/#paginate)
  */
 export interface PaginateOptions<PaginateProps extends Props, PaginateParams extends Params> {
 	/** the number of items per-page (default: `10`) */
@@ -47,7 +47,7 @@ export interface PaginateOptions<PaginateProps extends Props, PaginateParams ext
 /**
  * Represents a single page of data in a paginated collection
  *
- * [Astro reference](https://docs.astro.build/en/reference/api-reference/#the-pagination-page-prop)
+ * [Astro reference](https://docs.astro.build/en/reference/routing-reference/#the-pagination-page-prop)
  */
 export interface Page<T = any> {
 	/** result */
diff --git a/packages/astro/src/types/public/context.ts b/packages/astro/src/types/public/context.ts
@@ -343,7 +343,7 @@ export interface AstroSharedContext<
 	/**
 	 * An object containing the values of dynamic route segments matched for a request.
 	 *
-	 * In static builds, this will be the `params` returned by [`getStaticPaths()`](https://docs.astro.build/en/reference/api-reference/#getstaticpaths). With on-demand rendering, `params` can be any value matching the path segments in the dynamic route pattern.
+	 * In static builds, this will be the `params` returned by [`getStaticPaths()`](https://docs.astro.build/en/reference/routing-reference/#getstaticpaths). With on-demand rendering, `params` can be any value matching the path segments in the dynamic route pattern.
 	 *
 	 * ## Example
 	 *
@@ -368,7 +368,7 @@ export interface AstroSharedContext<
 	params: Params;
 
 	/**
-	 * An object containing any values that have been passed as component attributes. In static builds, this can also be the `props` returned by [`getStaticPaths()`](https://docs.astro.build/en/reference/api-reference/#getstaticpaths).
+	 * An object containing any values that have been passed as component attributes. In static builds, this can also be the `props` returned by [`getStaticPaths()`](https://docs.astro.build/en/reference/routing-reference/#getstaticpaths).
 	 *
 	 * ## Example
 	 *
@@ -613,7 +613,7 @@ export interface AstroSharedContext<
 	 * - The value when rendering `src/pages/blog/[slug].astro` will be `/blog/[slug]`.
 	 * - The value when rendering `src/pages/[...path].astro` will be `/[...path]`.
 	 *
-	 * [Astro reference](https://docs.astro.build/en/reference/api-reference/#routepattern)
+	 * [Astro reference](https://docs.astro.build/en/reference/routing-reference/#routepattern)
 	 */
 	routePattern: string;
 }
diff --git a/packages/integrations/netlify/README.md b/packages/integrations/netlify/README.md
@@ -1,6 +1,6 @@
 # @astrojs/netlify
 
-This adapter allows Astro to deploy your [`hybrid` or `server` rendered site](https://docs.astro.build/en/core-concepts/rendering-modes/#on-demand-rendered) to [Netlify](https://www.netlify.com/).
+This adapter allows Astro to deploy your [`hybrid` or `server` rendered site](https://docs.astro.build/en/guides/on-demand-rendering/) to [Netlify](https://www.netlify.com/).
 
 ## Documentation
 
diff --git a/packages/language-tools/language-server/src/plugins/html-data.ts b/packages/language-tools/language-server/src/plugins/html-data.ts
@@ -30,7 +30,7 @@ export const astroElements = newHTMLDataProvider('astro-elements', {
 			references: [
 				{
 					name: 'Astro reference',
-					url: 'https://docs.astro.build/en/core-concepts/astro-components/#slots',
+					url: 'https://docs.astro.build/en/basics/astro-components/#slots',
 				},
 			],
 			attributes: [
@@ -41,7 +41,7 @@ export const astroElements = newHTMLDataProvider('astro-elements', {
 					references: [
 						{
 							name: 'Astro reference',
-							url: 'https://docs.astro.build/en/core-concepts/astro-components/#named-slots',
+							url: 'https://docs.astro.build/en/basics/astro-components/#named-slots',
 						},
 					],
 				},
@@ -100,7 +100,7 @@ export const astroElements = newHTMLDataProvider('astro-elements', {
 					references: [
 						{
 							name: 'Astro reference',
-							url: 'https://docs.astro.build/en/guides/view-transitions/#script-behavior',
+							url: 'https://docs.astro.build/en/guides/view-transitions/#data-astro-rerun',
 						},
 					],
 				},
diff --git a/packages/language-tools/language-server/src/plugins/typescript-addons/snippets.ts b/packages/language-tools/language-server/src/plugins/typescript-addons/snippets.ts
@@ -35,7 +35,7 @@ export function getSnippetCompletions(frontmatter: FrontmatterStatus): Completio
 				value: [
 					'Create a new getStaticPaths function.',
 					'\n',
-					'[Astro reference](https://docs.astro.build/en/reference/api-reference/#getstaticpaths)',
+					'[Astro reference](https://docs.astro.build/en/reference/routing-reference/#getstaticpaths)',
 				].join('\n'),
 			},
 			insertText:
@@ -53,9 +53,9 @@ export function getSnippetCompletions(frontmatter: FrontmatterStatus): Completio
 			documentation: {
 				kind: 'markdown',
 				value: [
-					'Add prerender export. When [using server-side rendering](https://docs.astro.build/en/guides/server-side-rendering/#enabling-ssr-in-your-project), this value will be used to determine whether to prerender the page or not.',
+					'Add prerender export. When [using server-side rendering](https://docs.astro.build/en/guides/on-demand-rendering/#enabling-on-demand-rendering), this value will be used to determine whether to prerender the page or not.',
 					'\n',
-					'[Astro reference](https://docs.astro.build/en/guides/server-side-rendering/#configuring-individual-routes)',
+					'[Astro reference](https://docs.astro.build/en/reference/routing-reference/#prerender)',
 				].join('\n'),
 			},
 			insertText: 'export const prerender = ${1|true,false|}',
diff --git a/packages/language-tools/language-server/types/env.d.ts b/packages/language-tools/language-server/types/env.d.ts
@@ -1,7 +1,7 @@
 /**
  * Astro global available in all contexts in .astro files
  *
- * [Astro documentation](https://docs.astro.build/reference/api-reference/#astro-global)
+ * [Astro documentation](https://docs.astro.build/en/reference/api-reference/)
  */
 declare const Astro: any;
 declare const Fragment: any;

Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,7 @@ type Astro = import('./dist/types/public/context.js').AstroGlobal;`
`11`	`11`	`/**`
`12`	`12`	`* Astro global available in all contexts in .astro files`
`13`	`13`	`*`
`14`		`- * [Astro documentation](https://docs.astro.build/en/reference/api-reference/#astro-global)`
	`14`	`+ * [Astro documentation](https://docs.astro.build/en/reference/api-reference/)`
`15`	`15`	`*/`
`16`	`16`	`declare const Astro: Readonly<Astro>;`
`17`	`17`