Skip to content

Commit e14162e

Browse files
hippotastichippotastic
committed
Docs: Recommend ec.config.mjs for plugins, add Steps 
1 parent 7b8c71b commit e14162e

File tree

13 files changed

+141
-74
lines changed

13 files changed

+141
-74
lines changed

‎docs/scripts/typedoc/templates/plugins/collapsible-sections.mdx

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ title: Collapsible Sections
44

55
import ConfigVariants from '@components/ConfigVariants.astro'
66
import PackageManagers from '@components/PackageManagers.astro'
7-
import { Tabs, TabItem } from '@astrojs/starlight/components'
7+
import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'
88

99
This optional plugin allows you to reduce long code examples to their relevant parts by collapsing any line ranges that are not relevant to the example.
1010

@@ -14,13 +14,18 @@ The lines of collapsed sections will be replaced by a clickable `X collapsed l
1414

1515
Before being able to use collapsible sections in your code blocks, you need to install the plugin as a dependency and add it to your configuration:
1616

17+
<Steps>
18+
1719
1. Add the package to your site's dependencies:
1820

1921
<PackageManagers pkg="@expressive-code/plugin-collapsible-sections" />
2022

21-
2. Add the plugin to your site's configuration by passing it in the `plugins` list:
23+
2. Add the plugin to your site's configuration by passing it in the `plugins` list.
24+
25+
In Astro and Starlight projects, we recommend putting this option in `ec.config.mjs` to ensure that the [`<Code>` component](/key-features/code-component/#using-an-ecconfigmjs-file) can still be used on your site.
2226

2327
<ConfigVariants
28+
preferEcConfigFile
2429
imports={`
2530
import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'
2631
`}
@@ -29,6 +34,8 @@ Before being able to use collapsible sections in your code blocks, you need to i
2934
`}
3035
/>
3136

37+
</Steps>
38+
3239
## Usage in markdown / MDX
3340

3441
To mark a section as collapsible, you need to add **meta information** to your code blocks. This is done by appending `collapse={X-Y}` to your opening code fence, indicating a collapsed section from line `X` to (and including) line `Y`.

‎docs/scripts/typedoc/templates/plugins/line-numbers.mdx

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,21 +4,26 @@ title: Line Numbers
44

55
import ConfigVariants from '@components/ConfigVariants.astro'
66
import PackageManagers from '@components/PackageManagers.astro'
7-
import { Tabs, TabItem } from '@astrojs/starlight/components'
7+
import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'
88

99
This optional plugin allows you to display line numbers in your code blocks. The line numbers are displayed in the gutter to the left of the code.
1010

1111
## Installation
1212

1313
Before being able to display line numbers in your code blocks, you need to install the plugin as a dependency and add it to your configuration:
1414

15+
<Steps>
16+
1517
1. Add the package to your site's dependencies:
1618

1719
<PackageManagers pkg="@expressive-code/plugin-line-numbers" />
1820

19-
2. Add the plugin to your site's configuration by passing it in the `plugins` list:
21+
2. Add the plugin to your site's configuration by passing it in the `plugins` list.
22+
23+
In Astro and Starlight projects, we recommend putting this option in `ec.config.mjs` to ensure that the [`<Code>` component](/key-features/code-component/#using-an-ecconfigmjs-file) can still be used on your site.
2024

2125
<ConfigVariants
26+
preferEcConfigFile
2227
imports={`
2328
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'
2429
`}
@@ -27,6 +32,8 @@ Before being able to display line numbers in your code blocks, you need to insta
2732
`}
2833
/>
2934

35+
</Steps>
36+
3037
## Usage in markdown / MDX
3138

3239
### Displaying line numbers per block

‎docs/scripts/typedoc/templates/reference/configuration.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ styleOverrides: {
4343

4444
In projects based on Astro or Starlight, you also have the option to create a file named `ec.config.mjs` in your project's root directory and export your configuration object as the default export from there:
4545

46-
<ConfigVariants ecConfigFile ins={[]} settings={`
46+
<ConfigVariants onlyEcConfigFile ins={[]} settings={`
4747
// You can set configuration options here
4848
themes: ['dracula', 'github-light'],
4949
styleOverrides: {

‎docs/src/components/ConfigVariants.astro

Lines changed: 68 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,12 @@ type Props = {
66
nonIntegrationSettings: string
77
namedImports?: string[] | undefined
88
imports?: string | undefined
9-
ecConfigFile: boolean
9+
onlyEcConfigFile: boolean
10+
preferEcConfigFile: boolean
1011
noNextJs: boolean
1112
}
1213
13-
const { settings: rawSettings, nonIntegrationSettings: rawNonIntegrationSettings = '', namedImports = [], imports: rawImports, ecConfigFile, noNextJs, ...otherProps } = Astro.props
14+
const { settings: rawSettings, nonIntegrationSettings: rawNonIntegrationSettings = '', namedImports = [], imports: rawImports, onlyEcConfigFile, preferEcConfigFile, noNextJs, ...otherProps } = Astro.props
1415
1516
const tabsToSpaces = (str: string) => str.replace(/\t/g, ' ')
1617
const lines = (str: string) => str.split(/\r?\n/)
@@ -51,7 +52,21 @@ type Variant = {
5152
5253
const variants: Variant = {}
5354
54-
if (!ecConfigFile) {
55+
if (onlyEcConfigFile || preferEcConfigFile) {
56+
variants.Astro = {
57+
title: 'ec.config.mjs',
58+
code: `
59+
import { defineEcConfig[NAMED_IMPORTS] } from 'astro-expressive-code'
60+
[IMPORTS]
61+
62+
export default defineEcConfig({
63+
[SETTINGS]
64+
})
65+
`,
66+
namedImports: namedImports.length ? `, ${namedImports.join(', ')}` : '',
67+
settingsIndent: 1,
68+
}
69+
} else {
5570
variants.Astro = {
5671
title: 'astro.config.mjs',
5772
code: `
@@ -71,6 +86,26 @@ if (!ecConfigFile) {
7186
namedImports: namedImports.length ? `, { ${namedImports.join(', ')} }` : '',
7287
settingsIndent: 3,
7388
}
89+
}
90+
91+
if (onlyEcConfigFile || preferEcConfigFile) {
92+
if (namedImports.length) {
93+
throw new Error(`Named imports from Starlight are not supported in ec.config.mjs due to it being TS-only. Found: ${namedImports.join(', ')}`)
94+
}
95+
variants.Starlight = {
96+
title: 'ec.config.mjs',
97+
code: `
98+
[IMPORTS]
99+
100+
/** @type {import('@astrojs/starlight/expressive-code').StarlightExpressiveCodeOptions} */
101+
export default {
102+
[SETTINGS]
103+
}
104+
`,
105+
namedImports: namedImports.length ? `, ${namedImports.join(', ')}` : '',
106+
settingsIndent: 1,
107+
}
108+
} else {
74109
variants.Starlight = {
75110
title: 'astro.config.mjs',
76111
code: `
@@ -94,70 +129,42 @@ if (!ecConfigFile) {
94129
namedImports: namedImports.length ? `import { ${namedImports.join(', ')} } from '@astrojs/starlight/expressive-code'` : '',
95130
settingsIndent: 4,
96131
}
97-
if (!noNextJs)
98-
variants['Next.js'] = {
99-
title: 'next.config.mjs',
100-
code: `
101-
import createMDX from '@next/mdx'
102-
import rehypeExpressiveCode[NAMED_IMPORTS] from 'rehype-expressive-code'
103-
[IMPORTS]
104-
105-
/** @type {import('rehype-expressive-code').RehypeExpressiveCodeOptions} */
106-
const rehypeExpressiveCodeOptions = {
107-
[SETTINGS]
108-
}
132+
}
109133
110-
/** @type {import('next').NextConfig} */
111-
const nextConfig = {
112-
reactStrictMode: true,
113-
pageExtensions: ["js", "jsx", "ts", "tsx", "md", "mdx"],
114-
}
134+
if (!onlyEcConfigFile && !noNextJs) {
135+
variants['Next.js'] = {
136+
title: 'next.config.mjs',
137+
code: `
138+
import createMDX from '@next/mdx'
139+
import rehypeExpressiveCode[NAMED_IMPORTS] from 'rehype-expressive-code'
140+
[IMPORTS]
115141
116-
const withMDX = createMDX({
117-
extension: /\\.mdx?$/,
118-
options: {
119-
remarkPlugins: [],
120-
rehypePlugins: [
121-
// The nested array structure is required to pass options
122-
// to a rehype plugin
123-
[rehypeExpressiveCode, rehypeExpressiveCodeOptions],
124-
],
125-
},
126-
})
142+
/** @type {import('rehype-expressive-code').RehypeExpressiveCodeOptions} */
143+
const rehypeExpressiveCodeOptions = {
144+
[SETTINGS]
145+
}
127146
128-
export default withMDX(nextConfig)
129-
`,
130-
namedImports: namedImports.length ? `, { ${namedImports.join(', ')} }` : '',
131-
settingsIndent: 1,
147+
/** @type {import('next').NextConfig} */
148+
const nextConfig = {
149+
reactStrictMode: true,
150+
pageExtensions: ["js", "jsx", "ts", "tsx", "md", "mdx"],
132151
}
133-
} else {
134-
variants.Astro = {
135-
title: 'ec.config.mjs',
136-
code: `
137-
import { defineEcConfig[NAMED_IMPORTS] } from 'astro-expressive-code'
138-
[IMPORTS]
139152
140-
export default defineEcConfig({
141-
[SETTINGS]
142-
})
143-
`,
144-
namedImports: namedImports.length ? `, ${namedImports.join(', ')}` : '',
145-
settingsIndent: 1,
146-
}
147-
if (namedImports.length) {
148-
throw new Error(`Named imports from Starlight are not supported in ec.config.mjs due to it being TS-only. Found: ${namedImports.join(', ')}`)
149-
}
150-
variants.Starlight = {
151-
title: 'ec.config.mjs',
152-
code: `
153-
[IMPORTS]
153+
const withMDX = createMDX({
154+
extension: /\\.mdx?$/,
155+
options: {
156+
remarkPlugins: [],
157+
rehypePlugins: [
158+
// The nested array structure is required to pass options
159+
// to a rehype plugin
160+
[rehypeExpressiveCode, rehypeExpressiveCodeOptions],
161+
],
162+
},
163+
})
154164
155-
/** @type {import('@astrojs/starlight/expressive-code').StarlightExpressiveCodeOptions} */
156-
export default {
157-
[SETTINGS]
158-
}
159-
`,
160-
namedImports: namedImports.length ? `, ${namedImports.join(', ')}` : '',
165+
export default withMDX(nextConfig)
166+
`,
167+
namedImports: namedImports.length ? `, { ${namedImports.join(', ')} }` : '',
161168
settingsIndent: 1,
162169
}
163170
}

‎docs/src/content/docs/installation.mdx

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
title: Installing Expressive Code
33
---
44

5+
import { Steps } from '@astrojs/starlight/components'
56
import PackageManagers from '@components/PackageManagers.astro'
67

78
Expressive Code provides integrations into many different frameworks, including Astro, Starlight, Next.js, and any framework that supports rehype plugins.
@@ -16,6 +17,8 @@ Please select your framework to jump to the respective installation instructions
1617

1718
You can add Expressive Code to your Astro site by installing our framework integration `astro-expressive-code`. Follow these steps:
1819

20+
<Steps>
21+
1922
1. Change into the directory of your Astro site. If you do not have an existing Astro site, first create a new one using `npm create astro@latest` (other package managers like `pnpm` and `yarn` are also supported).
2023

2124
2. Use Astro's CLI to install `astro-expressive-code`:
@@ -26,6 +29,8 @@ You can add Expressive Code to your Astro site by installing our framework integ
2629

2730
3. You're done! 🎉
2831

32+
</Steps>
33+
2934
## Starlight
3035

3136
:::tip
@@ -36,6 +41,8 @@ Expressive Code is already included in Starlight. You're done! 🎉
3641

3742
You can add Expressive Code to your Next.js site by installing our framework integration `rehype-expressive-code`. Follow these steps:
3843

44+
<Steps>
45+
3946
1. Change into the directory of your Next.js site.
4047

4148
2. Add the integration package `rehype-expressive-code` to your site's dependencies:
@@ -76,3 +83,5 @@ You can add Expressive Code to your Next.js site by installing our framework int
7683
```
7784

7885
4. You're done! 🎉
86+
87+
</Steps>

‎docs/src/content/docs/key-features/code-component.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@ In these cases, you will receive the following error message when trying to use
113113
114114
As instructed by the error message, you can fix this issue by creating a separate `ec.config.mjs` file in your project root and moving your Expressive Code options object into the config file. Here is an example of how this file could look like if you're using the [collapsible sections plugin](/plugins/collapsible-sections/):
115115

116-
<ConfigVariants ecConfigFile ins={[]}
116+
<ConfigVariants onlyEcConfigFile ins={[]}
117117
imports={`
118118
import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'
119119
`}

‎docs/src/content/docs/plugins/collapsible-sections.mdx

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import { Code } from '@astrojs/starlight/components'
88
import PropertySignature from '@components/PropertySignature.astro'
99
import ConfigVariants from '@components/ConfigVariants.astro'
1010
import PackageManagers from '@components/PackageManagers.astro'
11-
import { Tabs, TabItem } from '@astrojs/starlight/components'
11+
import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'
1212

1313
This optional plugin allows you to reduce long code examples to their relevant parts by collapsing any line ranges that are not relevant to the example.
1414

@@ -18,13 +18,18 @@ The lines of collapsed sections will be replaced by a clickable `X collapsed l
1818

1919
Before being able to use collapsible sections in your code blocks, you need to install the plugin as a dependency and add it to your configuration:
2020

21+
<Steps>
22+
2123
1. Add the package to your site's dependencies:
2224

2325
<PackageManagers pkg="@expressive-code/plugin-collapsible-sections" />
2426

25-
2. Add the plugin to your site's configuration by passing it in the `plugins` list:
27+
2. Add the plugin to your site's configuration by passing it in the `plugins` list.
28+
29+
In Astro and Starlight projects, we recommend putting this option in `ec.config.mjs` to ensure that the [`<Code>` component](/key-features/code-component/#using-an-ecconfigmjs-file) can still be used on your site.
2630

2731
<ConfigVariants
32+
preferEcConfigFile
2833
imports={`
2934
import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'
3035
`}
@@ -33,6 +38,8 @@ Before being able to use collapsible sections in your code blocks, you need to i
3338
`}
3439
/>
3540

41+
</Steps>
42+
3643
## Usage in markdown / MDX
3744

3845
To mark a section as collapsible, you need to add **meta information** to your code blocks. This is done by appending `collapse={X-Y}` to your opening code fence, indicating a collapsed section from line `X` to (and including) line `Y`.

‎docs/src/content/docs/plugins/line-numbers.mdx

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,21 +7,26 @@ title: Line Numbers
77
import PropertySignature from '@components/PropertySignature.astro'
88
import ConfigVariants from '@components/ConfigVariants.astro'
99
import PackageManagers from '@components/PackageManagers.astro'
10-
import { Tabs, TabItem } from '@astrojs/starlight/components'
10+
import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'
1111

1212
This optional plugin allows you to display line numbers in your code blocks. The line numbers are displayed in the gutter to the left of the code.
1313

1414
## Installation
1515

1616
Before being able to display line numbers in your code blocks, you need to install the plugin as a dependency and add it to your configuration:
1717

18+
<Steps>
19+
1820
1. Add the package to your site's dependencies:
1921

2022
<PackageManagers pkg="@expressive-code/plugin-line-numbers" />
2123

22-
2. Add the plugin to your site's configuration by passing it in the `plugins` list:
24+
2. Add the plugin to your site's configuration by passing it in the `plugins` list.
25+
26+
In Astro and Starlight projects, we recommend putting this option in `ec.config.mjs` to ensure that the [`<Code>` component](/key-features/code-component/#using-an-ecconfigmjs-file) can still be used on your site.
2327

2428
<ConfigVariants
29+
preferEcConfigFile
2530
imports={`
2631
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'
2732
`}
@@ -30,6 +35,8 @@ Before being able to display line numbers in your code blocks, you need to insta
3035
`}
3136
/>
3237

38+
</Steps>
39+
3340
## Usage in markdown / MDX
3441

3542
### Displaying line numbers per block

‎docs/src/content/docs/reference/configuration.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ styleOverrides: {
4747

4848
In projects based on Astro or Starlight, you also have the option to create a file named `ec.config.mjs` in your project's root directory and export your configuration object as the default export from there:
4949

50-
<ConfigVariants ecConfigFile ins={[]} settings={`
50+
<ConfigVariants onlyEcConfigFile ins={[]} settings={`
5151
// You can set configuration options here
5252
themes: ['dracula', 'github-light'],
5353
styleOverrides: {

‎docs/src/content/docs/reference/plugin-api.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ Represents a strongly typed set of style settings provided by a plugin (or core)
7272

7373
The constructor expects an object with a `defaultSettings` property. This property must contain the default values for all settings and will be made available as a public instance property. Allowed default value types are plain values (e.g. strings), an array of two values to provide a dark and light variant, or resolver functions that return one of these types.
7474

75-
If you are writing a plugin that provides style overrides, please merge your style overrides into the `StyleOverrides` interface declaration provided by the `@expressive-code/core` module. You can see an example of this below.
75+
If you are writing a plugin that provides style overrides, please merge your style overrides into the `StyleSettings` interface declaration provided by the `@expressive-code/core` module. You can see an example of this below.
7676

7777
As a plugin author, you should also assign an instance of this class to your plugin's
7878
`styleSettings` property. This allows the engine to automatically declare CSS variables for your style settings in all theme variants defined in the config.

0 commit comments

Comments
 (0)