TheCurle
commented
8 months ago Moving from ReadTheDocs to Docusaurus was already a significant effort. The reasons we chose Docusaurus are threefold; 1) it's field tested, and used by tons of extremely popular resources and websites, not even Facebook (the creators) is the most well-known user. I have never heard of Astro/Starlight, and while they have some relatively high-end sponsors (Google, NordVPN, The Guardian, Trivago), they don't seem to be a well-known team themselves, making it a difficult decision to move to a product designed by a team with not much (publically documented) history behind them 2) It's much simpler in maintenance and updating than ReadTheDocs was, which does not seem to be the case for Starlight. It's a much more involved configuration, involving juggling various third-party plugins to get basic behaviour working, and dealing with dependency hell when a plugin you want isn't compatible with the version you have... not a problem we encounter at all with Docu. 3) Performance isn't a concern for us. It's documentation. It's not like the page loading 0.003 seconds faster is going to make or break somebody's project. The longest loading time I had on docs.neoforged.net was 218 milliseconds - practically instant, for the purpose of having a huge block of text to spend 15 minutes reading through and testing things out. It's not a performance critical page.
Moving to Starlight at this stage (especially less than a day after releasing 1.20.2) would just be a huge waste of time, distracting us from more important things. Moving to it in the future, after all of this is sorted out, would just be spending time moving to a new framework with no real benefit to us - just creating more work in the future for no actual tangible benefit to the team or to the community.
Effectively; no. We have no reason to do this, and it has far more drawbacks than benefits, to everybody involved.
Imzxhir
Description: I want the team to consider moving the current docs to use Starlight rather than Docusaurus 2.
As much as both documentation builders are great, in my opinon, I think starlight provides a more organised and faster approach to documentation with alot of features packed in. Since Starlight is built on top of Astro, you can use Astro's features inside Starlight to have more functionality with the docs.
I know I have mentioned 'alot of features' and you may be wondering what features does it have that makes is better than Docusaurus. Well, I can name a few but not all for example: Astro / Starlight is more faster and lightweight compared to Docusaurus. This means that it will take less time to build and load the pages up. The docs are very customisable and flexible, this means that the docs can be customised with plugins or add extra language support if needed. Extra language support means that markdown can be extended to support extra features outside of the markdown scheme. Finally, the looks and feel of Starlight, in my opinion, are so much better. I know that the last point is personal preference, but I truely believe that Starlight looks and performs much better than Docusaurus.
Now to the downsides of Astro / Starlight, luckily there is only one which is versioning support. Versioning support can really help organise your docs into seperate versions like the NeoForge docs have now (1.20.x and 1.19.x). In Starlight, there is no way to setup versioning for your docs however, this feature is being discussed and worked on here. I am not sure if NeoForged needs versioning desperately since NeoForge only has 1.20.x support, I know it will probably be needed for 1.21 for when that releases. That won't release for a couple of months so, the feature should be out by then.
Overall, I am sorry if this issue feels like I am in love with Starlight. This issue is mainly to try and convince the team to consider and maybe switch to using Astro / Starlight. Also, I am happy to help out the migration to Starlight if this issue gets accepted.