Skip to content

Commit

Permalink
4.5 minor release docs (#7250)
Browse files Browse the repository at this point in the history 
Co-authored-by: delucis <delucis@users.noreply.github.com>
Co-authored-by: sarah11918 <sarah11918@users.noreply.github.com>
Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>
Co-authored-by: Bjorn Lu <bjornlu.dev@gmail.com>
Co-authored-by: Erika <3019731+Princesseuh@users.noreply.github.com>
Co-authored-by: Matthew Phillips <matthew@skypack.dev>
Co-authored-by: Arsh <69170106+lilnasy@users.noreply.github.com>
Co-authored-by: Elian <hello@elian.codes>
Co-authored-by: Oliver Speir <115520730+OliverSpeir@users.noreply.github.com>
  • Loading branch information
@sarah11918 @delucis
@bluwy @Princesseuh @matthewp @lilnasy @ElianCodes @OliverSpeir
9 people authored Mar 11, 2024
1 parent 6d02645 commit 697a7c0
Show file tree
Hide file tree
Showing 10 changed files with 198 additions and 44 deletions.
6 changes: 3 additions & 3 deletions src/content/docs/en/guides/integrations-guide/markdoc.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@ For example, the heading `### Level 3 heading!` will pass `level: 3` and `id: 'l

### Syntax highlighting

`@astrojs/markdoc` provides [Shiki](https://github.com/shikijs/shiki) and [Prism](https://github.com/PrismJS) extensions to highlight your code blocks.
`@astrojs/markdoc` provides [Shiki](https://shiki.style) and [Prism](https://github.com/PrismJS) extensions to highlight your code blocks.

#### Shiki

Expand All @@ -226,14 +226,14 @@ export default defineMarkdocConfig({
shiki({
// Choose from Shiki's built-in themes (or add your own)
// Default: 'github-dark'
// https://github.com/shikijs/shiki/blob/main/docs/themes.md
// https://shiki.style/themes
theme: 'dracula',
// Enable word wrap to prevent horizontal scrolling
// Default: false
wrap: true,
// Pass custom languages
// Note: Shiki has countless langs built-in, including `.astro`!
// https://github.com/shikijs/shiki/blob/main/docs/languages.md
// https://shiki.style/languages
langs: [],
}),
],
Expand Down
12 changes: 6 additions & 6 deletions src/content/docs/en/guides/markdown-content.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -572,7 +572,7 @@ export default defineConfig({

### Syntax Highlighting

Astro comes with built-in support for [Shiki](https://shiki.matsu.io/) (via [Shikiji](https://github.com/shikijs/shiki)) and [Prism](https://prismjs.com/). This provides syntax highlighting for:
Astro comes with built-in support for [Shiki](https://shiki.style/) and [Prism](https://prismjs.com/). This provides syntax highlighting for:

- all code fences (\`\`\`) used in a Markdown or MDX file.
- content within the [built-in `<Code />` component](/en/reference/api-reference/#code-) (powered by Shiki).
Expand All @@ -591,17 +591,17 @@ export default defineConfig({
markdown: {
shikiConfig: {
// Choose from Shiki's built-in themes (or add your own)
// https://github.com/shikijs/shiki/blob/main/docs/themes.md
// https://shiki.style/themes
theme: 'dracula',
// Alternatively, provide multiple themes
// https://shiki.style/guide/dual-themes#light-dark-dual-themes
experimentalThemes: {
// https://shiki.style/guide/dual-themes
themes: {
light: 'github-light',
dark: 'github-dark',
},
// Add custom languages
// Note: Shiki has countless langs built-in, including .astro!
// https://github.com/shikijs/shiki/blob/main/docs/languages.md
// https://shiki.style/languages
langs: [],
// Enable word wrap to prevent horizontal scrolling
wrap: true,
Expand All @@ -628,7 +628,7 @@ export default defineConfig({
});
```

We also suggest reading [Shiki's own theme documentation](https://github.com/shikijs/shiki/blob/main/docs/themes.md#loading-theme) to explore more about themes, light vs dark mode toggles, or styling via CSS variables.
We also suggest reading [Shiki's own theme documentation](https://shiki.style/themes) to explore more about themes, light vs dark mode toggles, or styling via CSS variables.

#### Change Default Syntax Highlighting Mode

Expand Down
18 changes: 8 additions & 10 deletions src/content/docs/en/guides/middleware.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,9 @@ i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';

**Middleware** allows you to intercept requests and responses and inject behaviors dynamically every time a page or endpoint is about to be rendered.
**Middleware** allows you to intercept requests and responses and inject behaviors dynamically every time a page or endpoint is about to be rendered. This rendering occurs at build time for all prerendered pages, but occurs when the route is requested for pages rendered on demand.

This also allows you to set and share request-specific information across endpoints and pages by mutating a `locals` object that is available in all Astro components and API endpoints

Middleware is available in both SSG and SSR Astro projects.

:::note
On all prerendered pages, the middleware runs only during the **build process** to create static pages and does not run in the deployed website. This applies to all pages in a `static` (SSG) project. This also includes prerendered pages in `hybrid` mode (default) and any pages in `server` mode with `export const prerender = true`.

For on-demand rendered pages in `server` (default) or `hybrid` (with `export const prerender = false`) mode, the middleware runs in the deployed website when the route is requested.
:::
Middleware also allows you to set and share request-specific information across endpoints and pages by mutating a `locals` object that is available in all Astro components and API endpoints. This object is available even when this middleware runs at build time.

## Basic Usage

Expand Down Expand Up @@ -200,3 +192,9 @@ greeting response
auth response
validation response
```

## Error pages

Middleware will attempt to run for all on-demand rendered pages, even when a matching route cannot be found. This includes Astro's default (blank) 404 page and any custom 404 pages. However, it is up to the [adapter](/en/guides/server-side-rendering/) to decide whether that code runs. Some adapters may serve a platform-specific error page instead.

Middleware will also attempt to run before serving a 500 error page, including a custom 500 page, unless the server error occured in the execution of the middleware itself. If your middleware does not run successfully, then you will not have access to `Astro.locals` to render your 500 page.
40 changes: 35 additions & 5 deletions src/content/docs/en/guides/view-transitions.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -112,10 +112,10 @@ For example, the following `<video>` will continue to play as you navigate to an

You can also place the directive on an [Astro island](/en/concepts/islands/) (a UI framework component with a [`client:` directive](/en/reference/directives-reference/#client-directives)). If that component exists on the next page, the island from the old page **with its current state** will continue to be displayed, instead of replacing it with the island from the new page.

In the example below, the `count` will not be reset when navigating back and forth across pages that contain the `<Counter />` component with the `transition:persist` attribute.
In the example below, the component's internal state of the count will not be reset when navigating back and forth across pages that contain the `<Counter />` component with the `transition:persist` attribute.

```astro title="components/Header.astro" "transition:persist"
<Counter client:load transition:persist count={5} />
<Counter client:load transition:persist initialCount={5} />
```

You can also [manually identify corresponding elements](#naming-a-transition) if the island/element is in a different component between the two pages.
Expand All @@ -134,6 +134,15 @@ As a convenient shorthand, `transition:persist` can alternatively take a transit
<video controls="" autoplay="" transition:persist="media-player">
```

#### `transition:persist-props`
<p><Since v="4.5.0" /></p>

This allows you to control whether or not an island's props should be persisted upon navigation.

By default, when you add `transition:persist` to an island, the state is retained upon navigation, but your component will re-render with new props. This is useful, for example, when a component receives page-specific props such as the current page's `title`.

You can override this behavior with `transition:persist-props`. Adding this directive will keep an island's existing props (not re-render with new values) in addition to maintaining its existing state.

### Built-in Animation Directives

Astro comes with a few built-in animations to override the default `fade` transition. Add the `transition:animate` directive to individual elements to customize the behavior of specific transitions.
Expand Down Expand Up @@ -444,11 +453,33 @@ When using the `<ViewTransitions />` router, the following steps occur to produc
7. The router executes any new scripts added to the page.
8. The `astro:page-load` event fires. This is the end of the navigation process.

## Script behavior during page navigation
## Script behavior with view transitions

When you add view transitions to an existing Astro project, some of your scripts may no longer re-run after page navigation like they did with full-page browser refreshes. Use the following information to ensure that your scripts execute as expected.

### Script order

When navigating between pages with the `<ViewTransitions />` component, scripts are run in sequential order to match browser behavior.

If you have code that sets up global state, this state will need to take into account that the script might execute more than once. Check for the global state in your `<script>` tag, and conditionally execute your code where possible:
### Script re-execution

[Bundled module scripts](/en/guides/client-side-scripts/#script-processing), which are the default scripts in Astro, are only ever executed once. After initial execution they will be ignored, even if the script exists on the new page after a transition.

Unlike bundled module scripts, [inline scripts](/en/guides/client-side-scripts/#opting-out-of-processing) have the potential to be re-executed during a user's visit to a site if they exist on a page that is visited multiple times. Inline scripts might also re-execute when a visitor navigates to a page without the script, and then back to one with the script.

#### `data-astro-rerun`

<p><Since v="4.5.0" /></p>

To force inline scripts to re-execute after every transition, add the `data-astro-rerun` property. Adding any attribute to a script also implicitly adds `is:inline`, so this is only available for scripts that are not bundled and processed by Astro.

```astro
<script is:inline data-astro-rerun>...</script>
```

To ensure that a script runs every time a page is loaded during client-side navigation, it should be executed by a [lifecycle event](#lifecycle-events). For example, event listeners for `DOMContentLoaded` can be replaced by the [`astro:page-load`](/en/guides/view-transitions/#astropage-load) lifecycle event.

If you have code that sets up a global state in an inline script, this state will need to take into account that the script might execute more than once. Check for the global state in your `<script>` tag, and conditionally execute your code where possible. This works because `window` is preserved.

```astro
<script is:inline>
Expand All @@ -458,7 +489,6 @@ If you have code that sets up global state, this state will need to take into ac
</script>
```

Module scripts, including those that add event listeners for `DOMContentLoaded`, are only ever executed once because the browser keeps track of which modules are already loaded. You must add listeners for a [Lifecycle event](#lifecycle-events) to re-execute scripts during client-side page navigation.

See the [Add View Transitions Tutorial](/en/tutorials/add-view-transitions/#update-scripts) for an example of updating existing scripts in a project.

Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/en/reference/api-reference.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1419,7 +1419,7 @@ import { Code } from 'astro:components';
</p>
```

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://github.com/shikijs/shiki/blob/main/docs/themes.md) and [languages](https://github.com/shikijs/shiki/blob/main/docs/languages.md). Plus, you can add your custom themes and languages by passing them to `theme` and `lang` 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 and languages by passing them to `theme` and `lang` respectively.

### `<Fragment />`

Expand Down
99 changes: 84 additions & 15 deletions src/content/docs/en/reference/configuration-reference.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -492,18 +492,18 @@ Specifies the directory in the build output where Astro-generated assets (bundle

<p>

**Type:** `string`<br />
**Type:** `string | Record.<string, string>`<br />
**Default:** `undefined`<br />
<Since v="2.2.0" />
</p>

Specifies the prefix for Astro-generated asset links. This can be used if assets are served from a different domain than the current site.

For example, if this is set to `https://cdn.example.com`, assets will be fetched from `https://cdn.example.com/_astro/...` (regardless of the `base` option).
You would need to upload the files in `./dist/_astro/` to `https://cdn.example.com/_astro/` to serve the assets.
The process varies depending on how the third-party domain is hosted.
This requires uploading the assets in your local `./dist/_astro` folder to a corresponding `/_astro/` folder on the remote domain.
To rename the `_astro` path, specify a new directory in `build.assets`.

To fetch all assets uploaded to the same domain (e.g. `https://cdn.example.com/_astro/...`), set `assetsPrefix` to the root domain as a string (regardless of your `base` configuration):

```js
{
build: {
Expand All @@ -512,6 +512,24 @@ To rename the `_astro` path, specify a new directory in `build.assets`.
}
```

**Added in:** `astro@4.5.0`

You can also pass an object to `assetsPrefix` to specify a different domain for each file type.
In this case, a `fallback` property is required and will be used by default for any other files.

```js
{
build: {
assetsPrefix: {
'js': 'https://js.cdn.example.com',
'mjs': 'https://js.cdn.example.com',
'css': 'https://css.cdn.example.com',
'fallback': 'https://cdn.example.com'
}
}
}
```

### build.serverEntry

<p>
Expand Down Expand Up @@ -890,7 +908,7 @@ Shiki configuration options. See [the Markdown configuration docs](/en/guides/ma
</p>

Which syntax highlighter to use, if any.
- `shiki` - use the [Shiki](https://github.com/shikijs/shiki) highlighter
- `shiki` - use the [Shiki](https://shiki.style) highlighter
- `prism` - use the [Prism](https://prismjs.com/) highlighter
- `false` - do not apply syntax highlighting.

Expand Down Expand Up @@ -1127,25 +1145,29 @@ in the latest version, so that you can continue to upgrade and take advantage of
Astro offers experimental flags to give users early access to new features.
These flags are not guaranteed to be stable.

### experimental.optimizeHoistedScript
### experimental.directRenderScript

<p>

**Type:** `boolean`<br />
**Default:** `false`<br />
<Since v="2.10.4" />
<Since v="4.5.0" />
</p>

Prevents unused components' scripts from being included in a page unexpectedly.
The optimization is best-effort and may inversely miss including the used scripts. Make sure to double-check your built pages
before publishing.
Enable hoisted script analysis optimization by adding the experimental flag:
Enables a more reliable strategy to prevent scripts from being executed in pages where they are not used.

Scripts will directly render as declared in Astro files (including existing features like TypeScript, importing `node_modules`,
and deduplicating scripts). You can also now conditionally render scripts in your Astro file.
However, this means scripts are no longer hoisted to the `<head>` and multiple scripts on a page are no longer bundled together.
If you enable this option, you should check that all your `<script>` tags behave as expected.

This option will be enabled by default in Astro 5.0.

```js
{
experimental: {
optimizeHoistedScript: true,
},
experimental: {
directRenderScript: true,
},
}
```

Expand All @@ -1168,6 +1190,53 @@ Enables a persistent cache for content collections when building in static mode.
}
```

### experimental.contentCollectionJsonSchema

<p>

**Type:** `boolean`<br />
**Default:** `false`<br />
<Since v="4.5.0" />
</p>

This feature will auto-generate a JSON schema for content collections of `type: 'data'` which can be used as the `$schema` value for TypeScript-style autocompletion/hints in tools like VSCode.

To enable this feature, add the experimental flag:

```diff
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
+ contentCollectionJsonSchema: true
}
});
```

This experimental implementation requires you to manually reference the schema in each data entry file of the collection:

```diff
// src/content/test/entry.json
{
+ "$schema": "../../../.astro/collections/test.schema.json",
"test": "test"
}
```

Alternatively, you can set this in your [VSCode `json.schemas` settings](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings):

```diff
"json.schemas": [
{
"fileMatch": [
"/src/content/test/**"
],
"url": "../../../.astro/collections/test.schema.json"
}
]
```

Note that this initial implementation uses a library with [known issues for advanced Zod schemas](https://github.com/StefanTerdell/zod-to-json-schema#known-issues), so you may wish to consult these limitations before enabling the experimental flag.

### experimental.clientPrerender

<p>
Expand All @@ -1179,7 +1248,7 @@ Enables a persistent cache for content collections when building in static mode.

Enables pre-rendering your prefetched pages on the client in supported browsers.

This feature uses the experimental [Speculation Rules Web API](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API) and overrides the default `prefetch` behavior globally to prerender links on the client.
This feature uses the experimental [Speculation Rules Web API](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API) and enhances the default `prefetch` behavior globally to prerender links on the client.
You may wish to review the [possible risks when prerendering on the client](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API#unsafe_prefetching) before enabling this feature.

Enable client side prerendering in your `astro.config.mjs` along with any desired `prefetch` configuration options:
Expand Down
Loading

0 comments on commit 697a7c0

Please sign in to comment.