docs (meta issue): migrate website/docs to Astro using the Starlight theme

[lwasser]

The astro / starlight theme has a really nice interface that should support all of the work that we need to do here rebuilding the docs.

I suggest that instead of migraing to Docusaurus 3.x we move to astro and then convert the manually created index.html page to a clean astro / starlight splash layout page.

@flpm has rebuilt the docs already quickly using this theme and you can see it here. It will be easy to update graphics and layout and such from here and I found the splash page layout that should support our landing page.

You can see what the POC code looks like here: https://github.com/flpm/astro-test/

Related issues and discussion:
#853
#843 (comment)

I do think this is a better way for us to go.

[flpm]

Based on my (very short) experience playing with both Docusaurus 3 and Astro, I like Astro better for this type of use case.

It was a little simpler to setup, builds very fast with Vite, and generates (mostly) static HTML (you still have the option to use a framework like React in certain parts if you need).

[lwasser]

That is awesome to hear. I read really great things about it. Let's move forward with this and I can help with styles, the home page, etc. And soon we will be able to host allcontributors.org from this repo too!! 🚀

[lwasser]

Ok - this issue can serve as our meta-issue to organize docs tasks. Let's work together to determine the tasks needed to move the documentation forward. Each item below can turn into a linked issue once we create it! @JimMadge @flpm, what am I missing / what should we add/remove edit in this list? ✨

Documentation style/branding

• docs: add "Swoosh" div to landing page and purple box below is (docs: style landing page #901 )
• docs: check all pages for broken links, missing images, missing alt tags (medium priority)
• docs: fix images throughout docs(images): fix links to all images throughout the site #912
• docs: rename repo to support github pages (docs: Rename this repo to all-contributors.github.io to support github pages #860 )

REMOVED: docs add top bar links to docs and GitHub (this will require customization, but I think it's doable? (low priority) - I suggest we skip this for now as we have a strong side bar with previous and next buttons and we boxes on the home page

Translations ( @flpm, thank you Felipe!!!)

• docs(translations): update CrowdIn file structure (in the CrowdIn website) to match the new Astro folder structure to preserve translations
• docs(translations): rewrite CrowdIn configuration file
• docs(translations): create initial download of current translations to check into the repo
• docs(translations): configure Astro to build translations (drop-down on the site is automatically added)
• docs(translations): set up redirection to the user language (this seems easy to by adding a meta redirect to the landing page)
• chore(ci, translations): set up a CI action to regularly download translations from Crowdin and make a PR
• docs(translations): review all locale hardcoded links in MD files to make sure they still work (e.g., CONTRIBUTING, CODE_OF_CONDUCT, etc)
• docs(translations): test user experience

Docs Infrastructure

Set up Circle CI for documentation previews on PR's UPDATE: we are going to move forward with Netlify.

• Setup / Test GitHub pages build for new astro site This is complete via docs: Rename this repo to all-contributors.github.io to support github pages #860 chore(ci for docs): Get docs online via github pages #914
• Setup Dependabot to update NPM installed deps (I know very little about NPM deps, so I'm guessing about this based on a comment Jim made in another pr!!

what else?

When we are happy with this list, I'll update the top comment, link to all open issues, and we can track the work here and via the documentation milestone board!

[flpm]

Here are a set of tasks for the translation part:

• update CrowdIn file structure (in the CrowdIn website) to match the new Astro folder structure to preserve translations
• rewrite CrowdIn configuration file
• initial download of current translations to check into the repo
• configure Astro to build translations (drop-down on the site is automatically added)
• set up redirection to the user language (this seems easy to by adding a meta redirect to the landing page)
• set up a CI action to regularly download translations and make a PR
• review all locale hardcoded links in MD files to make sure they still work (e.g., CONTRIBUTING, CODE_OF_CONDUCT, etc)
• test user experience

Let me know if this is too granular, several of these tasks might be done at the same time.

[lwasser]

hey @flpm thank you for this list!! I'll update my list above. I think if someone wants to tackle a few issues together, they can always open a pr that closes multiple issues!! But if a few need to be done together or would be done more efficiently together, let's group. If you tell me which ones to group, I'm happy to do so. If they can be standalone, I'll make separate issues!! I don't have a personal preference, I just want to make it easier for someone to see what we're working on, where we need help, and what they could potentially help with!! ✨

[flpm]

I actually started looking into a few of these already, maybe this breakdown makes sense:

1. Initial setup (I am already working on these and they go all together)

• update CrowdIn file structure (in the CrowdIn website) to match the new Astro folder structure to preserve translations
• rewrite CrowdIn configuration file
• initial download of current translations to check into the repo
• configure Astro to build translations (drop-down on the site is automatically added)
• set up redirection to the user language (this seems easy to by adding a meta redirect to the landing page)

2. Set up the CI (I can take this one too, or help someone doing it, since it will involve setting CrowdIn credentials)

• Set up a CI action to regularly download translations and make a PR

3. Review (these ones are easy for anyone to help with)

• review all locale hardcoded links in MD files to make sure they still work (e.g., CONTRIBUTING, CODE_OF_CONDUCT, etc)
• test user experience

[lwasser]

Ok cool . One more question - in the list below, are the checked-off items already merged into docs-upgrade?
I am happy to then open a meta translation issue and then a bunch of subissues based on your list!

Let's also add an issue around documentation for our translation infra. I am totally open to helping with any of this too, once I am done with the base documentation updates (it's getting there!).