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.

Sign up for GitHub

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

Feature: add note about default color configuration for shiki #8722

Merged
merged 8 commits into from
Jul 14, 2024
Merged

Feature: add note about default color configuration for shiki #8722

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
60ae0ed
feat: add note about default color configuration for shiki
madcampos Jul 4, 2024
d5f511a
feat: add `since` component
madcampos Jul 4, 2024
69a67b0
feat: add doc on `<Code/>` component
madcampos Jul 4, 2024
321fbfa
Sarah edit
sarah11918 Jul 4, 2024
37bc966
Apply suggestions from code review
madcampos Jul 4, 2024
df4d945
feat: add note about code component not inheriting settings
madcampos Jul 4, 2024
e1c7ea6
Merge branch 'main' into feat/shiki-defaultcolor
delucis Jul 13, 2024
0cdc42b
Merge branch '4.12.0' into feat/shiki-defaultcolor
sarah11918 Jul 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion src/content/docs/en/guides/markdown-content.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -603,6 +603,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
Expand All @@ -618,7 +622,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
Expand Down
70 changes: 37 additions & 33 deletions src/content/docs/en/reference/api-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
<p>Received a {Astro.request.method} request to "{Astro.request.url}".</p>
Expand All @@ -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'`.
Expand Down Expand Up @@ -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.
Expand All @@ -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.

Equivalent to doing `new URL(Astro.request.url)`.
Equivalent to doing `new URL(Astro.request.url)`.

```astro
<h1>The current URL is: {Astro.url}</h1>
Expand Down Expand Up @@ -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.

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.

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.

Expand Down Expand Up @@ -1084,7 +1084,7 @@ This function accepts the following properties:

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

**Type:** `'content' | 'data'`
**Type:** `'content' | 'data'`
**Default:** `'content'`

`type` is a string that defines the type of entries stored within a collection:
Expand Down Expand Up @@ -1243,7 +1243,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
**Example Types:**
- content collections: `'entry-1.md' | 'entry-2.md' | ...`
- data collections: `'author-1' | 'author-2' | ...`
Expand All @@ -1252,35 +1252,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<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
**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<RenderedEntry>`

A function to compile a given Markdown or MDX document for rendering. This returns the following properties:
Expand Down Expand Up @@ -1379,7 +1379,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";
Expand Down Expand Up @@ -1418,11 +1418,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
---
Expand All @@ -1437,20 +1437,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.

Expand All @@ -1459,43 +1459,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");
// 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[]`


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`

Expand Down Expand Up @@ -1699,9 +1699,13 @@ 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 color theme](https://shiki.style/guide/dual-themes#without-default-color) by passing them to the `theme`, `lang`, `transformers`, and `defaultColor` attributes respectively.

By default, this component will use the settings from your [Shiki configuration](/en/guides/markdown-content/#shiki-configuration).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this true? If so, I think it's helpful to add here!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just tested and it seems that the <Code /> component does not inherit any configuration 😕

It think it is worth to point out that to avoid confusion.

Copy link
Member

@sarah11918 sarah11918 Jul 5, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting! So it doesn't even use the theme you've set or anything? I would have assumed that it would! (It's a better story to tell if it does!) I guess it's because it's a Markdown configuration, so it's only relevant when writing code in markdown blocks. I wonder how difficult that would be for us to add....

But yes, if it's not true, we won't say it! Thank you for testing!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No problem!

I think it would not be so hard to add. One workaround would be to import astro config and then pass the specific part as props to the Code component. Something like this:

On the config file, export the shiki config:

export const shikiConfig = {
  //...
};

// All the regular astro config...

Then on an astro file import the config and use it to pass props to the code component:

---
import { shikiConfig } from '../astro.config.ts';
---

<Code {...shikiConfig} />


#### Transformers

Expand All @@ -1724,7 +1728,7 @@ console.log(foo + bar) // [!code focus]
code={code}
lang="js"
transformers={[transformerNotationFocus()]} />

<style is:global>
pre.has-focused .line:not(.focused) {
filter: blur(1px);
Expand Down
Loading