From a1a1f2a034f4de6e17c18776fe7e1c3c7bca053c Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sun, 14 Jul 2024 09:06:15 -0300 Subject: [PATCH 1/9] add new `first` and `last` to pagination page prop (#8751) Co-authored-by: Matthew Phillips Co-authored-by: Luiz Ferraz Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com> --- src/content/docs/en/reference/api-reference.mdx | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index a9b2d01aa4dbb..51dc22d07781c 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/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` + +

+**Type:** `string | undefined` +

+ +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` + +

+**Type:** `string | undefined` +

+ +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). From 61f684f340e2b11e46296edceb383a67ac606210 Mon Sep 17 00:00:00 2001 From: Luiz Ferraz Date: Sun, 14 Jul 2024 09:10:14 -0300 Subject: [PATCH 2/9] Document how to extend integration hooks (#8701) Co-authored-by: Chris Swithinbank Co-authored-by: Sarah Rainsberger --- .../en/reference/integrations-reference.mdx | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 9e5580fbc305a..26d079398978a 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -54,12 +54,18 @@ interface AstroIntegration { logger: AstroIntegrationLogger; }) => void | Promise; 'astro:build:done'?: (options: { dir: URL; routes: RouteData[]; logger: AstroIntegrationLogger; }) => void | Promise; + + // ... 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 + } + } +} +``` + +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`**: From 14fb8191ebd11828ee70357960623a64ec12594c Mon Sep 17 00:00:00 2001 From: Marco Campos Date: Sun, 14 Jul 2024 08:18:26 -0400 Subject: [PATCH 3/9] Feature: add note about default color configuration for shiki (#8722) Co-authored-by: Sarah Rainsberger Co-authored-by: Chris Swithinbank --- .../docs/en/guides/markdown-content.mdx | 6 +- .../docs/en/reference/api-reference.mdx | 72 ++++++++++--------- 2 files changed, 44 insertions(+), 34 deletions(-) diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx index 2ea6a8f0555b5..b695d2594a7f9 100644 --- a/src/content/docs/en/guides/markdown-content.mdx +++ b/src/content/docs/en/guides/markdown-content.mdx @@ -601,6 +601,10 @@ export default defineConfig({ light: 'github-light', dark: 'github-dark', }, + // Disable the default colours + // 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 diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 51dc22d07781c..ae27f2baa97c6 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -160,7 +160,7 @@ See also: [`params`](#params) ### `Astro.request` -`Astro.request` is a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. It can be used to get the `url`, `headers`, `method`, and even body of the request. +`Astro.request` is a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. It can be used to get the `url`, `headers`, `method`, and even body of the request. ```astro

Received a {Astro.request.method} request to "{Astro.request.url}".

@@ -176,7 +176,7 @@ With the default `output: 'static'` option, `Astro.request.url` does not contain ### `Astro.response` -`Astro.response` is a standard `ResponseInit` object. It has the following structure. +`Astro.response` is a standard `ResponseInit` object. It has the following structure. - `status`: The numeric status code of the response, e.g., `200`. - `statusText`: The status message associated with the status code, e.g., `'OK'`. @@ -394,7 +394,7 @@ if (!isLoggedIn(cookie)) { ### `Astro.canonicalURL` :::caution[Deprecated] -Use [`Astro.url`](#astrourl) to construct your own canonical URL. +Use [`Astro.url`](#astrourl) to construct your own canonical URL. ::: The [canonical URL][canonical] of the current page. @@ -403,9 +403,9 @@ The [canonical URL][canonical] of the current page.

-A [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object constructed from the current `Astro.request.url` URL string value. Useful for interacting with individual properties of the request URL, like pathname and origin. +A [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object constructed from the current `Astro.request.url` URL string value. Useful for interacting with individual properties of the request URL, like pathname and origin. -Equivalent to doing `new URL(Astro.request.url)`. +Equivalent to doing `new URL(Astro.request.url)`. ```astro

The current URL is: {Astro.url}

@@ -599,7 +599,7 @@ const orders = Array.from(Astro.locals.orders.entries()); ### `Astro.preferredLocale` -`Astro.preferredLocale` is a computed value that represents the preferred locale of the user. +`Astro.preferredLocale` is a computed value that represents the preferred locale of the user. It is computed by checking the configured locales in your `i18n.locales` array and locales supported by the users's browser via the header `Accept-Language`. This value is `undefined` if no such match exists. @@ -607,11 +607,11 @@ This property is only available when building for SSR (server-side rendering) an ### `Astro.preferredLocaleList` -`Astro.preferredLocaleList` represents the array of all locales that are both requested by the browser and supported by your website. This produces a list of all compatible languages between your site and your visitor. +`Astro.preferredLocaleList` represents the array of all locales that are both requested by the browser and supported by your website. This produces a list of all compatible languages between your site and your visitor. If none of the browser's requested languages are found in your locales array, then the value is `[]`: you do not support any of your visitor's preferred locales. -If the browser does not specify any preferred languages, then this value will be [`i18n.locales`](/en/reference/configuration-reference/#i18nlocales): all of your supported locales will be considered equally preferred by a visitor with no preferences. +If the browser does not specify any preferred languages, then this value will be [`i18n.locales`](/en/reference/configuration-reference/#i18nlocales): all of your supported locales will be considered equally preferred by a visitor with no preferences. This property is only available when building for SSR (server-side rendering) and should not be used for static sites. @@ -1100,7 +1100,7 @@ This function accepts the following properties:

-**Type:** `'content' | 'data'` +**Type:** `'content' | 'data'` **Default:** `'content'` `type` is a string that defines the type of entries stored within a collection: @@ -1259,7 +1259,7 @@ The `CollectionEntry` type is an object with the following valu #### `id` -**Available for:** `type: 'content'` and `type: 'data'` collections +**Available for:** `type: 'content'` and `type: 'data'` collections **Example Types:** - content collections: `'entry-1.md' | 'entry-2.md' | ...` - data collections: `'author-1' | 'author-2' | ...` @@ -1268,35 +1268,35 @@ A unique ID using the file path relative to `src/content/[collection]`. Enumerat #### `collection` -**Available for:** `type: 'content'` and `type: 'data'` collections +**Available for:** `type: 'content'` and `type: 'data'` collections **Example Type:** `'blog' | 'authors' | ...` The name of a top-level folder under `src/content/` in which entries are located. This is the name used to reference the collection in your schema, and in querying functions. #### `data` -**Available for:** `type: 'content'` and `type: 'data'` collections +**Available for:** `type: 'content'` and `type: 'data'` collections **Type:** `CollectionSchema` An object of frontmatter properties inferred from your collection schema ([see `defineCollection()` reference](#definecollection)). Defaults to `any` if no schema is configured. #### `slug` -**Available for:** `type: 'content'` collections only +**Available for:** `type: 'content'` collections only **Example Type:** `'entry-1' | 'entry-2' | ...` A URL-ready slug for Markdown or MDX documents. Defaults to the `id` without the file extension, but can be overridden by setting [the `slug` property](/en/guides/content-collections/#defining-custom-slugs) in a file's frontmatter. #### `body` -**Available for:** `type: 'content'` collections only +**Available for:** `type: 'content'` collections only **Type:** `string` A string containing the raw, uncompiled body of the Markdown or MDX document. #### `render()` -**Available for:** `type: 'content'` collections only +**Available for:** `type: 'content'` collections only **Type:** `() => Promise` A function to compile a given Markdown or MDX document for rendering. This returns the following properties: @@ -1395,7 +1395,7 @@ This is an optional argument of `onRequest()`, and may provide the required `Res ### `sequence()` -A function that accepts middleware functions as arguments, and will execute them in the order in which they are passed. +A function that accepts middleware functions as arguments, and will execute them in the order in which they are passed. ```js title="src/middleware.js" import { sequence } from "astro:middleware"; @@ -1434,11 +1434,11 @@ Also, note that the returned URLs created by these functions for your `defaultLo For features and usage examples, [see our i18n routing guide](/en/guides/internationalization/). -### `getRelativeLocaleUrl()` +### `getRelativeLocaleUrl()` `getRelativeLocaleUrl(locale: string, path?: string, options?: GetLocaleOptions): string` -Use this function to retrieve a relative path for a locale. If the locale doesn't exist, Astro throws an error. +Use this function to retrieve a relative path for a locale. If the locale doesn't exist, Astro throws an error. ```astro --- @@ -1453,20 +1453,20 @@ getRelativeLocaleUrl("fr", "getting-started"); getRelativeLocaleUrl("fr_CA", "getting-started", { prependWith: "blog" -}); +}); // returns /blog/fr-ca/getting-started getRelativeLocaleUrl("fr_CA", "getting-started", { prependWith: "blog", normalizeLocale: false -}); +}); // returns /blog/fr_CA/getting-started --- ``` -### `getAbsoluteLocaleUrl()` +### `getAbsoluteLocaleUrl()` -`getAbsoluteLocaleUrl(locale: string, path: string, options?: GetLocaleOptions): string` +`getAbsoluteLocaleUrl(locale: string, path: string, options?: GetLocaleOptions): string` Use this function to retrieve an absolute path for a locale when [`site`] has a value. If [`site`] isn't configured, the function returns a relative URL. If the locale doesn't exist, Astro throws an error. @@ -1475,29 +1475,29 @@ Use this function to retrieve an absolute path for a locale when [`site`] has a --- // If `site` is set to be `https://example.com` -getAbsoluteLocaleUrl("fr"); +getAbsoluteLocaleUrl("fr"); // returns https://example.com/fr -getAbsoluteLocaleUrl("fr", ""); +getAbsoluteLocaleUrl("fr", ""); // returns https://example.com/fr -getAbsoluteLocaleUrl("fr", "getting-started"); +getAbsoluteLocaleUrl("fr", "getting-started"); // returns https://example.com/fr/getting-started getAbsoluteLocaleUrl("fr_CA", "getting-started", { prependWith: "blog" -}); +}); // returns https://example.com/blog/fr-ca/getting-started getAbsoluteLocaleUrl("fr_CA", "getting-started", { prependWith: "blog", normalizeLocale: false -}); +}); // returns https://example.com/blog/fr_CA/getting-started --- ``` - -### `getRelativeLocaleUrlList()` + +### `getRelativeLocaleUrlList()` `getRelativeLocaleUrlList(path?: string, options?: GetLocaleOptions): string[]` @@ -1505,13 +1505,13 @@ getAbsoluteLocaleUrl("fr_CA", "getting-started", { Use this like [`getRelativeLocaleUrl`](#getrelativelocaleurl) to return a list of relative paths for all the locales. -### `getAbsoluteLocaleUrlList()` +### `getAbsoluteLocaleUrlList()` `getAbsoluteLocaleUrlList(path?: string, options?: GetLocaleOptions): string[]` Use this like [`getAbsoluteLocaleUrl`](/en/guides/internationalization/#custom-locale-paths) to return a list of absolute paths for all the locales. -### `getPathByLocale()` +### `getPathByLocale()` `getPathByLocale(locale: string): string` @@ -1715,9 +1715,15 @@ import { Code } from 'astro:components'; will be rendered inline.

+ + ``` -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 @@ -1740,7 +1746,7 @@ console.log(foo + bar) // [!code focus] code={code} lang="js" transformers={[transformerNotationFocus()]} /> - +