File icons

A code block with a title shows the file name in the title bar. The plugin puts the icon of the file type before that name. By default, it uses the coloured icons of vscode-icons, the icon theme of VS Code. Two other coloured sets are available. The one-colour Seti set makes a file look the same as in the Starlight <FileTree> component.

Readers see

The default vscode-icons:

src/index.js

export const greet = (name) => console.log('Hello', name);

Material Icon Theme, with fileIcons.set="material":

app.py

print("Hello from Python")

The Seti icons of the Starlight file tree, with fileIcons.set="seti":

package.json

{ "name": "my-site", "type": "module" }

Catppuccin, with fileIcons.set="catppuccin":

Dockerfile

FROM node:22-alpine
CMD ["node", "src/index.js"]

You write

The default vscode-icons:

```js title="src/index.js"
export const greet = (name) => console.log('Hello', name);
```

Material Icon Theme, with `fileIcons.set="material"`:

```py title="app.py" fileIcons.set="material"
print("Hello from Python")
```

The Seti icons of the Starlight file tree, with `fileIcons.set="seti"`:

```json title="package.json" fileIcons.set="seti"
{ "name": "my-site", "type": "module" }
```

Catppuccin, with `fileIcons.set="catppuccin"`:

```dockerfile title="Dockerfile" fileIcons.set="catppuccin"
FROM node:22-alpine
CMD ["node", "src/index.js"]
```

File icons are on for every code block with a title, so you do not add an attribute. The plugin finds the icon from the file name in the title. When the title is not a file name, the icon comes from the language of the code block. The fileIcons.set attribute changes the icon set for one block, and the fileIcons.set option changes it for the site.

Syntax

Each attribute goes on the code block fence line. The fence line is the first line of the code block, with the language.

Syntax	Where
icon="<name>"	Code block fence line. Sets the icon by name, such as react.
icon=false or no-icon	Code block fence line. Removes the icon.
fileIcons.set="vscode-icons"	Code block fence line. Takes the icon from the coloured vscode-icons icons.
fileIcons.set="material"	Code block fence line. Takes the icon from the coloured Material Icon Theme icons.
fileIcons.set="seti"	Code block fence line. Takes the icon from the one-colour Seti icons.
fileIcons.set="catppuccin"	Code block fence line. Takes the icon from the coloured Catppuccin icons.
fileIcons.style="plain"	Code block fence line. Shows the icon alone.
fileIcons.style="tile"	Code block fence line. Shows the icon on a square with rounded corners.
fileIcons.colour="<colour>"	Code block fence line. Sets a CSS colour for the icon, or for the square of a tile.

Examples

Coloured icons

The vscode-icons, material and catppuccin sets have coloured icons, each with its own rules for file names. Icon sets lists the package that each set needs:

Output

package.json

{ "name": "my-site", "type": "module" }

package.json

{ "name": "my-site", "type": "module" }

package.json

{ "name": "my-site", "type": "module" }

app.py

print("Hello")

Source

```json title="package.json" fileIcons.set="material"
{ "name": "my-site", "type": "module" }
```

```json title="package.json" fileIcons.set="vscode-icons"
{ "name": "my-site", "type": "module" }
```

```json title="package.json" fileIcons.set="catppuccin"
{ "name": "my-site", "type": "module" }
```

```py title="app.py" fileIcons.set="catppuccin" fileIcons.style="tile"
print("Hello")
```

Some icons have a variant for light themes, and the block shows the variant for its theme. In a tile, a coloured icon sits on a neutral square.

GitHub files

Files in a .github folder and .gitattributes get the GitHub icon, from the whole path in the title:

Output

.github/workflows/test.yml

on: [push, pull_request]

Source

```yaml title=".github/workflows/test.yml"
on: [push, pull_request]
```

Icons in a tile

The tile style puts a one-colour icon, such as a Seti icon, on a square in the accent colour of the theme. With a custom colour, the icon is black or white, whichever reads on the square:

Output

app.py

print("Hello")

app.py

print("Hello")

app.js

console.log('Hello');

Source

```py title="app.py" fileIcons.set="seti" fileIcons.style="tile"
print("Hello")
```

```py title="app.py" fileIcons.set="seti" fileIcons.style="tile" fileIcons.colour="#3776ab"
print("Hello")
```

```js title="app.js" fileIcons.set="seti" fileIcons.style="tile" fileIcons.colour="#f7df1e"
console.log('Hello');
```

Set the icon

icon sets the icon by name. In the Seti set, the names are the names of the Starlight icons, with or without the seti: prefix. Each coloured set has its own names, which All file icons shows when you hover over an icon. A Seti name works in every set:

Output

App

export const App = () => <h1>Hello</h1>;

Source

```js title="App" icon="react"
export const App = () => <h1>Hello</h1>;
```

Colour an icon

fileIcons.colour takes a CSS colour. Use light-dark() to give a different colour in the dark and the light theme:

Output

Cargo.toml

[package]
name = "hello"

Source

```toml title="Cargo.toml" fileIcons.colour="light-dark(#f74c00, #b33600)"
[package]
name = "hello"
```

Custom icons

The fileIcons.icons option adds icons by name. This site adds the Nextflow icon from Simple Icons, links it to the .nf extension and the nextflow language, and gives it the Nextflow green:

Output

main.nf

workflow {
    Channel.of('Hello').view()
}

Source

src/content/docs/guide.md

```nextflow title="main.nf"
workflow {
    Channel.of('Hello').view()
}
```

astro.config.mjs

import { siNextflow } from 'simple-icons';

codeblocks({
  fileIcons: {
    icons: { nextflow: siNextflow.svg },
    files: { '.nf': 'nextflow', 'nextflow.config': 'nextflow' },
    languages: { nextflow: { icon: 'nextflow', colour: '#31C9AC' } },
  },
});

Behaviour

• How the plugin finds the icon:
  • First, the icon attribute.
  • Then the rules of the fileIcons.files option, on the whole path in the title.
  • Then the GitHub rules: .github/** and .gitattributes.
  • Then the rules of the icon set. The Seti set reads the file name at the end of the title, as <FileTree> does.
  • In the Seti set, the full name comes first, such as Dockerfile. Then the extension, such as .test.ts and then .ts.
  • Then the language of the code block, such as py or python.
  • Then the default file icon.
  • A false in fileIcons.files or fileIcons.languages stops the search, and the block gets no icon. The icon attribute still sets one.
  • When two keys of fileIcons.files match a title, the later key wins.
• Where icons show:
  • In the title of an editor frame. Terminal frames and code blocks with no title get no icon.
  • Code tabs show the icon of each file on its tab. The code tabs menu shows the icon of each language, custom icons too.
• Colours:
  • A plain icon has the colour of the title text.
  • A tile has the accent colour of the theme, with the icon in the text colour for that accent.
  • A colour from the site or the code block replaces both.
  • A coloured icon keeps its colours. A colour from the site or the code block draws it in that one colour.
• Screen readers:
  • The icon is decorative. Screen readers read the title only.

With the Seti set, a file in a <FileTree> has the same icon as a code block with that file name as its title:

• package.json
• app.py
• Cargo.toml
• Dockerfile
• Directorysrc/

  • index.js

Icon sets

The fileIcons.set option sets the icons for the whole site. vscode-icons and Seti come with the plugin. Material and Catppuccin each need one package, which you add to the site:

Set	Icons	Package
vscode-icons	vscode-icons. The default.	None
material	Material Icon Theme	@iconify-json/material-icon-theme
catppuccin	Catppuccin Icons, in Macchiato colours, and Latte colours in light themes	@iconify-json/catppuccin
seti	The one-colour icons of the Starlight <FileTree>	None

npm install @iconify-json/catppuccin

The plugin has the file name rules of each set, so a site downloads only the icons of the set that it uses. These files show the icon of each set:

File	Seti	Material	vscode-icons	Catppuc­cin
JavaScriptindex.js	javascript	javascript	file-type-js	javascript
TypeScriptindex.ts	typescript	typescript	file-type-typescript	typescript
ReactApp.tsx	react	react-ts	file-type-reactts	typescript-react
Pythonmain.py	python	python	file-type-python	python
Rustmain.rs	rust	rust	file-type-rust	rust
Gomain.go	go	go	file-type-go	go
JavaMain.java	java	java	file-type-java	java
KotlinMain.kt	kotlin	kotlin	file-type-kotlin	kotlin
Cmain.c	c	c	file-type-c	c
C++main.cpp	cpp	cpp	file-type-cpp	cpp
C#Program.cs	c-sharp	csharp	file-type-csharp	csharp
Rubyapp.rb	ruby	ruby	file-type-ruby	ruby
PHPindex.php	php	php	file-type-php	php
Swiftmain.swift	swift	swift	file-type-swift	swift
Shellinstall.sh	shell	console	file-type-shell	bash
PowerShellinstall.ps1	powershell	powershell	file-type-powershell	powershell
HTMLindex.html	html	html	file-type-html	html
CSSstyles.css	css	css	file-type-css	css
Sassstyles.scss	sass	sass	file-type-scss	sass
JSONdata.json	json	json	file-type-json	json
YAMLconfig.yaml	yml	yaml	file-type-yaml	yaml
TOMLconfig.toml	config	toml	file-type-toml	toml
Markdownnotes.md	markdown	markdown	file-type-markdown	markdown
MDXpage.mdx	mdx	mdx	file-type-mdx	markdown-mdx
AstroPage.astro	astro	astro	file-type-astro	astro
VueApp.vue	vue	vue	file-type-vue	vue
SvelteApp.svelte	svelte	svelte	file-type-svelte	svelte
SQLschema.sql	db	database	file-type-sql	database
GraphQLschema.graphql	graphql	graphql	file-type-graphql	graphql
Luainit.lua	lua	lua	file-type-lua	lua
package.json	json	nodejs	file-type-npm	package-json
tsconfig.json	tsconfig	tsconfig	file-type-tsconfig	typescript-config
Dockerfile	docker	docker	file-type-docker	docker
README.md	info	readme	file-type-markdown	readme
.gitignore	git	git	file-type-git	git
GitHub workflow.github/workflows/ci.yml	github	github	github	github

All file iconsSee the icon of every language and file name in each set.

Options

fileIcons

Shows the icon of the file type before the title of a code block. Set it to false to turn the feature off. icon attributes then have no effect.

Type

false | object

Default

On

fileIcons.set

The icons: the coloured icons of vscode-icons, Material Icon Theme or Catppuccin, or the one-colour Seti icons of the Starlight file tree. Material and Catppuccin need their @iconify-json package, such as @iconify-json/catppuccin.

Type

'seti' | 'material' | 'vscode-icons' | 'catppuccin'

Default

'vscode-icons'

fileIcons.style

The icon alone, or the icon on a square with rounded corners. A language or a code block can set its own.

Type

'plain' | 'tile'

Default

'plain'

fileIcons.languages

Settings for the blocks of each language: the icon when the title gives none, as an icon name or SVG markup, or false for none, a CSS colour for the icon or the tile, and the style.

Type

Record<string, { icon?: string | false; colour?: string; style?: 'plain' | 'tile' }>

Default

{}

fileIcons.files

Icon names, or false for no icon, by file name, such as nextflow.config, by extension, such as .nf, or by path pattern, such as .github/**. A * matches within one folder, and ** across folders. They come before the built-in rules.

Type

Record<string, string | false>

Default

{}

fileIcons.icons

Custom icons by name: SVG markup, or the path data of a 24 by 24 icon. A custom name replaces a built-in icon of the same name.

Type

Record<string, string>

Default

{}

To use tiles on the whole site, with the brand colour of Python and an icon for a custom language:

astro.config.mjs

import { siNextflow } from 'simple-icons';

codeblocks({
  fileIcons: {
    style: 'tile',
    icons: { nextflow: siNextflow.svg },
    files: { '.nf': 'nextflow', 'nextflow.config': 'nextflow', 'docs/**/*.md': 'info' },
    languages: {
      python: { colour: '#3776ab' },
      nextflow: { icon: 'nextflow', colour: '#31C9AC' },
    },
  },
});

A key in fileIcons.files with a / or a * is a path pattern. * matches inside one folder, and ** matches across folders.

For one language, the icon in fileIcons.languages can be SVG markup, with no name in fileIcons.icons:

astro.config.mjs

codeblocks({
  fileIcons: { languages: { nextflow: { icon: siNextflow.svg } } },
});

To show no icon for a file type or a language, use false. Here, .mmd files and metro blocks get no icon, but overview.mmd gets the Markdown icon. It comes after .mmd, so it wins:

astro.config.mjs

codeblocks({
  fileIcons: {
    files: { '.mmd': false, 'overview.mmd': 'markdown' },
    languages: { metro: { icon: false } },
  },
});

An icon in fileIcons.icons is SVG markup, or the path data of a 24 by 24 icon. An icon with no fill takes the colour of the icon. An icon with its own colours keeps them.

The size and the default colours are style settings in the codeblocksFileIcons group.

Style settingsSee the size and colour settings of file icons.

Limitations

• Each set has icons only for the file types that it knows. Other files get the default file icon of the set. Add an icon with fileIcons.icons.
• A custom icon with its own colours keeps them in the tile style.
• <FileTree> sees only the file name, so it shows the YAML icon for a file in .github/workflows, where a code block shows the GitHub icon.
• The coloured sets have no GitHub icon, so GitHub files get the Seti icon in every set.
• The plugin carries the rules of each coloured set at one version. An icon that a newer version adds has no rule until the plugin updates its rules.

Related

• Code tabs: show several files as one block, with the icon of each file on its tab.