Documentation platforms Netlify vs GitHub pages

[lwasser]

In this issue @JimMadge and @flpm discussed whether we should move away from Netlify (or not).

Previously, because we didn't have access to the Domain DNS, Netlify, and Crowdin, it made sense to rebuild the site using GitHub pages. However, we now have access to all of those things, which means we have more flexibility.

The question is moving forward: should we continue to use Netlify (but ensure that we have multiple people with sufficient access to it)? Or should we continue down the path of using GitHub Pages?

From my perspective (which might be wrong!), the one thing Netlify provides us is potential translation redirects based on a user's location. Although @JimMadge did find a redirect file recently as well!! So I might not understand how it works at all. I'd love everyone's feedback on this.

[flpm]

I have no strong opinion about Netlify. I am happy to move in any direction you think is best.

We can do some degree of redirection with Astro in the front end, but it might be handy to set server redirects. So maybe better to keep Netlify if we can.

The _redirects file has information to tell Netlify which URL to use for different locales (line 40 and after).

The way it works is that the browser adds an HTTP header called Accept-Languages to the requests to the server, which includes an ordered list of locales it would like to receive.

My Firefox, for example, sends this one:

Accept-Language: es-ES,en-US;q=0.7,en;q=0.3

It's a comma-separated list of locales and a q number (between 0 and 1) to indicate the order of preference. The default is 1, so the first entry often is the first choice and has no explicit number.

In this case, it asks for:

• Spanish from Spain
• English from the US
• Any English

Netlify sees this and uses the list of redirects to send me to the proper translation.

Curiously, I do not arrive at the Spanish translation with this header value because the redirects have no locale for es-ES, and I don't ask for generic Spanish (es). There is no en-US locale either, so Netlify gives the generic English (en) back.

Note: this is not a problem with Netlify or the redirect config, it's because my browser setup is unusual 😂 normally someone in Spain, for example, would have es;q=0.7 after es-ES.

[lwasser]

@flpm I tested this last night and switched my phone's browser to Firefox with the language set to Spanish. It didn't seem to register the language, but I also may be doing things wrong. I tried generic Spanish (ES?). i will play with this a bit more tonight but i'm trying to understand how we can test that this works!!

[flpm]

@lwasser I was looking at the docs that @JimMadge shared and based on a quick read it looks like it should have worked for me with es-ES.

I will investigate more, I have a an easy way to try arbitrary values for the header so I can test.

Am I correct to assume that it's currently setup in Netlify with those redirects? Maybe the config for redirects for Netlify changed and the _redirects file does not work anymore?

[lwasser]

We can guess that Netlify should handle those items. However, we currently don't have access to Netlify to test it out.

One idea to throw over the fence (but i want to see what @JimMadge thinks about this as someone who knows Netlify)... if we believe Netlify adds significant value to the site, we could create our own account and make multiple people maintainers there. Then we can potentially redirect the domain there, too. I'm sorry I can't be more helpful right now!!

[JimMadge]

Thanks @lwasser! 🎉

It's great to know that we have access to DNS, Netlify, Crowdin and the GitHub org. Hopefully that is everything to keep the project running.

I'm fairly familiar with using Netlify, from @the-turing-way. It isn't perfect, but it has quite a few handy features,

• managed DNS (optional)
• TLS certs
• Build and deployment logs
• Build previews for PRs
• Configurable headers and redirects

In terms of redirects specifically, you can write them in a _redirects file or in the Netlify configuration netlify.toml (docs).
It is very useful if you ever move or remove pages from your site, to prevent link rot.
For multiple languages, you can also redirect based on location of language preference.
I'm not 100% certain, but I couldn't find a way to do the same with GitHub pages.

My intuition would be, now that we have access to all the infrastructure, don't make changes right away. However, if we find problems we can always move in the future.

[lwasser]

I just did some sluthing

https://app.netlify.com/projects/allcontributors-org/deploys/6898fd610220450008d3fcd3

if you look at the deploy logs there are some errors related to the version of the crowdin CLI that we are using. I think that Netlify is totally broken now because it's deploying from master (rather than main). But I wonder if updating the Crowin dep will resolve some of the issues.

9:58:46 AM: $ npm run build-with-translations
9:58:46 AM: > [email protected] build-with-translations
9:58:46 AM: > npm run write-translations && npm run crowdin-upload && npm run crowdin-download && npm run build
9:58:47 AM: > [email protected] write-translations
9:58:47 AM: > cd website && ../node_modules/.bin/docusaurus-write-translations
9:58:48 AM: > [email protected] crowdin-upload
9:58:48 AM: > npm run crowdin -- --config crowdin.yaml upload sources --auto-update -b $(git rev-parse --abbrev-ref HEAD)
9:58:48 AM: > [email protected] crowdin
9:58:48 AM: > java -jar website/crowdin/crowdin-cli.jar --config crowdin.yaml upload sources --auto-update -b HEAD
9:58:49 AM: ERROR
9:58:49 AM: code: 2
9:58:49 AM: message: Version 1.0 of the Crowdin API has been deprecated and removed
9:58:50 AM: > [email protected] crowdin-download
9:58:50 AM: > npm run crowdin -- --config crowdin.yaml download -b $(git rev-parse --abbrev-ref HEAD)
9:58:50 AM: > [email protected] crowdin
9:58:50 AM: > java -jar website/crowdin/crowdin-cli.jar --config crowdin.yaml download -b HEAD
9:58:51 AM: ERROR
9:58:51 AM: code: 2
9:58:51 AM: message: Version 1.0 of the Crowdin API has been deprecated and removed
9:58:51 AM: > [email protected] build
9:58:51 AM: > cd website && ../node_modules/.bin/docusaurus-build && cp _redirects build/all-contributors
9:58:52 AM: generate.js triggered...
9:58:53 AM: Version 9 of Highlight.js has reached EOL and is no longer supported.
9:58:53 AM: Please upgrade or ask whatever dependency you are using to upgrade.
9:58:53 AM: https://github.com/highlightjs/highlight.js/issues/2877
9:58:53 AM: Warning: Invalid DOM property `class`. Did you mean `className`?

i will open a small PR but we won't be able to test without setting up a new netlify account.

[flpm]

Ah that makes sense, right now it's probably built only in English. Good catch!

I was able to solve this issue when I built locally with translations. The CrowdIn CLI right now is a Java app and is very old. Updating to the NPM crowdin package worked for me but I had to recreate the config file, because the format has changed.

[lwasser]

ok I have one question for @flpm @JimMadge here. I can get an open source plan for Netlify. I suspect that Jake has the bot in a team plan that they manage / own, and there is likely a fee for it. I can't add team members to my free Netlify account; I have to upgrade to paid.

But I did email Netlify, and they will give us a free open source plan, I think, if I add a Netlify badge to our website! We weren't approved but they told me that was why.

I'd like to avoid burdening Jake any more than necessary. They were kind enough to pay for the domain and set things up.
What if we:

1. Stick with Astro/starlight as a doc platform (I think we should do this)
2. Get GitHub Pages up and running (this is underway!) Yes, translations wouldn't be hosted as nicely as they will on Netlify, but we can fix that later and get things online sooner! 🚀
3. Add translations to the repo so they are synced and in version control (there is definitely a way to do that as I looked into it before for our package guide!)
4. Ask Jake to migrate the DNS to GitHub Pages and shut down his Netlify project for the bot. (If Jake can move the project to me, that is another option too, but also that requires a paid plan to add someone to my account.)
5. I can set up Circle CI to preview the docs too!! ✨

IF i get the open source Netlify plan for the website, we can then set up Netlify again in the future to take advantage of the translation features. And if we want to pay for the domain, we can ask Jake to update the DNS too.

I think right now we should do what is easiest for Jake while we have a bit of his time. So, my vote (after doing some research) is to move forward with GitHub Pages and get things working there for the time being as a course of action that we have full control over and will limit how much we have to ask of Jake.

In the meantime, we need to decide if we want a paid domain or not. (let's discuss this separately)
Please let me know if you support this plan as a way to move forward together.

[JimMadge]

Thanks for all this work and investigation @lwasser 🤩

That all sounds good to me. My only concern is spending a lot of effort moving to GH Page then to move back. But I think if we go one step at a time, we can always revaluate what our best hosting option looks like. And, having a live site somewhere while we are migrating to Astro is a very good idea.

If we have a period where you have to select your language rather than being redirected, that is a little annoying but more than worth it for getting the project up and running again 🚀.

[flpm]

I think this is a good plan 👍 Thanks for putting it together! There is a lot that has to be done no matter where the site is hosted.