Skip to content
Expressive Code

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:

  1. Add the package to your site’s dependencies:

    Terminal window
    npm i @expressive-code/plugin-collapsible-sections

  2. 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()],
        }),
      ],
    })

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 collapsed
import { 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 default
engine.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 collapsed
import { 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 default
engine.doSomething(1, 2, 3, calcFn)


function calcFn() {
  // You can have multiple collapsed sections
3 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

Type: string | string[]

Collapses the given line range or ranges.

collapsePreserveIndent

Type: 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:

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()],
      styleOverrides: {
        // You can optionally override the plugin's default styles here
        collapsibleSections: {
          closedBackgroundColor: '#68F',
        },
      },
    }),
  ],
})

Available style overrides

closedBackgroundColor

Type: UnresolvedStyleValue Default: ({ theme }) => setAlpha(theme.colors['editor.foldBackground'], 0.2) || 'rgb(84 174 255 / 20%)'

The background color of closed sections.

closedBorderColor

Type: UnresolvedStyleValue Default: ({ theme }) => setAlpha(theme.colors['editor.foldBackground'], 0.5) || 'rgb(84 174 255 / 50%)'

The border color of closed sections.

closedBorderWidth

Type: UnresolvedStyleValue Default: '0'

The border width of closed sections.

closedFontFamily

Type: UnresolvedStyleValue Default: 'inherit'

The font family of the closed section summary text.

closedFontSize

Type: UnresolvedStyleValue Default: 'inherit'

The font size of the closed section summary text.

closedLineHeight

Type: UnresolvedStyleValue Default: 'inherit'

The line height of the closed section summary text.

closedMargin

Type: UnresolvedStyleValue Default: '0'

The margin around closed sections.

closedPaddingBlock

Type: UnresolvedStyleValue Default: '4px'

The block padding of closed sections.

closedTextColor

Type: UnresolvedStyleValue Default: 'inherit'

The text color of the closed section summary text.

openBackgroundColor

Type: UnresolvedStyleValue Default: 'transparent'

The background color of open sections.

openBorderColor

Type: UnresolvedStyleValue Default: 'transparent'

The border color of open sections.

openBorderWidth

Type: UnresolvedStyleValue Default: '1px'

The border width of open sections.

openMargin

Type: UnresolvedStyleValue Default: '0'

The margin around open sections.

openPadding

Type: UnresolvedStyleValue Default: '0'

The padding of open sections.