How to add custom code block themes in Starlight

In Starlight, we have an integrated solution for incorporating code blocks with syntax highlighting into our projects. This functionality is powered by astro-expressive-code.

We have a list of builded themes that can be readily utilized. However, there may be scenarios where customization of these themes is desired:

• Making adjustments to an existing theme.
• Creating a theme from the ground up to harmonize with our brand or design aesthetics.

ExpressiveCode supports several theme structures: ShikiTheme or ExpressiveCodeTheme.

In my case, I wanted to refine the one-dark-pro theme to improve accessibility by adjusting the contrast.

How to create a theme?

"undefined" anchor link

I just went to one-dark-pro theme, also available in your node_modules, and get the code.

And then, I proceed to customize the desired colors.

export const theme = {
  name: 'one-dark-pro',
  type: 'dark',
  semanticHighlighting: true,
  semanticTokenColors: {
    // ...
  },
  tokenColors: [
    // ...
  ],
  colors: {
    // ...
  },
}

The final step consists in importing the theme into your astro.config file. Then, integrate it into the Starlight Astro integration settings, within the expressiveCode configuration wrapped into the ExpressiveCodeTheme constructor.

import starlight from '@astrojs/starlight'
import { defineConfig } from 'astro/config'
import { ExpressiveCodeTheme } from 'astro-expressive-code'
import { theme } from './integrations/custom-theme'

export default defineConfig({
  integrations: [
    starlight({
      expressiveCode: {
        themes: [new ExpressiveCodeTheme(theme), 'github-light'],
      },
    }),
  ],
})

That’s all! Now, you can enjoy your custom code blocks with syntax highlighting theme.

Happy coding! 🚀