Configuring the Language Badge Plugin

Basic Usage

Default Configuration

The plugin works out of the box with sensible defaults:

import { pluginLanguageBadge } from 'expressive-code-language-badge';

export default {
  plugins: [
    pluginLanguageBadge(), // Uses all default options.
  ],
};

Configuration Options

Core Options

Option	Type	Default	Description
languageMap	Record<string, string>	{ cpp: 'C++' }	Mapping of language identifiers to display labels
textTransform	'uppercase' | 'lowercase'	'uppercase'	Text transform for language labels
excludeLanguages	string[]	[]	Array of languages to exclude from showing badges

Custom Configuration

You can customize the plugin behavior by passing an options object to pluginLanguageBadge():

ec.config.mjs

import { defineEcConfig } from "@astrojs/starlight/expressive-code";
import { pluginLanguageBadge } from 'expressive-code-language-badge';

export default defineEcConfig({
  plugins: [
    pluginLanguageBadge({
      textTransform: 'lowercase',
      excludeLanguages: ['json', 'css', 'bash'],
      languageMap: {
        cpp: 'C++',
        csharp: 'C#',
        ts: 'TypeScript',
        js: 'JavaScript',
      },
    }),
  ],
});

Custom Language Mapping

You can customize how language names are displayed:

pluginLanguageBadge({
  languageMap: {
    cpp: 'C++',
    csharp: 'C#',
    py: 'Python',
    js: 'JavaScript',
    ts: 'TypeScript',
    sh: 'Shell',
  },
})

Excluding Languages

You can exclude specific languages from showing badges:

pluginLanguageBadge({
  excludeLanguages: ['json', 'yaml', 'txt'],
})

Text Transform

Control the text casing of language badges:

// Uppercase (default)
pluginLanguageBadge({
  textTransform: 'uppercase', // Shows "JAVASCRIPT", "PYTHON", etc.
})

// Lowercase
pluginLanguageBadge({
  textTransform: 'lowercase', // Shows "javascript", "python", etc.
})

Examples

Production Configuration

pluginLanguageBadge({
  textTransform: 'uppercase',
  excludeLanguages: ['json', 'txt'],
  languageMap: {
    cpp: 'C++',
    csharp: 'C#',
    ts: 'TypeScript',
    js: 'JavaScript',
  },
})

Minimal Configuration

ec.config.mjs

pluginLanguageBadge({
  languageMap: {
    cpp: 'C++',
  },
})

The language badge will appear in the top-right corner of your code blocks, providing users with clear visual indication of the code language.

Language Badge Plugin Theming System

You can override the default styles in your Expressive Code config using the styleOverrides.languageBadge object if you want to change the colors, fonts, or other styles of the language badge.

For more information on styleOverrides, see the Expressive Code style overrides documentation.

Available Style Options

Badge Styling

• fontSize: Font size of the language badge

  • Default: '0.75rem'
  • Example: '0.85rem', '14px'

• fontColor: Text color of the language badge

  • Default: 'darkblue'
  • Example: '#ffffff', 'rgba(255, 255, 255, 0.8)'

• fontWeight: Font weight of the language badge

  • Default: 'bold'
  • Example: '500', '600', 'normal'

• background: Background color of the language badge

  • Default: 'lightblue'
  • Example: '#f0f0f0', 'rgba(0, 0, 0, 0.1)'

• borderRadius: Border radius of the language badge

  • Default: '0.25rem'
  • Example: '0.5rem', '4px'

• opacity: Opacity of the language badge

  • Default: '1'
  • Example: '0.8', '0.95'

• borderWidth: Border width of the language badge

  • Default: '0px'
  • Example: '1px', '2px'

• borderColor: Border color of the language badge

  • Default: 'transparent'
  • Example: 'darkgray', '#000000'

Quick Start

{
  plugins: [pluginLanguageBadge()],
  styleOverrides: {
    languageBadge: {
      fontSize: '0.85rem',
      fontColor: 'darkblue',
      fontWeight: '600',
      background: 'lightgray',
      borderRadius: '0.15rem',
      opacity: '0.95',
      borderWidth: '1px',
      borderColor: 'darkgray',
    }
  }
}

Complete Style Configuration Example

Here’s a complete example showing all available style options with their default values:

{
  plugins: [pluginLanguageBadge()],
  styleOverrides: {
    languageBadge: {
      fontSize: '0.75rem',
      fontColor: 'darkblue',
      fontWeight: 'bold',
      background: 'lightblue',
      borderRadius: '0.25rem',
      opacity: '1',
      borderWidth: '0px',
      borderColor: 'transparent',
    }
  }
}

Custom Style Example

{
  plugins: [pluginLanguageBadge()],
  styleOverrides: {
    languageBadge: {
      // Prominent badge style with border
      fontSize: '0.85rem',
      fontColor: '#e6f3ff',
      fontWeight: '600',
      background: '#1a1a2e',
      borderRadius: '0.5rem',
      opacity: '0.95',
      borderWidth: '2px',
      borderColor: '#0f3460',
    }
  }
}