File Tree

当层级结构比长段正文更重要时，使用 FileTree 展示 project structure、package exports、 documentation folders 或其他 directory layout。

Import

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

Basic Usage

语法跟随 Starlight：在 FileTree 中包裹一个 unordered Markdown list。

• astro.config.mjs
• package.json
• Directory src

  • Directory content

    • Directory docs

      • index.mdx
      • Directory components/

        • …
  • theme.config.ts
• Directory public/

  • …

<FileTree>

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

</FileTree>

Directories

当一个 item 有 nested children 时，它会成为 directory。你也可以添加结尾 / 来标记空目录。

• Directory src

  • Directory components

    • Callout.astro
    • Tabs.astro
  • Directory content/

    • …
• Directory public/

  • …

Directories 渲染为原生 disclosure controls，所以读者可以 collapse 和 expand 树中的 section。

Comments

在 file 或 directory name 后面写文本即可添加 comment。Comments 可以使用 inline Markdown。

• astro.config.mjsregisters the Lotus integration
• Directory src

  • theme.config.tsthe main theme configuration file
  • Directory contentcontains the docs collection

    • docsgenerated from themeConfig.sidebars
• Directory packages

  • astro-componentsshared MDX components
  • astro-theme-lotustheme integration and layouts

<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

将 file 或 directory name 加粗，可以突出重要 entry。Highlight 会包含 file 或 directory icon 和 name；comments 保持在 highlighted area 外。

• Directory packages

  • Directory astro-components

    • Directory src

      • Directory mdx

        • FileTree.astro
        • rehype-file-tree.ts
        • Tabs.astro
  • astro-theme-lotus

Placeholders

当 tree 有意省略文件时，使用 ... 或 …。

• Directory src

  • Directory components

    • Callout.astro
    • Steps.astro
    • …
  • Directory content

    • Directory docs

      • overview.mdx
      • …

Special Names

当文件名包含空格、前导下划线，或 Markdown 可能当作格式语法的字符时，用反引号包裹文件名。

• __init__.py
• README copy.md
• theme.config.ts highlighted with code formatting
• Directory docs

  • getting started.mdx
  • faq?.mdx

File Icons

File icons 会根据文件名或扩展名选择。默认情况下，FileTree 使用简单的 Lucide file 和 folder icons。

• component.astrocode file
• config.yamlconfig file
• tokens.cssstylesheet
• logo.svgimage asset
• notes.mdtext content
• archive.zipgeneric file

使用 iconSet="vscode-icons" 可显示更丰富的 file-type icons。

• astro.config.mjs
• package.json
• tsconfig.json
• Directory src

  • Directory components

    • Header.astro
    • SearchDialog.ts
  • Directory content

    • Directory docs

      • overview.mdx
      • images.md
  • Directory styles

    • app.css
• Directory public

  • logo.svg

<FileTree iconSet="vscode-icons">

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

</FileTree>

Props

Syntax Rules

• FileTree 的直接内容必须是且只能是一个 unordered Markdown list。
• 在 <FileTree> 后和 </FileTree> 前保留空行，让 MDX 将列表解析为 Markdown。
• 使用 nested list items 表示 directory contents。
• 使用 bold text 突出 entry name。
• 将 comments 放在同一个 list item 中的 name 后面。
• 使用 ... 或 … 表示省略的文件。