4.12.0 Minor release docs (#8796)

Co-authored-by:  Matthew Phillips <matthew@matthewphillips.info>
Co-authored-by: Luiz Ferraz <luiz@lferraz.com>
Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>
Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>
Co-authored-by: sarah11918 <sarah11918@users.noreply.github.com>
Co-authored-by: Matthew Phillips <matthew@matthewphillips.info>
Co-authored-by: Marco Campos <madcampos@outlook.com>
Co-authored-by: Erika <3019731+Princesseuh@users.noreply.github.com>

src/content/docs/en/guides/images.mdx

@@ -129,7 +129,7 @@ The format of the `src` value of your image file depends on where your image fil
  src="https://example.com/remote-image.jpg"
  alt="descriptive text"
  width="200"
- height="150" 
+ height="150"
  />
  ```
 
@@ -143,7 +143,7 @@ If an image is merely decorative (i.e. doesn't contribute to the understanding o
 
 These properties define the dimensions to use for the image.
 
-When using images in their original aspect ratio, `width` and `height` are optional. These dimensions can be automatically inferred from image files located in `src/` and from remote images with [`inferSize` set to `true`](#infersize).
+When using images in their original aspect ratio, `width` and `height` are optional. These dimensions can be automatically inferred from image files located in `src/`. For remote images, add [the `inferSize` attribute set to `true`](#infersize) on the `<Image />` or `<Picture />` component or use [`inferRemoteSize()` function](#inferremotesize).
 
 However, both of these properties are required for images stored in your `public/` folder as Astro is unable to analyze these files.
 
@@ -266,6 +266,17 @@ import { Image } from 'astro:assets';
 
 `inferSize` can fetch the dimensions of a [remote image from a domain that has not been authorized](#authorizing-remote-images), however the image itself will remain unprocessed.
 
+###### inferRemoteSize()
+
+<p><Since v="4.12.0" /></p>
+
+A function to infer the dimensions of remote images. This can be used as an alternative to passing the `inferSize` property.
+
+```ts
+import { inferRemoteSize } from 'astro:assets';
+const {width, height} = await inferRemoteSize("https://example.com/cat.png");
+```
+
 ##### Additional properties
 
 In addition to the properties above, the `<Image />` component accepts all properties accepted by the HTML `<img>` tag.
@@ -742,4 +753,4 @@ export default defineConfig({
 
 ## Community Integrations
 
-There are several third-party [community image integrations](https://astro.build/integrations?search=images) for optimizing and working with images in your Astro project.
+There are several third-party [community image integrations](https://astro.build/integrations?search=images) for optimizing and working with images in your Astro project.

src/content/docs/en/guides/markdown-content.mdx

@@ -601,6 +601,10 @@ export default defineConfig({
  light: 'github-light',
  dark: 'github-dark',
  },
+ // Disable the default colors
+ // https://shiki.style/guide/dual-themes#without-default-color
+ // (Added in v4.12.0)
+ defaultColor: false,
  // Add custom languages
  // Note: Shiki has countless langs built-in, including .astro!
  // https://shiki.style/languages
@@ -616,7 +620,7 @@ export default defineConfig({
 ```
 
 :::note[Customizing Shiki themes]
-Astro code blocks are styled using the `.astro-code` class. When following Shiki's documentation (e.g. to [customize light/dark dual or multiple themes](https://shiki.style/guide/dual-themes#query-based-dark-mode)), be sure to replace the `.shiki` class in the examples with `.astro-code`
+Astro code blocks are styled using the `.astro-code` class. When following Shiki's documentation (e.g. to [customize light/dark dual or multiple themes](https://shiki.style/guide/dual-themes#query-based-dark-mode)), be sure to replace the `.shiki` class in the examples with `.astro-code`.
 :::
 
 #### Adding your own theme

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

@@ -1007,6 +1007,22 @@ Get the URL of the previous page (will be `undefined` if on page 1). If a value
 
 Get the URL of the next page (will be `undefined` if no more pages). If a value is set for [`base`](/en/reference/configuration-reference/#base), prepend the base path to the URL.
 
+##### `page.url.first`
+
+<p>
+**Type:** `string | undefined`
+</p>
+
+Get the URL of the first page (will be `undefined` if on page 1). If a value is set for [`base`](/en/reference/configuration-reference/#base), prepend the base path to the URL.
+
+##### `page.url.last`
+
+<p>
+**Type:** `string | undefined`
+</p>
+
+Get the URL of the last page (will be `undefined` if no more pages). If a value is set for [`base`](/en/reference/configuration-reference/#base), prepend the base path to the URL.
+
 ## `import.meta`
 
 All ESM modules include a `import.meta` property. Astro adds `import.meta.env` through [Vite](https://vitejs.dev/guide/env-and-mode.html).
@@ -1699,9 +1715,15 @@ import { Code } from 'astro:components';
  <Code code={`const foo = 'bar';`} lang="js" inline />
  will be rendered inline.
 </p>
+<!-- Optional: defaultColor -->
+<Code code={`const foo = 'bar';`} lang="js" defaultColor={false} />
 ```
 
-This component provides syntax highlighting for code blocks at build time (no client-side JavaScript included). The component is powered internally by Shiki and it supports all popular [themes](https://shiki.style/themes) and [languages](https://shiki.style/languages). Plus, you can add your custom themes, languages, and [transformers](#transformers) by passing them to the `theme`, `lang`, and `transformers` attributes respectively.
+This component provides syntax highlighting for code blocks at build time (no client-side JavaScript included). The component is powered internally by Shiki and it supports all popular [themes](https://shiki.style/themes) and [languages](https://shiki.style/languages). Plus, you can add your custom themes, languages, [transformers](#transformers), and [default colors](https://shiki.style/guide/dual-themes#without-default-color) by passing them to the `theme`, `lang`, `transformers`, and `defaultColor` attributes respectively.
+
+:::note
+This component **does not** inherit the settings from your [Shiki configuration](/en/guides/markdown-content/#shiki-configuration). You will have to set them using the component props.
+:::
 
 #### Transformers
 

src/content/docs/en/reference/cli-reference.mdx

@@ -250,6 +250,10 @@ For example, running `astro check --minimumSeverity warning` will show errors an
 
 Specifies not to clear the ouput between checks when in watch mode.
 
+#### `--noSync`
+
+Specifies not to run `astro sync` before checking the project.
+
 <ReadMore>Read more about [type checking in Astro](/en/guides/typescript/#type-checking).</ReadMore>
 
 ## `astro sync`

src/content/docs/en/reference/configuration-reference.mdx

@@ -1669,3 +1669,67 @@ export default defineConfig({
 })
 ```
 
+### experimental.serverIslands
+
+<p>
+
+**Type:** `boolean`<br />
+**Default:** `false`<br />
+<Since v="4.12.0" />
+</p>
+
+Enables experimental Server Island features.
+Server Islands offer the ability to defer a component to render asynchronously after the page has already rendered.
+
+To enable, configure an [on-demand server rendering `output` mode](/en/basics/rendering-modes/#on-demand-rendered) with an adapter, and add the `serverIslands` flag to the `experimental` object:
+
+```js
+{
+ output: 'hybrid', // or 'server'
+ adapter: nodejs({ mode: 'standalone' }),
+ experimental: {
+ serverIslands: true,
+ },
+}
+```
+
+Use the `server:defer` directive on any Astro component to delay initial rendering:
+
+```astro "server:defer"
+---
+import Avatar from '~/components/Avatar.astro';
+---
+<Avatar server:defer />
+```
+
+The outer page will be rendered, either at build-time (`hybrid`) or at runtime (`server`) with the island content omitted and a `<script>` tag included in its place.
+
+After the page loads in the browser, the script tag will replace itself with the the contents of the island by making a request.
+
+Any Astro component can be given the `server: defer` attribute to delay its rendering. There is no special API and you can write `.astro` code as normal:
+
+```astro
+---
+import { getUser } from '../api';
+
+const user = await getUser(Astro.locals.userId);
+---
+<img class="avatar" src={user.imageUrl}>
+```
+
+#### Server island fallback content
+
+Since your component will not render with the rest of the page, you may want to add generic content (e.g. a loading message) to temporarily show in its place. This content will be displayed when the page first renders but before the island has loaded.
+
+Add placeholder content as a child of your Astro component with the `slot="fallback:` attribute. When your island content is available, the fallback content will be replaced.
+
+The example below displays a generic avatar as fallback content, then animates into a personalized avatar using view transitions:
+
+```astro
+<Avatar server:defer>
+ <svg slot="fallback" class="generic-avatar" transition:name="avatar">...</svg>
+</Avatar>
+```
+
+For a complete overview, and to give feedback on this experimental API, see the [Server Islands RFC](https://github.com/withastro/roadmap/pull/963).
+

src/content/docs/en/reference/integrations-reference.mdx

@@ -54,12 +54,18 @@ interface AstroIntegration {
  logger: AstroIntegrationLogger;
  }) => void | Promise<void>;
  'astro:build:done'?: (options: { dir: URL; routes: RouteData[]; logger: AstroIntegrationLogger; }) => void | Promise<void>;
+
+ // ... any custom hooks from integrations
  };
 }
 ```
 
 ## Hooks
 
+Astro provides hooks that integrations can implement to execute during certain parts of Astro's lifecycle. Astro hooks are defined in the `IntegrationHooks` interface, which is part of the global `Astro` namespace.
+
+The following hooks are built in to Astro:
+
 ### `astro:config:setup`
 
 **Next hook:** [`astro:config:done`](#astroconfigdone)
@@ -613,6 +619,22 @@ A list of all generated pages. It is an object with one property.
 
 - `pathname` - the finalized path of the page.
 
+### Custom hooks
+
+Custom hooks can be added to integrations by extending the `IntegrationHooks` interface through [global augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#global-augmentation).
+
+```ts
+declare global {
+ namespace Astro {
+ export interface IntegrationHook {
+ 'your:hook': (params: YourHookParameters) => Promise<void>
+ }
+ }
+}
+```
+
+Astro reserves the `astro:` prefix for future built-in hooks. Please choose a different prefix when naming your custom hook.
+
 ## Allow installation with `astro add`
 
 [The `astro add` command](/en/reference/cli-reference/#astro-add) allows users to easily add integrations and adapters to their project. If you want _your_ integration to be installable with this tool, **add `astro-integration` to the `keywords` field in your `package.json`**: