Labels & Icons

Code blocks can display a file path label and an automatically detected language icon in the header.

File labels

Add a label using the [path/to/file] syntax in the code block meta:

```ts [src/index.ts]
import { createApp } from './app'
```

Renders as:

src/index.ts
import { createApp } from './app'

The label appears in the top-right corner of the code block, giving readers context about which file the code belongs to.

More examples

src/main.rs
fn main() {
    println!("Hello, world!");
}

app/main.py
from fastapi import FastAPI

app = FastAPI()

package.json
{
  "name": "@explainer/docs",
  "version": "1.0.0"
}

docker-compose.yml
services:
  docs:
    build:
      context: .
      args:
        APP: docs
    ports:
      - "8080:8080"

Language icons

Language icons are automatically detected from the code block language identifier. Over 60 languages are supported with their recognizable icons, including:

TypeScript, JavaScript, JSX, TSX
Python, Rust, Go, Java, C#
HTML, CSS, SCSS, Tailwind
JSON, YAML, TOML
Bash, Shell, Dockerfile
Markdown, MDX
SQL, GraphQL
And many more

No configuration is needed — icons appear automatically when a language is specified.

Smart detection

For shell code blocks (bash, sh, shell), the icon is automatically resolved from the first command in the snippet. For example, a block starting with pnpm install will show the pnpm icon instead of the generic bash icon.

Adding custom icons

All language icons, shell language identifiers, and terminal commands are defined in a single shared file at packages/mdx/src/language-icons.ts. To add support for a new language or tool, add an entry to the languageIcons record:

packages/mdx/src/language-icons.ts
export const languageIcons: Record<string, string> = {
  // ...existing icons
  ruby: 'devicon:ruby',
  rb: 'devicon:ruby',
  php: 'devicon:php',
  swift: 'devicon:swift',
  kotlin: 'devicon:kotlin',
}

Icons use Iconify identifiers in the format {set}:{name}. Common sets used in Explainer:

devicon: — technology and language logos
catppuccin: — aesthetic icon variants
mdi: — Material Design Icons (used as fallback)

Browse available icons at icon-sets.iconify.design.

This file is imported by both the React component (pre/code.tsx) and the Astro component (pre/pre.astro), as well as the code group tabs (code-group.tsx). A single change applies everywhere.

Terminal commands

To add icon detection for a new CLI tool in shell code blocks, add it to both the languageIcons map and the terminalCommands array in the same file:

packages/mdx/src/language-icons.ts
export const languageIcons: Record<string, string> = {
  // ...existing icons
  deno: 'devicon:denojs',
}

export const terminalCommands = ['npm', 'npx', 'pnpm', 'yarn', 'bun', 'cargo', 'deno']

This way, a bash code block starting with deno run will display the Deno icon automatically.