Collapsible Sections
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.
The lines of collapsed sections will be replaced by a clickable X collapsed lines
element. When clicked, the collapsed section will be expanded, showing the previously hidden lines.
Installation
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:
-
Add the package to your site’s dependencies:
Terminal window npm i @expressive-code/plugin-collapsible-sectionsTerminal window pnpm i @expressive-code/plugin-collapsible-sectionsTerminal window yarn add @expressive-code/plugin-collapsible-sections -
Add the plugin to your site’s configuration by passing it in the
plugins
list:astro.config.mjs import { defineConfig } from 'astro/config'import astroExpressiveCode from 'astro-expressive-code'import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'export default defineConfig({integrations: [astroExpressiveCode({plugins: [pluginCollapsibleSections()],}),],})astro.config.mjs import { defineConfig } from 'astro/config'import starlight from '@astrojs/starlight'import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'export default defineConfig({integrations: [starlight({title: 'My Starlight site',expressiveCode: {plugins: [pluginCollapsibleSections()],},}),],})next.config.mjs import createMDX from '@next/mdx'import rehypeExpressiveCode from 'rehype-expressive-code'import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'/** @type {import('rehype-expressive-code').RehypeExpressiveCodeOptions} */const rehypeExpressiveCodeOptions = {plugins: [pluginCollapsibleSections()],}/** @type {import('next').NextConfig} */const nextConfig = {reactStrictMode: true,pageExtensions: ["js", "jsx", "ts", "tsx", "md", "mdx"],}const withMDX = createMDX({extension: /\.mdx?$/,options: {remarkPlugins: [],rehypePlugins: [// The nested array structure is required to pass options// to a rehype plugin[rehypeExpressiveCode, rehypeExpressiveCodeOptions],],},})export default withMDX(nextConfig)
Usage in markdown / MDX
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
.
You can also collapse multiple sections in a single code block by separating them with commas:
```js collapse={1-5, 12-14}// All this boilerplate setup code will be collapsedimport { someBoilerplateEngine } from '@example/some-boilerplate'import { evenMoreBoilerplate } from '@example/even-more-boilerplate'
const engine = someBoilerplateEngine(evenMoreBoilerplate())
// This part of the code will be visible by defaultengine.doSomething(1, 2, 3, calcFn)
function calcFn() { // You can have multiple collapsed sections const a = 1 const b = 2 return a + b}```
The above code block will be rendered like this:
5 collapsed lines
// All this boilerplate setup code will be collapsedimport { someBoilerplateEngine } from '@example/some-boilerplate'import { evenMoreBoilerplate } from '@example/even-more-boilerplate'
const engine = someBoilerplateEngine(evenMoreBoilerplate())
// This part of the code will be visible by defaultengine.doSomething(1, 2, 3, calcFn)
function calcFn() { // You can have multiple collapsed sections3 collapsed lines
const a = 1 const b = 2 return a + b}
Usage in the <Code>
component
The collapsible sections plugin adds the following props to the <Code>
component that allow direct access to its features:
Props
collapse
string
| string
[] Collapses the given line range or ranges.
collapsePreserveIndent
boolean
Default:
true
Determines if collapsed section titles (X collapsed lines
) should be indented to preserve the minimum indent level of their contained collapsed code lines.
Styling
This plugin adds a collapsibleSections
object to the styleOverrides
engine config option, allowing you to customize the visual appearance of the sections:
import { defineConfig } from 'astro/config'import astroExpressiveCode from 'astro-expressive-code'import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'
export default defineConfig({ integrations: [ astroExpressiveCode({ plugins: [pluginCollapsibleSections()], styleOverrides: { // You can optionally override the plugin's default styles here collapsibleSections: { closedBackgroundColor: '#68F', }, }, }), ],})
import { defineConfig } from 'astro/config'import starlight from '@astrojs/starlight'import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'
export default defineConfig({ integrations: [ starlight({ title: 'My Starlight site', expressiveCode: { plugins: [pluginCollapsibleSections()], styleOverrides: { // You can optionally override the plugin's default styles here collapsibleSections: { closedBackgroundColor: '#68F', }, }, }, }), ],})
import createMDX from '@next/mdx'import rehypeExpressiveCode from 'rehype-expressive-code'import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'
/** @type {import('rehype-expressive-code').RehypeExpressiveCodeOptions} */const rehypeExpressiveCodeOptions = { plugins: [pluginCollapsibleSections()], styleOverrides: { // You can optionally override the plugin's default styles here collapsibleSections: { closedBackgroundColor: '#68F', }, },}
/** @type {import('next').NextConfig} */const nextConfig = { reactStrictMode: true, pageExtensions: ["js", "jsx", "ts", "tsx", "md", "mdx"],}
const withMDX = createMDX({ extension: /\.mdx?$/, options: { remarkPlugins: [], rehypePlugins: [ // The nested array structure is required to pass options // to a rehype plugin [rehypeExpressiveCode, rehypeExpressiveCodeOptions], ], },})
export default withMDX(nextConfig)
Available style overrides
closedBackgroundColor
({ theme }) => setAlpha(theme.colors['editor.foldBackground'], 0.2) || 'rgb(84 174 255 / 20%)'
The background color of closed sections.
closedBorderColor
({ theme }) => setAlpha(theme.colors['editor.foldBackground'], 0.5) || 'rgb(84 174 255 / 50%)'
The border color of closed sections.
closedBorderWidth
The border width of closed sections.
closedFontFamily
The font family of the closed section summary text.
closedFontSize
The font size of the closed section summary text.
closedLineHeight
The line height of the closed section summary text.
closedMargin
The margin around closed sections.
closedPaddingBlock
The block padding of closed sections.
closedTextColor
The text color of the closed section summary text.
openBackgroundColor
The background color of open sections.
openBorderColor
The border color of open sections.
openBorderWidth
The border width of open sections.
openMargin
The margin around open sections.
openPadding
The padding of open sections.