RFC: avoid recommending github pages

[slorber]

💥 Proposal

Github pages is a free hosting solution that works for Docusaurus.

It's the first thing that users see here: https://v2.docusaurus.io/docs/next/deployment

But it's not the most easy to setup, requires commiting to a gh-branch of the repo, give write access...

There are issues like #2846 where people struggle to set it up, while it's not directly related to Docusaurus

---

I think we should stop recommending Github pages as the primary deployment option, and actually document that it's the most complicated option to setup.

Alternatives like Netlify, Vercel, Surge, Render etc... :

• are also free (have a good enough free plan, not worst than Github CI)
• are much simpler to setup (no need to commit to the github repo, give write access...)
• do not mess-up with the "doc last updated by X on X" (see [v2] Author name is always same for all of the pages #2952)
• can add deploy previews for docs PR before merging

[shinebayar-g]

Most of the users are open source project developers and uses Docusaurus for their documentation website. Majority of them hosted on Github and their docs are hosted on Github Pages which integrates nicely. Even docusaurus.io itself is hosted on Github Pages?!

[slorber]

@shinebayar-g

Majority of them hosted on Github and their docs are hosted on Github Pages which integrates nicely.

What do you mean by "integrates nicely"? Have you tried alternatives and find they are not as good integration as Github pages? I have and really think Github Pages is not the most convenient tool to host a Github-based website, since a few years already.

Even docusaurus.io itself is hosted on Github Pages?!

Actually, we have 2 websites on this monorepo, v1 and v2. I don't even think it's possible to publish more than 1 website per repo on Github pages.

V1 seems to use Github Pages: https://github.com/facebook/docusaurus/tree/gh-pages
This requires v1 to provide publish-gh-pages.js, a 200 LOC cli to make it work correctly.

V2 is using Netlify.
It is very easy to setup and actually add a deploy preview to each PR.

Setting Github pages might be quite easy if you run locally, but in practice, people that want to automate the publish process (ie commit to master = deploy) struggle a bit, because their CI need write permissions to their repo.

[ark120202]

people that want to automate the publish process (ie commit to master = deploy) struggle a bit, because their CI need write permissions to their repo.

Is there some reason why documentation requires SSH-key setup, instead of just using a provided GITHUB_TOKEN secret? With that actions workflow is pretty simple: example 1, example 2

[slorber]

@ark120202 didn't know it was actually possible.

Maybe we just need to rewrite the Github CI part of the doc?
https://v2.docusaurus.io/docs/deployment/#triggering-deployment-with-github-actions

Any PR would be appreciated, as I'm not familiar with Github CI, and users seems to follow our existing doc and some struggle a bit as the doc is unnecessarily complex.

After taking a look, it seems the Github workflow and Travis workflow could share almost the same code.

@Jason-2020 seems to be using a workflow similar to the documented Travis workflow while he's using Github CI: #2798 (comment)

[shinebayar-g]

people that want to automate the publish process (ie commit to master = deploy) struggle a bit, because their CI need write permissions to their repo.

Is there some reason why documentation requires SSH-key setup, instead of just using a provided GITHUB_TOKEN secret? With that actions workflow is pretty simple: example 1, example 2

That's mentioned here too :)

[slorber]

So it seems @amimas agrees with me, feel less alone :D

#2736 (comment)

[amimas]

In my opinion, this tool needs to focus in it's core functionality, which is to generate a static documentation site that is easy to maintain.

Publishing and deployment doesn't really fit in that core function although it can easily mistaken for thinking otherwise.

The generated site can be deployed in so many ways. For example:

• github pages
• gitlab pages
• docker image
• aws cloud
• azure cloud
• traditional web server with nginx or apache or tomcat

I'm sure I missed other options. Add other services like netlify that @slorber mentioned and the list gets much bigger.

Basically this is all about how to deploy/publish a static site and it's applicable for any tools in this category. Adding deployment functionality means they also need to be maintained going forward. And it's not possible to satisfy every type of deployments nor is it the focus of this tool.

[Josh-Cena]

Revisiting this after a year: GitHub pages still remains as one of the most popular choices, if not gaining more popularity. For casual users (especially small open-source libraries) it's hard to say if GitHub pages is harder to set up than Netlify. The docusaurus deploy command has masked away all the details of the deploy workflow, and there are also out-of-the-box GitHub actions that takes the directory on master, runs build, and copies the output to gh-pages.

I think Docusaurus should be less opinionated in various ways, both in our code base and in our documentation. In the community, I'm constantly asked of how to do things that are actually pretty terrible—but instead of saying "it's terrible, you'd better do X", my responsibility is to just tell them that "do A, B, and C", and leave them to eventually figure out that there's another way to do things. It's the same for our documentation. GitHub pages is terrible in many ways, e.g. server-side redirects, but:

(a) Users know what they are doing when they go to the GitHub pages tutorial. We should not imagine our users asking "how should I deploy my site?" but rather "I want to host it on GitHub pages. How do I do it?" I think that's also the general positioning we are taking in our docs—provide solutions, not suggestions.

(b) At the end of the day Netlify is far less free than GH Pages—my own deployments are on the verge of crossing the limit every month.

(c) We already provide first-class support for GH Pages in our code base by allowing config options that only apply to GH Pages deployment, and also a docusaurus deploy command that's targeting nothing but GH Pages.

(d) GH Pages is non-proprietary (afaik) while the others are. While we document Crowdin for backward-compatibility and Algolia for partnership, I think recommending Netlify / Vercel makes our doc less neutral.

[slorber]

(a) Users know what they are doing when they go to the GitHub pages tutorial. We should not imagine our users asking "how should I deploy my site?" but rather "I want to host it on GitHub pages. How do I do it?" I think that's also the general positioning we are taking in our docs—provide solutions, not suggestions.

I don't really agree here. This overestimate the number of devs that have no idea that services like Netlify/Vercel exists and why they are way better than GitHub pages. When they discover such services they generally are very impressed by deploy previews etc and really willing to test this.

(b) At the end of the day Netlify is far less free than GH Pages—my own deployments are on the verge of crossing the limit every month.

I assume you talk about 300 Netlify build limits vs 2000 build minutes for GH? In both cases there's a limit.
Netlify can also be deployed with a CLI without any build minute.

(c) We already provide first-class support for GH Pages in our code base by allowing config options that only apply to GH Pages deployment, and also a docusaurus deploy command that's targeting nothing but GH Pages.

yes, not a huge fan of those

(d) GH Pages is non-proprietary (afaik) while the others are. While we document Crowdin for backward-compatibility and Algolia for partnership, I think recommending Netlify / Vercel makes our doc less neutral.

Being non-neutral also gives the opportunity to get some sponsors, and Netlify/Vercel are usually happy do to so.

Already suggested that, but afaik Facebook/Meta is not really willing to do that atm, or at least it requires some internal process that I'm not really aware of.

[Josh-Cena]

I don't really agree here. This overestimate the number of devs that have no idea that services like Netlify/Vercel exists and why they are way better than GitHub pages. When they discover such services they generally are very impressed by deploy previews etc and really willing to test this.

I think we can do a cost-benefit analysis here like we did for Crowdin vs. git

2000 build minutes for GH

2000 is quite a lot—6x compared to Netlify. My site takes 20 min for each build (yes, I still haven't figured out how caching works) and that means I can build 15 times for Netlify and 100 times for GitHub. Also I think we need to separate CI from hosting. In practice I also use CircleCI for two legacy websites, which offers 6000 min/mo.

All that said, deploy time has really been a bottleneck for me, despite Netlify being much more featured.

I also remember back in the days GH Pages was really hard to set up, but now it's quite intuitive. Already explained in our own docs: https://docusaurus.io/docs/next/deployment#github-pages-overview It's just my-org/my-project => https://my-org.github.io/my-project/ and my-org/my-org.github.io => https://my-org.github.io/. There's no magic. Even better: you can host your source on the master branch and deploy to gh-pages branch even if you are using my-org/my-org.github.io. I already do that myself: https://github.com/Josh-Cena/Josh-Cena.github.io

I'm not really pro-GitHub pages. I do use GH Pages for all my personal projects, but I recommend others to try Netlify. On our docs we can do two things:

• Do a cost-benefit analysis;
• Put Netlify before GitHub pages.

But:

1. We didn't recommend GH Pages. We implemented the tooling to help GH Pages deployment to make it stay competitive against Netlify.
2. We shouldn't explicitly discourage using GH Pages or encourage using Netlify / Vercel, unless... we do get sponsorship

[shinebayar-g]

2000 build minutes for GH?

Github doesn't have any limits for Public repos btw.