# File Tree

Display directory structures with collapsible folders and inline file metadata.

import { FileTree } from '@prosefly/astro-components';

Use `FileTree` to show project structure, package exports, documentation
folders, or any directory layout where hierarchy matters more than long prose.

## Import

```mdx
import { FileTree } from '@prosefly/astro-components';
```

## Basic Usage

The syntax follows Starlight: wrap a single unordered Markdown list inside
`FileTree`.

<FileTree>

- astro.config.mjs
- package.json
- src
  - content
    - docs
      - index.mdx
      - components/
  - theme.config.ts
- public/

</FileTree>

```mdx
<FileTree>

- astro.config.mjs
- package.json
- src
  - content
    - docs
      - index.mdx
      - components/
  - theme.config.ts
- public/

</FileTree>
```

## Directories

An item becomes a directory when it has nested children. You can also add a
trailing `/` to mark an empty directory.

<FileTree>

- src
  - components
    - Callout.astro
    - Tabs.astro
  - content/
- public/

</FileTree>

Directories render as native disclosure controls, so readers can collapse and
expand sections of the tree.

## Comments

Add a comment by writing text after the file or directory name. Comments can use
inline Markdown.

<FileTree>

- astro.config.mjs registers the Lotus integration
- src
  - theme.config.ts the **main** theme configuration file
  - content contains the docs collection
    - docs generated from `themeConfig.sidebars`
- packages
  - astro-components shared MDX components
  - astro-theme-lotus theme integration and layouts

</FileTree>

```mdx
<FileTree>

- astro.config.mjs registers the Lotus integration
- src
  - theme.config.ts the **main** theme configuration file
  - content contains the docs collection

</FileTree>
```

## Highlight Entries

Make a file or directory name bold to highlight the important entry.
The highlight covers the file or directory icon and name; comments stay outside
the highlighted area.

<FileTree>

- packages
  - astro-components
    - src
      - mdx
        - **FileTree.astro**
        - rehype-file-tree.ts
        - Tabs.astro
  - astro-theme-lotus

</FileTree>

## Placeholders

Use `...` or `…` when a tree intentionally omits files.

<FileTree>

- src
  - components
    - Callout.astro
    - Steps.astro
    - …
  - content
    - docs
      - overview.mdx
      - …

</FileTree>

## Special Names

Wrap file names in backticks when they contain spaces, leading underscores, or
characters that Markdown may treat as formatting.

<FileTree>

- `__init__.py`
- `README copy.md`
- **`theme.config.ts`** highlighted with code formatting
- docs
  - `getting started.mdx`
  - `faq?.mdx`

</FileTree>

## File Icons

File icons are selected from the file name or extension. By default, `FileTree`
uses simple Lucide file and folder icons.

<FileTree>

- component.astro code file
- config.yaml config file
- tokens.css stylesheet
- logo.svg image asset
- notes.md text content
- archive.zip generic file

</FileTree>

Use `iconSet="vscode-icons"` for richer file-type icons.

<FileTree iconSet="vscode-icons">

- astro.config.mjs
- package.json
- tsconfig.json
- src
  - components
    - Header.astro
    - SearchDialog.ts
  - content
    - docs
      - overview.mdx
      - images.md
  - styles
    - app.css
- public
  - logo.svg

</FileTree>

```mdx
<FileTree iconSet="vscode-icons">

- astro.config.mjs
- package.json
- tsconfig.json
- src
  - components
    - Header.astro
    - SearchDialog.ts

</FileTree>
```

## Props

| Prop | Type | Default |
| --- | --- | --- |
| `iconSet` | `'lucide' \| 'vscode-icons'` | `'lucide'` |

## Syntax Rules

- The direct content of `FileTree` must be exactly one unordered Markdown list.
- Keep a blank line after `<FileTree>` and before `</FileTree>` so MDX parses
  the list as Markdown.
- Use nested list items for directory contents.
- Use bold text to highlight an entry name.
- Put comments after the name on the same list item.
- Use `...` or `…` for omitted files.