-
-
Notifications
You must be signed in to change notification settings - Fork 8.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
RFC: avoid recommending github pages #2953
Comments
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?! |
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.
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 V2 is using Netlify. 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. |
Is there some reason why documentation requires SSH-key setup, instead of just using a provided |
@ark120202 didn't know it was actually possible. Maybe we just need to rewrite the Github CI part of the doc? 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) |
That's mentioned here too :) |
So it seems @amimas agrees with me, feel less alone :D |
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:
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. |
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 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 (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. |
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 assume you talk about 300 Netlify build limits vs 2000 build minutes for GH? In both cases there's a limit.
yes, not a huge fan of those
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. |
I think we can do a cost-benefit analysis here like we did for Crowdin vs. git
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 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:
But:
|
Github doesn't have any limits for Public repos btw. |
💥 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... :
The text was updated successfully, but these errors were encountered: