Add <FileTree> component

[HiDeoo]

What kind of changes does this PR include?

• Changes or translations of Starlight docs site content
• Changes to Starlight code

Description

This PR adds a <FileTree> component to display the structure of a directory.

This pull request is a draft as some decisions still need to be made regarding various points described below and maybe discuss some implementation details.

Details

Rehype processor and component

Based on the version in the documentation, there is not a lot of changes, only minor ones:

• Documented a bit more the code as I discovered some features while working on this.
• Validation is no longer done with a regex but on the HAST tree itself and more errors are reported.
• Reported errors contain a hint with a link to the component documentation.
• Adds a bunch of tests.

Icons

• Cleaned the icon definitions a bit to only include information that is actually used.
• All icons have been updated as some of them were outdated, just the first letter of the extension thrown in an SVG, etc. When possible, icons from the Unicons icon set have been used.
• All icons have been ran through SVGOMG.
• All icons have been made usable with the <Icon> component.
• The following file icons have been removed for either not having Visual Studio Code icons or sometimes not even finding one: argdown, asm, bsl, cake, cake_php, code-search, cu, d, go (Slidesgo, not the language), grails, hacklang, jade, makefile, mdo, odata, pddl, pddl-happenings, pddl-plan, prolog, rescript, slim, smarty, spring, sublime, twig, wat, wgt.
• The following icons have been added (either made sense to me or are official integrations): alpine, biome, cloudflare, lit, mdx, netlify, node, pnpm, preact, solid, tailwind, vercel.

Regarding my train of thought for the icons, I imagined receiving feature requests for some icons being used in the file tree but not being available in Starlight so I made them all available. And if we decide to not do that, it's easier to remove icons vs. adding them all (I can attest to that ^^).

We may also decide to not include all the icons from my initial push, I just added everything possible based on the existing code and figured it would be easier to remove some of them if they are unwanted.

Docs

I added some documentation for the component and updated the english version of the docs site to use the new component altho I'm not sure what is the best way to handle the removal of the old one to not trigger too much the i18n tracker considering it is a drop-in replacement but this PR should still be tracked as it contains new documentation.

My current idea I have would be:

• Remove the changes to the english version of the docs site to use the new component.
• Prepare a follow-up PR that should be merged right after this one that would:
  • Use [i18nIgnore]
  • Update all documentation pages in all languages to use the new component
  • Remove the old component
  • Remove the following dependencies: hast-util-from-html, hast-util-to-string, hastscript, hast, rehype, and unist-util-visit.

Another approach could be to let translators handle the replacement of the component in their language and wait for them to do so before removing the old component and its dependencies.

If merged, the following tasks should be done before merging:

• Delete the docs/src/content/docs/guides/file-tree-demo.mdx demo file.

[changeset-bot]

🦋 Changeset detected

Latest commit: 9e881ec

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@astrojs/starlight	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
starlight	✅ Ready (Inspect)	Visit Preview	Mar 1, 2024 5:23pm

1 Ignored Deployment

Name	Status	Preview	Updated (UTC)
starlight-i18n	⬜️ Ignored (Inspect)	Visit Preview	Mar 1, 2024 5:23pm

[delucis]

Amazing work on this @HiDeoo as usual! Thanks for your patience waiting for a review. As you know, I’m very much in favour of adding this to our built-in components.

Before diving into the detail wanted to give some big picture feedback about some of the changes.

Adds a bunch of tests.

I love it! This was my big intended chunk of work when moving this into Starlight, so very happy to see it in place 🙌

All icons have been updated as some of them were outdated, just the first letter of the extension thrown in an SVG, etc. When possible, icons from the Unicons icon set have been used.

The existing <FileTree> in docs uses the exact same Seti icon set as VS Code uses by default. I’m not 100% sure if we should move away from that.

Not so much because the alternative icons added in this PR are not nice, just because having an opinion has a cost, and it could be nice to say “We use the default VS Code icon set” and avoid discussion about whether icon X for file type Y is better than icon Z. (It also could make it easier to update when VS Code updates, although I didn’t make the process particularly automated when building out the initial icon set.)

I think filling obvious gaps makes sense, but not sure if we should deviate much more than that. (Although noting there’s still plenty of scope for regular maintenance when dealing with these. For example, since this PR was opened, Biome has already changed icon 😅)

What do you think? There may be more things to consider here, so I’m happy to discuss.

All icons have been made usable with the <Icon> component.

At first this made me nervous, but I think you’re right that this is sensible. (We might want to revisit the icon picker UI in the component docs in the future, but not required for this PR.)

I think the only thing to double check is if any of these icons could clash with names in the Unicons set? I might try adding all the Unicons in a separate PR to see if that helps us spot these things. If it is an issue, maybe we would come up with a prefix for file-type icons?

I'm not sure what is the best way to handle the removal of the old [docs <FileTree> component] to not trigger too much the i18n tracker

We do have special commit message syntax that allows us to opt certain files out, although Lunaria doesn’t document that yet. Nevertheless, I think your proposed strategy is good as it will help translators clearly see the important changes in this PR and easily ignore the follow-up one.

[HiDeoo]

it could be nice to say “We use the default VS Code icon set” and avoid discussion about whether icon X for file type Y is better than icon Z.

I think I am mostly fine with that. Altho, considering we plan to make these icons available in the <Icon> component, and having them all visible in the documentation, I'll have to check but I think we would need to have a list of icons to exclude as some of them do not even render anything.

It also could make it easier to update when VS Code updates

I think considering my previous point and this one, I should make a script to quickly fetch the Seti icons (from the repo used by VSC and not the JSON one which was not updated in 4 years, or maybe re-use the JSON one code, need to check), have an exclusion list, optimize them and then generate what we need in a temporary file or something.

I think filling obvious gaps makes sense

Definitely, I think having at least official integrations, all package managers (so that #1453 is possible), etc. would be a small but nice improvement.

We might want to revisit the icon picker UI in the component docs in the future, but not required for this PR.

Totally agree, maybe even an Icons dedicated page listing at first the various places/components where you can use icons and then the icons themselves with a basic search input could be enough. I'll play around with that idea and see if I can come up with something nice.

I think the only thing to double check is if any of these icons could clash with names in the Unicons set?

I think I could bake that into the script I mentioned earlier so it's easier to maintain on the long run.

I think your proposed strategy is good as it will help translators clearly see the important changes in this PR and easily ignore the follow-up one.

Perfect, I'll start preparing that PR when we are almost done with this one.

---

I'll start thinking and working on that "icon refactor" but if you have any questions or suggestions, feel free to ask.

[HiDeoo]

Small update: played a bit with creating a script that generates definitions based on the most recent icons used by VSC, grab all the associated SVGs and optimize them and export everything to a generated file that we can import and use in Starlight. It supports overriding some icons with already existing built-in ones, and reports name conflicts.

Altho, I just remembered at the end why I didn't do this before: some of their SVGs are huge and won't work as-is with already existing icons. This works fine in isolation by using the entire <svg> element provided but as we want to re-use them with <Icon>, this is not ideal at all.

I personally don't know how to properly resize them programmatically (using a lightweight approach), I usually use Figma for that.

I think there are 2 options here:

• You know how to do that and can give me a hint about it.
• We ditch the idea to automate this process, we use the Seti/VSC icons but I manually scale them down in Figma, optimize them and we use this. Pretty much the same as I did before, but only with Seti icons this time.

Any thoughts?

[HiDeoo]

I noticed MDX uses a default file icon, for example:

• jesseweed/seti-ui does not include mapping or icon for .mdx files
• elviswolcott/seti-icons used in the current docs FileTree does not include anyting for .mdx files either
• The VSC MDX extension provides the icon to .mdx files in VSC.
• My guess would be that you manually "aliased" the .mdx files to use the .md icon but I have no proof of that

I guess there are a few options:

• Do nothing
• Alias .mdx to .md altho it would be an incorrect icon
• Add a new icon for .mdx files (this is what I did in the first iteration of the PR) altho like you said, it's a bit tiny

Plus there are a few other formats like .less, .ejs, .coffee, and .erb, which show icons in VS Code but not in the preview.

Good catch, we lost them when adding prefix support. This is now fixed in the generator and properly reflected in the generated file.

The position of the left line varies depending on what screen I use 🙃

Wow, fun indeed ^^ I tried to repro on all my screens but didn't manage to. I wonder what would be the best approach to force that in order to fix it 🤔

I'll think more about it.

[delucis]

Awesome — I think this should be pretty much good to go I guess. Will do a final pass through things now.

• My guess would be that you manually "aliased" the .mdx files to use the .md icon but I have no proof of that

I’m fairly sure I did that too, although I don’t quite remember 😁

Of the options I guess we should either do nothing or use the official icon, even if we don’t like it. I’m fine with whatever you prefer.

[delucis]

As I thought — looks ready to go for the next minor! Just left one tiny suggestion.

[HiDeoo]

Update the PR:

• I added the MDX icon
• Added Markdown backticks to the errors (added a few more compared to the suggestion for elements, hope it's fine)
• Fixed a link issue in the file tree error hint.
• Removed the file tree demo page

I think for this PR we should be good to go (except if we find any other issues ofc).

The documentation follow up PR is available in #1563

[delucis]

Giving this an official stamp of approval for Friday’s release. Lovely work @HiDeoo! 🌟