5.0.0 beta docs

.vscode/settings.json

@@ -9,5 +9,8 @@
   },
   "[typescript]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[mdx]": {
+    "files.trimTrailingWhitespace": false,
   }
 }

CONTRIBUTING.md

@@ -146,7 +146,7 @@ You can install and run the project locally using [pnpm](https://pnpm.io/). Head
 ```shell
 pnpm install
 
-pnpm start
+pnpm run dev
 ```
 
 If you’re copying these instructions, remember to [configure this project as a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork).

astro.config.ts

@@ -38,13 +38,13 @@ export default defineConfig({
 				Pagination: './src/components/starlight/Pagination.astro',
 				Footer: './src/components/starlight/Footer.astro',
 				SiteTitle: './src/components/starlight/SiteTitle.astro',
-				Search: './src/components/starlight/Search.astro',
+				// Search: './src/components/starlight/Search.astro',
 				Sidebar: './src/components/starlight/Sidebar.astro',
 				MobileMenuFooter: './src/components/starlight/MobileMenuFooter.astro',
 				PageTitle: './src/components/starlight/PageTitle.astro',
 			},
 			editLink: {
-				baseUrl: 'https://github.com/withastro/docs/edit/main',
+				baseUrl: 'https://github.com/withastro/docs/edit/5.0.0-beta',
 			},
 			defaultLocale: 'en',
 			locales: makeLocalesConfig(),
@@ -53,7 +53,7 @@ export default defineConfig({
 				github: 'https://github.com/withastro/astro',
 				discord: 'https://astro.build/chat',
 			},
-			pagefind: false,
+			// pagefind: false,
 			head: [
 				// Add ICO favicon fallback for Safari.
 				{

public/_redirects

@@ -7,7 +7,7 @@
 /:lang/core-concepts/astro-pages                     /:lang/basics/astro-pages/
 /:lang/core-concepts/layouts                         /:lang/basics/layouts/
 /:lang/core-concepts/astro-syntax                    /:lang/basics/astro-syntax/
-/:lang/core-concepts/rendering-modes                 /:lang/basics/rendering-modes/
+/:lang/core-concepts/rendering-modes                 /:lang/guides/on-demand-rendering/
 /:lang/core-concepts/routing                         /:lang/guides/routing/
 /:lang/core-concepts/endpoints                       /:lang/guides/endpoints/
 /:lang/core-concepts/framework-components            /:lang/guides/framework-components/
@@ -28,6 +28,9 @@
 /:lang/recipes/studio                                /:lang/guides/astro-db/
 /:lang/recipes                                       /:lang/community-resources/content/
 /:lang:/reference/api-reference/#astrocanonicalurl   /:lang:/reference/api-reference/#astrourl
+/:lang/basics/rendering-modes/                       /:lang/guides/on-demand-rendering/
+/:lang/guides/server-side-rendering/                 /:lang/guides/on-demand-rendering/
+/:lang/guides/content/                               /:lang/guides/markdown-content/
 
 # Very old docs site redirects
 # Once upon a time these URLs existed, so we try to keep them meaning something.

scripts/docgen.mjs

@@ -11,12 +11,12 @@ const STUB = ``; // fs.readFileSync('/PATH/TO/MONOREPO/astro/packages/astro/src/
 const HEADER = `---
 # NOTE: This file is auto-generated from 'scripts/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/%40types/astro.ts
+# Instead, change this file: https://github.com/withastro/astro/blob/main/packages/astro/src/types/public/config.ts
 # Translators, please remove this note and the <DontEditWarning/> component. 
 
 title: Configuration Reference
 i18nReady: true
-githubURL: https://github.com/withastro/astro/blob/main/packages/astro/src/%40types/astro.ts
+githubURL: https://github.com/withastro/astro/blob/main/packages/astro/src/types/public/config.ts
 ---
 
 import Since from '~/components/Since.astro'
@@ -52,7 +52,7 @@ export async function run() {
 	const inputBuffer =
 		STUB ||
 		(await fetch(
-			`https://raw.githubusercontent.com/${sourceRepo}/${sourceBranch}/packages/astro/src/%40types/astro.ts`
+			`https://raw.githubusercontent.com/${sourceRepo}/${sourceBranch}/packages/astro/src/types/public/config.ts`
 		).then((r) => r.text()));
 
 	console.timeEnd(task);

src/components/SourcePR.astro

@@ -0,0 +1,25 @@
+---
+import { Icon } from '@astrojs/starlight/components';
+const { number, title } = Astro.props
+---
+
+<div class="source">
+	<Icon class="icon" name="github" />
+	<a href=`https://github.com/withastro/astro/pull/${number}`>Implementation PR: {title} (#{number})<span><slot /></span></a>
+</div>
+
+<style>
+	.source {
+		display: flex;
+		gap: 0.5rem;
+		align-items: flex-start;
+	}
+	.icon {
+		--icon-size: 1.5rem;
+		font-size: var(--icon-size);
+		flex-shrink: 0;
+		/* Align to the middle of the first line of text. */
+		margin-block: calc((var(--sl-line-height) * 1rem - var(--icon-size)) / 2);
+		color: var(--sl-color-text-accent);
+	}
+</style>

src/components/starlight/SiteTitle.astro

@@ -2,6 +2,7 @@
 import logo from '~/assets/astro-logo.svg?raw';
 import docs from '~/assets/docs.svg?raw';
 import type { Props } from '@astrojs/starlight/props';
+import Badge from '../Badge.astro';
 
 const main = 'https://astro.build/';
 const self = '/' + (Astro.props.locale || 'en') + '/getting-started/';
@@ -10,6 +11,7 @@ const self = '/' + (Astro.props.locale || 'en') + '/getting-started/';
 <span class="site-title sl-flex">
 	<a class="astro-logo" href={main} set:html={logo} aria-label="Astro" />
 	<a class="docs-logo" href={self} set:html={docs} aria-label="Docs" />
+	<Badge text="v5-beta" style={{ alignSelf: 'center', whiteSpace: 'nowrap' }} />
 </span>
 
 <style>

src/content/docs/ar/concepts/why-astro.mdx

@@ -14,7 +14,7 @@ i18nReady: true
 
 - **[جزر](/ar/concepts/islands/):** تم تحسين بنية الويب القائمة على المكونات اعتمادا على المحتوى.
 - **[UI-agnostic](/ar/guides/framework-components/):** يشمل React، Preact، Svelte، Vue، Solid، Lit، HTMX، مكونات الويب، و اكثر.
-- **[الخادم أولا](/ar/basics/rendering-modes/):** يجنبك التكلفة الكبيرة للعرض على أجهزة زوارك.
+- **[الخادم أولا](/ar/guides/on-demand-rendering/):** يجنبك التكلفة الكبيرة للعرض على أجهزة زوارك.
 - **[صفر جافاسكريبت ، افتراضيا](/ar/basics/astro-components/):** أقل ما يمكن من جافاسكريبت من جانب العميل لتجنب إبطاء موقعك.
 - **[مجموعات المحتوى](/ar/guides/content-collections/):** تنظيم والتحقق من صحة وتوفير سلامة نوع TypeScript لمحتوى الماركداون الخاص بك.
 - **[قابل للتخصيص](/ar/guides/integrations-guide/):** Tailwind و MDX  ومئات الإضافات للإختيار من بينها.
@@ -41,7 +41,7 @@ i18nReady: true
 
 ### الخادم أولًا
 
-**يستثمر أسترو [تقديم الخادم](/ar/basics/rendering-modes/) على عرض جانب العميل في المتصفح قدر الإمكان.** هذا هو نفس النهج الذي تستخدمه الأطر التقليدية منذ عقود من جانب الخادم :  ،Ruby on Rails، Laravel ،WordPress PHP  وما إلى ذلك.. .لكنك لا تحتاج إلى تعلم لغة أخرى لإلغاء ذلك. مع أسترو، لا يزال كل شيء مجرد HTML و CSS و JavaScript (أو TypeScript ، إذا كنت تفضله).
+**يستثمر أسترو[تقديم الخادم على عرض جانب العميل في المتصفح قدر الإمكان.** هذا هو نفس النهج الذي تستخدمه الأطر التقليدية منذ عقود من جانب الخادم :  ،Ruby on Rails، Laravel ،WordPress PHP  وما إلى ذلك.. .لكنك لا تحتاج إلى تعلم لغة أخرى لإلغاء ذلك. مع أسترو، لا يزال كل شيء مجرد HTML و CSS و JavaScript (أو TypeScript ، إذا كنت تفضله).
 
 يتناقض هذا النهج مع أطر عمل جافاسكريبت الحديثة الأخرى مثل Next.js و Sveltekit و Nuxt و Remix وغيرها. تم تصميم هذه الأطر لتقديم موقع الويب الخاص بك من جانب العميل وتتضمن عرضًا من جانب الخادم بشكل أساسي لمعالجة مخاوف الأداء.تم تسمية هذا النهج بتطبيق **أحادي الصفحة (SPA)** ، على عكس نهج أسترو **متعدد الصفحات (MPA)**.
 

src/content/docs/ar/guides/integrations-guide/sitemap.mdx

@@ -18,7 +18,7 @@ import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
 
 باستخدام أسترو Sitemap ، لا داعي للقلق بشأن إنشاء ملف XML هذا بنفسك: سوف يمحص الدمج من أسترو ل Sitemap على طرقك )(routes) المولدة بشكل ثابت وإنشاء ملف Sitemap ، بما في ذلك [الطرق الدينامية](/ar/guides/routing/#dynamic-routes) مثل `[...slug]` أو `src/pages/[lang]/[version]/info.astro` المولدة عبر `()getStaticPaths`.
 
- هذا الدمج من أسترو لا يمكن أن يولد بيانات Sitemap للطرق الديناميكية [SSR mode](/ar/basics/rendering-modes/#on-demand-rendered).
+ هذا الدمج من أسترو لا يمكن أن يولد بيانات Sitemap للطرق الديناميكية [SSR mode](/ar/guides/on-demand-rendering/).
 
 ## تثبيت
 

src/content/docs/de/guides/cms.mdx

@@ -33,4 +33,4 @@ Einige Headless CMS, wie Storyblok, bieten eine Astro-[Integration](/de/guides/i
 
 ## Kann ich Astro ohne CMS nutzen?
 
-Ja! Astro bietet eingebaute Möglichkeiten, [Inhalte zu erstellen](/de/guides/content/), darunter auch die Unterstützung von Markdown-Seiten.
+Ja! Astro bietet eingebaute Möglichkeiten, Inhalte zu erstellen, darunter auch die Unterstützung von Markdown-Seiten.

src/content/docs/de/guides/upgrade-to/v3.mdx

@@ -362,7 +362,7 @@ Astro v3.0 deklariert dieses Feature als veraltet und bevorzugt die Verwendung v
 
 #### Was soll ich tun?
 
-Um weiterhin einige Seiten in deinem Projekt als Entwürfe zu kennzeichnen, [verwende stattdessen Inhalts-Sammlungen](/de/guides/content-collections/#migrating-from-file-based-routing) und [filtere Seiten manuell aus](/de/guides/content-collections/#filtering-collection-queries), indem du die `draft: true`-Frontmatter-Eigenschaft verwendest.
+Um weiterhin einige Seiten in deinem Projekt als Entwürfe zu kennzeichnen, [verwende stattdessen Inhalts-Sammlungen](/de/guides/content-collections/) und [filtere Seiten manuell aus](/de/guides/content-collections/#filtering-collection-queries), indem du die `draft: true`-Frontmatter-Eigenschaft verwendest.
 
 ### Veraltet: Rückgabe eines einfachen Objekts an Endpunkten
 

src/content/docs/de/reference/api-reference.mdx

@@ -848,7 +848,7 @@ const { Content, headings, remarkPluginFrontmatter } = await entry.render();
 ---
 ```
 
-[Siehe die Anleitungs für Inhaltssammlungen](/de/guides/content-collections/#rendering-content-to-html) für ein Anwendungsbeispiel.
+[Siehe die Anleitungs für Inhaltssammlungen](/de/guides/content-collections/#rendering-body-content) für ein Anwendungsbeispiel.
 
 ## `import.meta`
 

src/content/docs/en/basics/astro-components.mdx

@@ -1,17 +1,18 @@
 ---
 title: Components
-description: An intro to the .astro component syntax.
+description: An introduction to Astro components.
 i18nReady: true
 ---
 
 **Astro components** are the basic building blocks of any Astro project. They are HTML-only templating components with no client-side runtime. You can spot an Astro component by its file extension: `.astro`.
 
-Astro components are extremely flexible. Often, an Astro component will contain some **reusable UI on the page**, like a header or a profile card. At other times, an Astro component may contain a smaller snippet of HTML, like a collection of common `<meta>` tags that make SEO easy to work with. Astro components can even contain an entire page layout.
+Astro components are extremely flexible. An Astro component can be as small as a snippet of HTML, like a collection of common `<meta>` tags that make SEO easy to work with. Components can be reusable UI elements, like a header or a profile card. Astro components can even contain an entire page layout or, when located in the special `src/pages/` folder, be an entire page itself.
 
-The most important thing to know about Astro components is that they **don't render on the client**. They render to HTML either at build-time or on-demand using [server-side rendering (SSR)](/en/guides/server-side-rendering/). You can include JavaScript code inside of your component frontmatter, and all of it will be stripped from the final page sent to your users' browsers. The result is a faster site, with zero JavaScript footprint added by default.
+The most important thing to know about Astro components is that they **don't render on the client**. They render to HTML either at build-time or on-demand. You can include JavaScript code inside of your component frontmatter, and all of it will be stripped from the final page sent to your users' browsers. The result is a faster site, with zero JavaScript footprint added by default.
 
-When your Astro component does need client-side interactivity, you can add [standard HTML `<script>` tags](/en/guides/client-side-scripts/) or [UI Framework components](/en/guides/framework-components/#hydrating-interactive-components).
+When your Astro component does need client-side interactivity, you can add [standard HTML `<script>` tags](/en/guides/client-side-scripts/) or [UI Framework components](/en/guides/framework-components/#hydrating-interactive-components) as "client islands".
 
+For components that need to render personalized or dynamic content, you can defer their server rendering by adding a [server directive](/en/reference/directives-reference/#server-directives). These "server islands" will render their content when it is available, without delaying the entire page load.
 
 ## Component Structure
 
@@ -69,6 +70,7 @@ However, [Astro's component template syntax](/en/basics/astro-syntax/) also supp
 ---
 // Your component script here!
 import Banner from '../components/Banner.astro';
+import Avatar from '../components/Avatar.astro';
 import ReactPokemonComponent from '../components/ReactPokemonComponent.jsx';
 const myFavoritePokemon = [/* ... */];
 const { title } = Astro.props;
@@ -82,6 +84,11 @@ const { title } = Astro.props;
 <!-- Use props and other variables from the component script: -->
 <p>{title}</p>
 
+<!-- Delay component rendering and provide fallback loading content: -->
+<Avatar server:defer>
+  <svg slot="fallback" class="generic-avatar" transition:name="avatar">...</svg>
+</Avatar>
+
 <!-- Include other UI framework components with a `client:` directive to hydrate: -->
 <ReactPokemonComponent client:visible />
 
@@ -371,7 +378,6 @@ import HomeLayout from '../layouts/HomeLayout.astro';
 </HomeLayout>
 ```
 
-
 ## HTML Components
 
 Astro supports importing and using `.html` files as components or placing these files within the `src/pages/` subdirectory as pages. You may want to use HTML components if you're reusing code from an existing site built without a framework, or if you want to ensure that your component has no dynamic features.

src/content/docs/en/basics/astro-pages.mdx

@@ -1,6 +1,6 @@
 ---
 title: Pages
-description: An introduction to Astro pages
+description: An introduction to Astro pages.
 i18nReady: true
 ---
 
@@ -104,7 +104,7 @@ This will build to a `404.html` page. Most [deploy services](/en/guides/deploy/)
 
 ## Custom 500 Error Page
 
-For a custom 500 error page to show for pages that are [rendered on demand](/en/guides/server-side-rendering/#enable-on-demand-server-rendering), create the file `src/pages/500.astro`. This custom page is not available for prerendered pages and can't be prerendered.
+For a custom 500 error page to show for pages that are [rendered on demand](/en/guides/on-demand-rendering/), create the file `src/pages/500.astro`. This custom page is not available for prerendered pages and can't be prerendered.
 
 If an error occurs rendering this page, your host's default 500 error page will be shown to your visitor.
 

src/content/docs/en/basics/astro-syntax.mdx

@@ -1,6 +1,6 @@
 ---
 title: Astro Syntax
-description: An intro to the .astro component syntax.
+description: An introducton to the .astro component syntax.
 i18nReady: true
 ---
 

src/content/docs/en/basics/layouts.mdx

@@ -1,6 +1,6 @@
 ---
 title: Layouts
-description: An intro to layouts, a type of Astro component that is shared between pages for common layouts.
+description: An introduction to layouts in Astro.
 i18nReady: true
 ---
 
@@ -100,7 +100,9 @@ const { title, description, publishDate, viewCount } = Astro.props;
 
 Page layouts are especially useful for individual Markdown pages which otherwise would not have any page formatting. 
 
-Astro provides a special `layout` frontmatter property to specify which `.astro` component to use as the page layout. By default, this specified component can automatically access data from the Markdown file.
+Astro provides a special `layout` frontmatter property intended for [individual `.md` files located within `src/pages/` using file-based routing](/en/guides/markdown-content/#individual-markdown-pages) to specify which `.astro` component to use as the page layout. This component allows you to provide `<head>` content like meta tags (e.g. `<meta charset="utf-8">`) and styles for the Markdown page. By default, this specified component can automatically access data from the Markdown file.
+
+This is not recognized as a special property when using [content collections](/en/guides/content-collections/) to query and render your content.
 
 ```markdown title="src/pages/page.md" {2} 
 ---
@@ -130,6 +132,8 @@ const { frontmatter } = Astro.props;
 <html>
   <head>
     <!-- Add other Head elements here, like styles and meta tags. -->
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta charset="utf-8">
     <title>{frontmatter.title}</title>
   </head>
   <body>
@@ -161,6 +165,7 @@ const { frontmatter, url } = Astro.props;
 ---
 <html>
   <head>
+    <meta charset="utf-8">
     <link rel="canonical" href={new URL(url, Astro.site).pathname}>
     <title>{frontmatter.title}</title>
   </head>
@@ -183,7 +188,7 @@ A Markdown layout will have access to the following information via `Astro.props
   - **`frontmatter.url`** - The same as the top-level `url` property.
 - **`headings`** - A list of headings (`h1 -> h6`) in the Markdown or MDX document with associated metadata. This list follows the type: `{ depth: number; slug: string; text: string }[]`.
 - **`rawContent()`** - A function that returns the raw Markdown document as a string.
-- **`compiledContent()`** - A function that returns the Markdown document compiled to an HTML string.
+- **`compiledContent()`** - An async function that returns the Markdown document compiled to an HTML string.
 
 :::note
 A Markdown layout will have access to all the Markdown file's [available properties](/en/guides/markdown-content/#available-properties) from `Astro.props` **with two key differences:**
@@ -223,13 +228,23 @@ Then, your values are available to you through `Astro.props` in your layout, and
 ---
 const { title, fancyJsHelper } = Astro.props;
 ---
-<!-- -->
-<h1>{title}</h1>
-<slot /> <!-- your content is injected here -->
-<p>{fancyJsHelper()}</p>
-<!-- -->
+<html>
+  <head>
+    <!-- -->
+    <meta charset="utf-8">
+  </head>
+  <body>
+    <!-- -->
+    <h1>{title}</h1>
+    <slot /> <!-- your content is injected here -->
+    <p>{fancyJsHelper()}</p>
+    <!-- -->
+  </body>
+</html>
 ```
 
+When using any layout (either through the frontmatter `layout` property or by importing a layout), you must include the `<meta charset="utf-8">` tag in your layout as Astro will no longer add it automatically to your MDX page.
+
 <ReadMore>Learn more about Astro’s Markdown and MDX support in our [Markdown guide](/en/guides/markdown-content/).</ReadMore>
 
 ## Nesting Layouts