docs: add starlight

[trueberryless]

Description

Migrate the docs/ folder to a Starlight site.

Here are the details:

• Leave the order of pages exactly as on the current site (but improve the folder structure a little bit, e.g., "Start here", "Guides", ...)
• I found a browser.md file and also included it in the "Guides" section.
• I created an index page. Inspired by whiskers project.
• I added some plugins that make sense of these docs:
  • Catppuccin theme 😏
  • GitHub Alerts: I noticed that some files use the GitHub Alert syntax, which is different from the Starlight Aside syntax, there is a plugin for exactly this use case ✅
  • Links Validation: Validate links (WIP, not all links adapted yet)
  • Image Zoom: I saw some images, and I think all those images should be zoomable (I excluded some of the README, e.g. Logo, the cool line, ...) ✅
  • One possible plugin which is not very useful in this repo but could be useful in other catppuccin Starlight docs (e.g. https://whiskers.catppuccin.com/getting-started/installation/) is: Starlight Changelogs, which can show the release notes in the docs.

Note

I saw two pages on the current website, where no Markdown files exists: "Convert Images to WebP" and "Hide sensitive information from preview screenshot". I figured that they got deleted but the website didn't get updated, so I left them out in the migration as well. ✅

Related PRs

#1856

[uncenter]

I saw two pages on the current website, where no Markdown files exists: "Convert Images to WebP" and "Hide sensitive information from preview screenshot". I figured that they got deleted but the website didn't get updated, so I left them out in the migration as well. ✅

Good catch. We used to require preview images for userstyles but no longer do so that's a leftover from that.

[uncenter]

We'll need to add a deployment workflow too, maybe the same as https://github.com/catppuccin/whiskers/pull/94/files#diff-9cf2000c53760d837a449f874e53f792819108d3a4bf346336d0f7d082deae2c (cc @sgoudham).

[trueberryless]

We'll need to add a deployment workflow too, maybe the same as catppuccin/whiskers#94 (files) (cc @sgoudham).

That's exactly what I was currently doing 😆

[sgoudham]

In the public/ directory, you'll need a CNAME file with userstyles.catppuccin.com in it. This is to allow GitHub pages to deploy properly, ran into an issue without this file on Whiskers.

Nice job so far though, it's coming along nicely.

[uncenter]

Made some more changes. I think I'm pretty happy with this now, and it unblocks the lib stuff! I can't request a review from you @trueberryless since you are the author but what do you think now?

[trueberryless]

Starlight-wise the PR looks good to me 👍
I'm not the expert of the domain, so I can't 100% verify the changes to the scripts, but generally I quite like that we removed all the logic for updating the README.

Let's hope that the GitHub action runs smoothly, 90% sure it should work 🤞

[sgoudham]

Think everything is good for the initial version.

As I've mentioned on discord, it's unfortunate that there's a bit of a hop back and forth between the site and GitHub but hoping we can alleviate that going forward after this is merged.

Is there a future where we can serve the userstyles from our domain instead of the GitHub raw links? Or is that a breaking change for each userstyle? Suppose it'd be nice to generate a page for each userstyle (similar to the per userstyle READMEs) and just have the userstyle content under our domain)

I'll leave that one for you all to figure out. Thanks @trueberryless for getting us started on this!

[uncenter]

Is there a future where we can serve the userstyles from our domain instead of the GitHub raw links? Or is that a breaking change for each userstyle?

Definitely possible, would be a similarly semi-breaking change to renaming from .css to .less as we did earlier this year and we would want to do "stub" redirect files for updating. Some conveniences of doing that approach is that we can version the userstyles in deployment instead of committing the (calendar) versioning changes to source, and we can do other "processing" as needed.

[sgoudham]

@uncenter and I are aware that we're making the process of installing userstyles a little bit more annoying with the usage instructions on the website, but the actual userstyles and install badges on GitHub.

We're looking at improving this in the future by moving the userstyles under our domain (userstyles.catppuccin.com) and also streamlining the process of installing userstyles. Starlight gives us a lot more freedom, such as being able to bake in the "userstyles customiser" which would allow you to install multiple userstyles at once under different accents.

Most likely will raise a separate issue for the concerns above, but we're one step closer with this PR - thanks again to @trueberryless for kicking off the work and @uncenter as always for the continued engagement and reviews!