Interactive file/folder tree diagrams for VitePress. Write YAML or paste ASCII — get a beautiful, collapsible Vue component.

# pnpm
pnpm add vitepress-plugin-folder-tree

# npm
npm install vitepress-plugin-folder-tree

# yarn
yarn add vitepress-plugin-folder-tree

1. VitePress config — .vitepress/config.mts:

import { defineConfig } from 'vitepress'
import { withFolderTree } from 'vitepress-plugin-folder-tree'

export default withFolderTree(
  defineConfig({ title: 'My Docs' })
)

2. Import styles — .vitepress/theme/index.ts:

import DefaultTheme from 'vitepress/theme'
import 'vitepress-plugin-folder-tree/style.css'

export default {
  extends: DefaultTheme,
}

CSS is shipped as a separate file for better performance, caching, and CSP compatibility.

Write a fenced code block with language tree (or folder-tree / file-tree):

```tree
- name: src
  children:
    - name: components
      children:
        - Button.vue
        - Modal.vue
    - App.vue
    - main.ts
- package.json
```

Each root item is a string (file) or object (file/folder with metadata):

```tree
- name: src
  description: "Source code"
  children:
    - name: index.ts
      highlight: true
    - utils.ts
- README.md
```

Paste tree command output — auto-detected by ├── / └── characters:

```tree
├── src
│   ├── index.ts
│   └── utils.ts
├── package.json
└── README.md
```

Load tree from a separate file (YAML, JSON, or JS module). All URL resolution happens at build time — no client-side fetching:

```tree
url: /trees/my-project.yaml
```

JS modules run in Node.js at build time, so you can use fs.readFileSync, fetch() for remote APIs, or any Node API:

// public/trees/my-project.js
import { readFileSync } from 'fs';
import { dirname, join } from 'path';
import { fileURLToPath } from 'url';

export default function () {
  const __dir = dirname(fileURLToPath(import.meta.url));
  const data = JSON.parse(readFileSync(join(__dir, 'data.json'), 'utf-8'));
  return [{ name: 'project', children: data.files }];
}

Generate tree from a real directory at build time:

```tree
from: ./src
depth: 3
exclude:
  - "*.test.ts"
```

With file content preview (hover to see, click to copy):

```tree
from: ./src
preview: true
maxPreviewSize: 4096
openDepth: 2
```

* name is optional when tab is set — the tab label is used as the name.

- name: config.ts
  status: modified
- name: new-feature.ts
  status: added
- name: old-module.ts
  status: deleted

Use tab on root-level nodes to create switchable views:

```tree
- tab: "Frontend"
  children:
    - name: src
      children:
        - App.vue
        - main.ts
    - package.json
- tab: "Backend"
  children:
    - name: src
      children:
        - index.ts
        - server.ts
    - package.json
```

Each tab shows the children of its root node. All toolbar operations (search, copy, download, shell script) work within the active tab.

Append #path/to/file to the page URL:

https://example.com/docs/guide.html#src/components/Button.vue

The tree will:

1. Switch to the correct tab (if tabs are used)
2. Expand all ancestor folders
3. Scroll to the node
4. Highlight it with a pulse animation

Add preview to show code/text in an IDE-style tooltip on hover:

- name: index.ts
  preview: "import { createApp } from 'vue'\ncreateApp(App).mount('#app')"

Tooltip appears after 600 ms, disappears on mouse leave.

Click the >_ button in the toolbar to copy a shell script (mkdir -p + touch) that recreates the tree structure. Paste into your terminal to scaffold a project instantly.

- name: .env
  icon: "\U0001F510"

Map filenames or extensions to emoji/Iconify classes:

export default withFolderTree(
  defineConfig({}),
  {
    iconMap: {
      'vite.config.ts': '\u26A1',
      'ts': 'logos:typescript-icon',
      'vue': 'logos:vue',
    },
  }
)

Priority: full filename → extension → default SVG.

Default excludes: node_modules, .git, .DS_Store, dist, .cache, .vitepress, __pycache__, .next, .nuxt, .idea, .vscode, coverage, and more.

```tree
from: ./src
include:
  - "*.ts"
  - "*.tsx"
exclude:
  - "*.test.ts"
options:
  defaultOpen: false
```

Access the context menu on any node:

Menu actions:

• Copy Name — file/folder name (e.g. Button.vue)
• Copy Path — full tree path (e.g. src/components/Button.vue)

Press Escape to close.

export default withFolderTree(
  defineConfig({}),
  {
    languages: ['tree', 'file-tree', 'folder-tree'], // trigger languages
    defaultOpen: true,       // folders expanded by default
    showToolbar: true,       // show toolbar
    showBadges: true,        // auto file/folder count badges
    interactive: true,       // allow expand/collapse
    root: process.cwd(),     // base path for `from:` resolution
    iconMap: {},             // global icon overrides
  }
)

Override global settings per code block:

```tree
options:
  defaultOpen: false
  showToolbar: false
  showBadges: false
  interactive: false
tree:
  - name: src
    children:
      - index.ts
```

import {
  validateTreeInput,
  parseTree,
  parseAsciiTree,
  scanDirectory,
} from 'vitepress-plugin-folder-tree'

// Validate YAML
const result = validateTreeInput(yamlString)
// { valid: boolean, errors: string[], warnings: string[] }

// Parse YAML → TreeNode[]
const { tree, options } = parseTree(yamlString)

// Parse ASCII → TreeNode[]
const nodes = parseAsciiTree(asciiString)

// Scan filesystem → TreeNode[]
const tree = scanDirectory('/path', 5, ['node_modules'], ['*.ts'])

pnpm install
pnpm build        # build plugin
pnpm dev          # dev server with examples
pnpm docs:build   # build example docs

• GitHub
• npm
• Issues
• Live Demo

MIT © s00d