Add collapse level to FileTree

[iskandersierra]

What version of starlight are you using?

0.28.3

What is your idea?

I would like a property collapseLevel on FileTree to allow the starting tree to be collapsed to that level.

Why is this feature necessary?

To document about project folder structure it would be nice to have the tree with enough levels to document about the project structure, but not to occupy too much space when first shown. A per folder way to do it would be too much in my opinion, but a global collapseLevel would be good enough for that.

E.g. collapseLevel=0 would show all the folders at first level collapsed, collapseLevel=1 would open the first-level folders, but the second level would be collapsed, and so on ...

Do you have examples of this feature in other projects?

<FileTree collapseLevel="0">
- README.md
- docs
  - guides
  - architecture
  - ...
- src
  - data-access
  - ...
- test
  - ...
- package.json
<FileTree>

Would show as:

• README.md
• docs
• src
• test
• package.json

Participation

• I am willing to submit a pull request for this feature.

[delucis]

Thanks for the idea! I’m not 100% convinced a top-level attribute is the most helpful way to approach this. For example, I can totally imagine a situation where you want to collapse different directories at different depths and this would not really help there, for example you might have something like this where you’d like to collapse the top-level misc/ but still show the src/important/thing.js file:

<FileTree>
- misc/
  - files/
  - i-want.to
  - hide.md
- src/
  - important/
    - thing.js
</FileTree>

To support that, I guess would require some kind of custom syntax per directory. Not super simple to come up with but we could think about it if other people have the same need.

[iskandersierra]

That is correct. I'm thinking something like this could be used:

<FileTree>
+ misc/
  - files/
  - i-want.to
  - hide.md
- src/
  - important/
    - thing.js
</FileTree>

When showing a folder with content, using + would indicate that the folder should be collapsed at first view. What do you think?

[delucis]

Hmm, that would break the default Markdown list syntax which this is building on and I suspect we wouldn’t even see that input: the component receives the rendered HTML rather than the raw Markdown, so in this case we’d need a syntax that survives compiling from Markdown to HTML as well as surviving stuff like formatters in the editor (i.e. running something like Prettier shouldn’t mess with the syntax)

[iskandersierra]

It makes sense. I was thinking on a syntax involving only the content of the item, but it might break some users out there.

Some suggestions:

- [+] folder\ Replace [+] by any string that could be more intuitive: `[v]`, `[^]`, etc.
- folder\ collapsed=true Allow `key=value` assignments in the beginning of the comments section to allow for `collapsed` and any other per-item properties we could add in the future, like `icon=angular`, etc.

What do you think?