Skip to content
Expressive Code

Line Numbers

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.

Installation

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:

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

    Terminal window
    npm i @expressive-code/plugin-line-numbers

  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 { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'
    

    export default defineConfig({
      integrations: [
        astroExpressiveCode({
          plugins: [pluginLineNumbers()],
        }),
      ],
    })

Usage in markdown / MDX

Displaying line numbers per block

You can enable or disable line numbers on individual code blocks using the showLineNumbers boolean prop in the meta information of your code blocks. This is done by appending showLineNumbers or showLineNumbers=true to your opening code fence to enable line numbers, or showLineNumbers=false to disable them:

```js showLineNumbers
// This code block will show line numbers
console.log('Greetings from line 2!')
console.log('I am on line 3')
```


```js showLineNumbers=false
// Line numbers are disabled for this block
console.log('Hello?')
console.log('Sorry, do you know what line I am on?')
```

The above code will be rendered like this:

1
// This code block will show line numbers
2
console.log('Greetings from line 2!')
3
console.log('I am on line 3')
// Line numbers are disabled for this block
console.log('Hello?')
console.log('Sorry, do you know what line I am on?')

Changing the starting line number

By default, the line numbers of your code blocks will start at 1. Sometimes, you might want to start at a different number to indicate that the code block is part of a larger file.

To change the starting line number for a code block, you can use the startLineNumber prop in the meta information of your code blocks. This is done by appending startLineNumber= followed by the desired number to your opening code fence:

```js showLineNumbers startLineNumber=5
console.log('Greetings from line 5!')
console.log('I am on line 6')
```

The above code will be rendered like this:

5
console.log('Greetings from line 5!')
6
console.log('I am on line 6')

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

showLineNumbers

Type: boolean Default: true

Whether to show line numbers on the current code block.

The default value of this prop can be changed using the defaultProps option in your Expressive Code configuration. You can also change the default value by language using defaultProps.overridesByLang.

startLineNumber

Type: number Default: 1

The line number to start counting from.

Configuration

After installing the plugin, line numbers will be displayed in the gutter of all code blocks by default. You don’t need to do anything else to enable this feature.

You can configure this default behavior using the defaultProps option in your Expressive Code configuration. You can also change the defaults by language using the sub-property overridesByLang:

astro.config.mjs
import { defineConfig } from 'astro/config'
import astroExpressiveCode from 'astro-expressive-code'
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'


export default defineConfig({
  integrations: [
    astroExpressiveCode({
      plugins: [pluginLineNumbers()],
      defaultProps: {
        // Disable line numbers by default
        showLineNumbers: false,
        // But enable line numbers for certain languages
        overridesByLang: {
          'js,ts,html': {
            showLineNumbers: true,
          },
        },
      },
    }),
  ],
})

Styling

This plugin adds a lineNumbers object to the styleOverrides engine config option, allowing you to customize the visual appearance of the line numbers:

astro.config.mjs
import { defineConfig } from 'astro/config'
import astroExpressiveCode from 'astro-expressive-code'
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'


export default defineConfig({
  integrations: [
    astroExpressiveCode({
      plugins: [pluginLineNumbers()],
      styleOverrides: {
        lineNumbers: {
          // Example: Change the line number foreground colors
          foreground: '#578298a6',
          highlightForeground: '#85c7ebb3',
        },
      },
    }),
  ],
})

Available style overrides

foreground

Type: UnresolvedStyleValue Default: 'inherit'

Allows overriding the foreground color to use for line numbers.

By default, line numbers inherit the gutter foreground color defined by the gutterForeground core style setting.

highlightForeground

Type: UnresolvedStyleValue Default: 'inherit'

Allows overriding the foreground color to use for highlighted line numbers.

By default, highlighted line numbers inherit the gutter highlighted foreground color defined by the gutterHighlightForeground core style setting.