You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Adds Expressive Code as Starlight’s default code block renderer
6
+
7
+
⚠️ **Potentially breaking change:**
8
+
This addition changes how Markdown code blocks are rendered. By default, Starlight will now use [Expressive Code](https://github.com/expressive-code/expressive-code/tree/main/packages/astro-expressive-code).
9
+
If you were already customizing how code blocks are rendered and don't want to use the [features provided by Expressive Code](https://starlight.astro.build/guides/authoring-content/#expressive-code-features), you can preserve the previous behavior by setting the new config option `expressiveCode` to `false`.
10
+
11
+
If you had previously added Expressive Code manually to your Starlight project, you can now remove the manual set-up in `astro.config.mjs`:
12
+
13
+
- Move your configuration to Starlight’s new `expressiveCode` option.
14
+
- Remove the `astro-expressive-code` integration.
15
+
16
+
For example:
17
+
18
+
```diff
19
+
import starlight from '@astrojs/starlight';
20
+
import { defineConfig } from 'astro/config';
21
+
- import expressiveCode from 'astro-expressive-code';
22
+
23
+
export default defineConfig({
24
+
integrations: [
25
+
- expressiveCode({
26
+
- themes: ['rose-pine'],
27
+
- }),
28
+
starlight({
29
+
title: 'My docs',
30
+
+ expressiveCode: {
31
+
+ themes: ['rose-pine'],
32
+
+ },
33
+
}),
34
+
],
35
+
});
36
+
```
37
+
38
+
Note that the built-in Starlight version of Expressive Code sets some opinionated defaults that are different from the `astro-expressive-code` defaults. You may need to set some `styleOverrides` if you wish to keep styles exactly the same.
Copy file name to clipboardExpand all lines: docs/src/content/docs/guides/authoring-content.md
+142-3
Original file line number
Diff line number
Diff line change
@@ -202,9 +202,148 @@ var fun = function lang(l) {
202
202
```
203
203
````
204
204
205
-
```md
206
-
Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.
207
-
```
205
+
### Expressive Code features
206
+
207
+
Starlight uses [Expressive Code](https://github.com/expressive-code/expressive-code/tree/main/packages/astro-expressive-code) to extend formatting possibilities for code blocks.
208
+
Expressive Code’s text markers and window frames plugins are enabled by default.
209
+
Code block rendering can be configured using Starlight’s [`expressiveCode` configuration option](/reference/configuration/#expressivecode).
210
+
211
+
#### Text markers
212
+
213
+
You can highlight specific lines or parts of your code blocks using [Expressive Code text markers](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#usage-in-markdown--mdx-documents) on the opening line of your code block.
214
+
Use curly braces (`{ }`) to highlight entire lines, and quotation marks to highlight strings of text.
215
+
216
+
There are three highlighting styles: neutral for calling attention to code, green for indicating inserted code, and red for indicating deleted code.
217
+
Both text and entire lines can be marked using the default marker, or in combination with `ins=` and `del=` to produce the desired highlighting.
218
+
219
+
Expressive Code provides several options for customizing the visual appearance of your code samples.
220
+
Many of these can be combined, for highly illustrative code samples.
221
+
Please explore the [Expressive Code documentation](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md) for the extensive options available.
222
+
Some of the most common examples are shown below:
223
+
224
+
-[Mark entire lines & line ranges using the `{ }` marker](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#marking-entire-lines--line-ranges):
225
+
226
+
```js {2-3}
227
+
functiondemo() {
228
+
// This line (#2) and the next one are highlighted
229
+
return'This is line #3 of this snippet';
230
+
}
231
+
```
232
+
233
+
````md
234
+
```js {2-3}
235
+
function demo() {
236
+
// This line (#2) and the next one are highlighted
237
+
return 'This is line #3 of this snippet';
238
+
}
239
+
```
240
+
````
241
+
242
+
-[Mark selections of text using the `" "` marker or regular expressions](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#marking-entire-lines--line-ranges):
243
+
244
+
```js "Individual terms" /Even.*supported/
245
+
// Individual terms can be highlighted, too
246
+
functiondemo() {
247
+
return'Even regular expressions are supported';
248
+
}
249
+
```
250
+
251
+
````md
252
+
```js "Individual terms" /Even.*supported/
253
+
// Individual terms can be highlighted, too
254
+
function demo() {
255
+
return 'Even regular expressions are supported';
256
+
}
257
+
```
258
+
````
259
+
260
+
-[Mark text or lines as inserted or deleted with `ins` or `del`](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#selecting-marker-types-mark-ins-del):
261
+
262
+
```js "return true;" ins="inserted" del="deleted"
263
+
functiondemo() {
264
+
console.log('These are inserted and deleted marker types');
265
+
// The return statement uses the default marker type
266
+
returntrue;
267
+
}
268
+
```
269
+
270
+
````md
271
+
```js "return true;" ins="inserted" del="deleted"
272
+
function demo() {
273
+
console.log('These are inserted and deleted marker types');
274
+
// The return statement uses the default marker type
275
+
return true;
276
+
}
277
+
```
278
+
````
279
+
280
+
-[Combine syntax highlighting with `diff`-like syntax](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#combining-syntax-highlighting-with-diff-like-syntax):
281
+
282
+
```diff lang="js"
283
+
function thisIsJavaScript() {
284
+
// This entire block gets highlighted as JavaScript,
285
+
// and we can still add diff markers to it!
286
+
- console.log('Old code to be removed')
287
+
+ console.log('New and shiny code!')
288
+
}
289
+
```
290
+
291
+
````md
292
+
```diff lang="js"
293
+
function thisIsJavaScript() {
294
+
// This entire block gets highlighted as JavaScript,
295
+
// and we can still add diff markers to it!
296
+
- console.log('Old code to be removed')
297
+
+ console.log('New and shiny code!')
298
+
}
299
+
```
300
+
````
301
+
302
+
#### Frames and titles
303
+
304
+
Code blocks can be rendered inside a window-like frame.
305
+
A frame that looks like a terminal window will be used for shell scripting languages (e.g. `bash` or `sh`).
306
+
Other languages display inside a code editor-style frame if they include a title.
307
+
308
+
A code block’s optional title can be set either with a `title="..."` attribute following the code block's opening backticks and language identifier, or with a file name comment in the first lines of the code.
309
+
310
+
-[Add a file name tab with a comment](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#code-editor-window-frames)
311
+
312
+
```js
313
+
// my-test-file.js
314
+
console.log('Hello World!');
315
+
```
316
+
317
+
````md
318
+
```js
319
+
// my-test-file.js
320
+
console.log('Hello World!');
321
+
```
322
+
````
323
+
324
+
-[Add a title to a Terminal window](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#terminal-window-frames)
325
+
326
+
```bash title="Installing dependencies…"
327
+
npm install
328
+
```
329
+
330
+
````md
331
+
```bash title="Installing dependencies…"
332
+
npm install
333
+
```
334
+
````
335
+
336
+
-[Disable window frames with `frame="none"`](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#overriding-frame-types)
337
+
338
+
```bash frame="none"
339
+
echo"This is not rendered as a terminal despite using the bash language"
340
+
```
341
+
342
+
````md
343
+
```bash frame="none"
344
+
echo "This is not rendered as a terminal despite using the bash language"
Starlight uses [Expressive Code](https://github.com/expressive-code/expressive-code/tree/main/packages/astro-expressive-code) to render code blocks and add support for highlighting parts of code examples, adding filenames to code blocks, and more.
355
+
See the [“Code blocks” guide](/guides/authoring-content/#code-blocks) to learn how to use Expressive Code syntax in your Markdown and MDX content.
356
+
357
+
You can use any of the standard [Expressive Code configuration options](https://github.com/expressive-code/expressive-code/blob/main/packages/astro-expressive-code/README.md#configuration) as well as some Starlight-specific properties, by setting them in Starlight’s `expressiveCode` option.
358
+
For example, set Expressive Code’s `styleOverrides` option to override the default CSS. This enables customizations like giving your code blocks rounded corners:
359
+
360
+
```js ins={2-4}
361
+
starlight({
362
+
expressiveCode: {
363
+
styleOverrides: { borderRadius:'0.5rem' },
364
+
},
365
+
});
366
+
```
367
+
368
+
If you want to disable Expressive Code, set `expressiveCode: false` in your Starlight config:
369
+
370
+
```js ins={2}
371
+
starlight({
372
+
expressiveCode:false,
373
+
});
374
+
```
375
+
376
+
In addition to the standard Expressive Code options, you can also set the following Starlight-specific properties in your `expressiveCode` config to further customize theme behavior for your code blocks :
See the [Expressive Code `themes` documentation](https://github.com/expressive-code/expressive-code/blob/main/packages/astro-expressive-code/README.md#themes) for details of the supported theme formats.
385
+
386
+
Starlight uses the dark and light variants of Sarah Drasner’s [Night Owl theme](https://github.com/sdras/night-owl-vscode-theme) by default.
387
+
388
+
If you provide at least one dark and one light theme, Starlight will automatically keep the active code block theme in sync with the current site theme.
389
+
Configure this behavior with the [`useStarlightDarkModeSwitch`](#usestarlightdarkmodeswitch) option.
390
+
391
+
#### `useStarlightDarkModeSwitch`
392
+
393
+
**type:**`boolean`
394
+
**default:**`true`
395
+
396
+
When `true`, code blocks automatically switch between light and dark themes when the site theme changes.
397
+
When `false`, you must manually add CSS to handle switching between multiple themes.
398
+
399
+
:::note
400
+
When setting `themes`, you must provide at least one dark and one light theme for the Starlight dark mode switch to work.
401
+
:::
402
+
403
+
#### `useStarlightUiThemeColors`
404
+
405
+
**type:**`boolean`
406
+
**default:**`true` if `themes` is not set, otherwise `false`
407
+
408
+
When `true`, Starlight's CSS variables are used for the colors of code block UI elements (backgrounds, buttons, shadows etc.), matching the [site color theme](/guides/css-and-tailwind/#theming).
409
+
When `false`, the colors provided by the active syntax highlighting theme are used for these elements.
410
+
411
+
:::note
412
+
When using custom themes and setting this to `true`, you must provide at least one dark and one light theme to ensure proper color contrast.
0 commit comments