Install Expressive Code on Astro

Update (2025): This guide now lives inside the Astro Erudite series. The layout snippet that referenced PostDetails.astro belonged to the Astro Paper starter—Erudite ships its own enhancements through public/scripts/post-enhancements.js, so you no longer need to manually strip tabindex attributes.

1. Syntax Highlighter

Astro comes with Shiki preconfigured as the syntax highlighter, which provides great looking code blocks out of the box. However, if you want additional features like line highlighting, line numbers, editor-terminal frame, and more customization options, you may want to look at using expressive-code instead.

Expressive-code is a code rendering library that provides integrations into many different frameworks, including Astro, Starlight, Next.js, and any framework that supports remark plugins. This allows you to have a consistent look and functionality for your code blocks across different platforms.

2. Installation

1. Install the expressive-code package:

npx astro add astro-expressive-code

2. Update astro.config.ts to register Expressive Code alongside the other integrations:

1
import { defineConfig } from 'astro/config'
2
import expressiveCode from 'astro-expressive-code'
3
import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'
4
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'
5

6
import mdx from '@astrojs/mdx'
7
import react from '@astrojs/react'
8
import sitemap from '@astrojs/sitemap'
9
import icon from 'astro-icon'
10
import tailwindcss from '@tailwindcss/vite'
11

12
import { SITE } from '@/consts'
13

14
export default defineConfig({
15
  site: SITE.href,
16
  integrations: [
17
    expressiveCode({
18
      themes: ['github-light', 'github-dark'],
19
      plugins: [pluginCollapsibleSections(), pluginLineNumbers()],
20
      useDarkModeMediaQuery: false,
21
      themeCssSelector: (theme) => `[data-theme="${theme.name.split('-')[1]}"]`,
22
      defaultProps: {
23
        wrap: true,
24
        collapseStyle: 'collapsible-auto',
25
        overridesByLang: {
26
          'ansi,bat,bash,batch,cmd,console,powershell,ps,ps1,psd1,psm1,sh,shell,shellscript,shellsession,text,zsh':
27
            {
28
              showLineNumbers: false,
29
            },
30
        },
31
      },
32
    }),
33
    mdx(),
34
    react(),
35
    sitemap(),
36
    icon(),
37
  ],
38
  vite: {
39
    plugins: [tailwindcss()],
40
  },
41
})

3. Configuration

Expressive Code exposes plenty of styling hooks. The Erudite setup above keeps the light/dark pairing aligned with the site theme tokens, disables noisy line numbers for shell output, and leans on collapsible sections for long snippets. Adjust styleOverrides or defaultProps as needed, then rerun pnpm run lint to make sure the config still satisfies the schema.

With expressive-code integrated into your Astro project, you’ll have more control over the styling and functionality of your code blocks.

4. 2025 Refresh

Erudite now loads the copy-button behaviour and tab-index cleanup through public/scripts/post-enhancements.js. Extend that file if you need extra interactivity instead of editing layouts directly, and keep the visual adjustments in src/styles/typography.css so the blog and notes remain in sync. See Expressive Code documentation for more extensive setup.