Docusaurus Sidebar File Icon Plugin

Adds file icons to the Docusaurus sidebar based on file names or tags.

Features

• Maps filenames and/or front-matter tags to icon components.
• Copies a theme override (theme/Root.tsx) into your site to render icons in the sidebar.
• Provides an icons/ collection that is copied to src/icons (preserves existing files).

Install

npm install sidebar-fileicon-plugin

Setup

• After installing the package, run the included setup script to copy the theme override and icons into your site.

npm run setup

• The script will copy theme/Root.tsx to src/theme/Root.tsx and the package icons/ folder into src/icons.
• Existing files in the destination are preserved by default (the script skips overwriting).

Usage

• Configure the plugin in your docusaurus.config.js (if the plugin provides runtime options) or use the shipped theme override to render icons.

Icon usage

To enable file icons in the sidebar, add this front-matter field to your .md or .mdx file:

---
icon: <color>/<icon>
---

Available icons (so far): wip, empty, and full.

You can choose a color name like green or red; hex values (for example #fff) are not supported by the plugin.

Example:

---
icon: green/full
id: <id>
---

Testing locally (developer)

1. Link the package for iterative development

# In the plugin repo
npm install
npm link

# In your Docusaurus site repo
npm link sidebar-fileicon-plugin
npm install
npm run start

2. Pack and install

npm install
npm pack
npm install /path/to/sidebar-fileicon-plugin-<version>.tgz

3. Run the setup script to copy theme and icons

npm run setup

Verification

• Confirm src/theme/Root.tsx and src/icons exist in your site after running the setup script.
• Run your site (npm run start) and verify icons appear in the sidebar.

License

GPL-3.0-only