Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

4.12.0 Minor release docs #8796

Merged
merged 11 commits into from
Jul 18, 2024
Prev Previous commit
Next Next commit
Feature: add note about default color configuration for shiki (#8722)
Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>
Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
3 people authored Jul 14, 2024
commit 14fb8191ebd11828ee70357960623a64ec12594c
6 changes: 5 additions & 1 deletion src/content/docs/en/guides/markdown-content.mdx
Original file line number Diff line number Diff line change
@@ -601,6 +601,10 @@ export default defineConfig({
light: 'github-light',
dark: 'github-dark',
},
// Disable the default colours
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
// 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
72 changes: 39 additions & 33 deletions src/content/docs/en/reference/api-reference.mdx
Original file line number Diff line number Diff line change
@@ -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.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

```astro
<p>Received a {Astro.request.method} request to "{Astro.request.url}".</p>
@@ -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.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

- `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.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
:::

The [canonical URL][canonical] of the current page.
@@ -403,9 +403,9 @@ The [canonical URL][canonical] of the current page.

<p><Since v="1.0.0-rc" /></p>

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.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

Equivalent to doing `new URL(Astro.request.url)`.
Equivalent to doing `new URL(Astro.request.url)`.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

```astro
<h1>The current URL is: {Astro.url}</h1>
@@ -599,19 +599,19 @@ 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.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

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.

This property is only available when building for SSR (server-side rendering) and should not be used for static sites.

### `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.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

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.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

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:

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

**Type:** `'content' | 'data'`
**Type:** `'content' | 'data'`
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
**Default:** `'content'`

`type` is a string that defines the type of entries stored within a collection:
@@ -1259,7 +1259,7 @@ The `CollectionEntry<TCollectionName>` 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
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
**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
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
**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
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
**Type:** `CollectionSchema<TCollectionName>`

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
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
**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
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
**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
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
**Type:** `() => Promise<RenderedEntry>`

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.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

```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()`
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

`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.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

```astro
---
@@ -1453,20 +1453,20 @@ getRelativeLocaleUrl("fr", "getting-started");
getRelativeLocaleUrl("fr_CA", "getting-started", {
prependWith: "blog"
});
});
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
// returns /blog/fr-ca/getting-started
getRelativeLocaleUrl("fr_CA", "getting-started", {
prependWith: "blog",
normalizeLocale: false
});
});
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
// returns /blog/fr_CA/getting-started
---
```

### `getAbsoluteLocaleUrl()`
### `getAbsoluteLocaleUrl()`
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

`getAbsoluteLocaleUrl(locale: string, path: string, options?: GetLocaleOptions): string`
`getAbsoluteLocaleUrl(locale: string, path: string, options?: GetLocaleOptions): string`
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

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,43 +1475,43 @@ 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");
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
// returns https://example.com/fr
getAbsoluteLocaleUrl("fr", "");
getAbsoluteLocaleUrl("fr", "");
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
// returns https://example.com/fr
getAbsoluteLocaleUrl("fr", "getting-started");
getAbsoluteLocaleUrl("fr", "getting-started");
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
// returns https://example.com/fr/getting-started
getAbsoluteLocaleUrl("fr_CA", "getting-started", {
prependWith: "blog"
});
});
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
// returns https://example.com/blog/fr-ca/getting-started
getAbsoluteLocaleUrl("fr_CA", "getting-started", {
prependWith: "blog",
normalizeLocale: false
});
});
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
// returns https://example.com/blog/fr_CA/getting-started
---
```
### `getRelativeLocaleUrlList()`

sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
### `getRelativeLocaleUrlList()`
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

`getRelativeLocaleUrlList(path?: string, options?: GetLocaleOptions): string[]`


Use this like [`getRelativeLocaleUrl`](#getrelativelocaleurl) to return a list of relative paths for all the locales.


### `getAbsoluteLocaleUrlList()`
### `getAbsoluteLocaleUrlList()`
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

`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()`
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

`getPathByLocale(locale: string): string`

@@ -1715,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

@@ -1740,7 +1746,7 @@ console.log(foo + bar) // [!code focus]
code={code}
lang="js"
transformers={[transformerNotationFocus()]} />
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
<style is:global>
pre.has-focused .line:not(.focused) {
filter: blur(1px);

Unchanged files with check annotations Beta

/** Generate a Starlight sidebar config object from our existing `nav.ts` files. */
export function makeSidebar(): StarlightSidebarConfig {
let currentSubGroup: Extract<StarlightSidebarConfig[number], { items: any }>;

Check warning on line 25 in config/sidebar.ts

GitHub Actions / Check for code issues with ESLint

Unexpected any. Specify a different type
return navTranslations.en.reduce((sidebar, item) => {
if ('header' in item) {
const newGroup = {