5.0.0 beta docs

.vscode/settings.json

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

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/basics/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/basics/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/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. 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} 
 ---
@@ -183,7 +185,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:**

src/content/docs/en/basics/project-structure.mdx

@@ -1,6 +1,6 @@
 ---
 title: Project Structure
-description: Learn how to structure a project with Astro.
+description: An introducton to Astro's basic project structure.
 i18nReady: true
 ---
 import { FileTree } from '@astrojs/starlight/components';
@@ -74,7 +74,7 @@ This is a common convention in Astro projects, but it is not required. Feel free
 
 ### `src/content`
 
-The `src/content/` directory is reserved to store [content collections](/en/guides/content-collections/) and an optional collections configuration file. No other files are allowed inside this folder.
+The `src/content/` directory is reserved for [content collections](/en/guides/content-collections/).
 
 ### `src/layouts`
 

src/content/docs/en/basics/rendering-modes.mdx

@@ -34,15 +34,15 @@ Astro's default `static` mode is a powerful, modern-feeling choice for content-h
 
 ### On-demand rendered
 
-With [an SSR adapter](/en/guides/server-side-rendering/), Astro's other two output modes can be configured to enable **on-demand rendering of some or all of your pages, routes or API endpoints**:
+With [an SSR adapter](/en/guides/on-demand-rendering/), Astro's other two output modes can be configured to enable **on-demand rendering of some or all of your pages, routes or API endpoints**:
   - __`output: 'server'`__ for highly dynamic sites with most or all on-demand routes.
   - __`output: 'hybrid'`__ for mostly static sites with some on-demand routes. 
 
 Since they are generated per visit, these routes can be customized for each viewer. For example, a page rendered on demand can show a logged-in user their account information or display freshly updated data without requiring a full-site rebuild. On-demand rendering on the server at request time is also known as **server-side rendering (SSR)**.
 
-<ReadMore>Read more about [features available to you with on-demand rendering and an adapter](/en/guides/server-side-rendering/#on-demand-rendering-features), such as cookies, Response and Request objects, HTML streaming, and more.</ReadMore>
+<ReadMore>Read more about [features available to you with on-demand rendering and an adapter](/en/guides/on-demand-rendering/#on-demand-rendering-features), such as cookies, Response and Request objects, HTML streaming, and more.</ReadMore>
 
-[Consider enabling `server` or `hybrid` mode](/en/guides/server-side-rendering/#enable-on-demand-server-rendering) in your Astro project if you need the following:
+[Consider enabling `server` or `hybrid` mode](/en/guides/on-demand-rendering/) in your Astro project if you need the following:
 
 - **API endpoints**: Create specific pages that function as API endpoints for tasks like database access, authentication, and authorization while keeping sensitive data hidden from the client.
 
@@ -53,5 +53,5 @@ Since they are generated per visit, these routes can be customized for each view
 Both `server` and `hybrid` output modes allow you to include [Astro islands](/en/concepts/islands/) for interactivity (or even entire embedded client-side rendered apps!) in your choice of [UI frameworks](/en/guides/framework-components/). With [middleware](/en/guides/middleware/) and Astro's [View Transitions API](/en/guides/view-transitions/) for animations and preserving state across route navigations, even highly interactive apps are possible.
 
 :::tip
-On demand server-rendering in Astro, especially when combined with [view transitions](/en/guides/view-transitions/), provides a true app experience without the JavaScript overhead of a client-side, single-page application.
-:::
+On demand server rendering in Astro, especially when combined with [view transitions](/en/guides/view-transitions/), provides a true app experience without the JavaScript overhead of a client-side, single-page application.
+:::