Deploy main docs site from GitHub Pages

[mattxwang]

In #1211, we deployed the new just-the-docs.com URL. Right now, it deploys off of the main branch built with Netlify.

We could move it to instead use GitHub Pages. Here's a quick pros/cons (without thinking about it too deeply):

1. Using GH Pages is closer to "dogfooding" our own theme, in that more users are likely to use GH Pages with JtD; we could catch any specific issues with it there
2. Using GH Pages requires us to add a CNAME file to the repo, which could pollute the directory + be very confusing for people who fork our repository
   • in particular, people cannot fork our repository and then use pages to showcase their changes
   • ideally, users of our theme should not be forking our repo. But, they do anyways!
3. Netlify gathers a few more statistics about how many hits our site has, etc.

What are our thoughts? I don't have a strong opinion either way (other than being slightly annoyed by the CNAME file.

[max06]

Hey Matt, thanks for picking up on this one!

If we move to gh-pages, I'd do it the same way our users do it: Fork the repo and add the domain there. That way our main repo will stay clean and we can deploy independently to gh-pages.
(Might add more later, no coffee yet)

[ShaneCurcuru]

From the peanut gallery: I bet a lot of users would appreciate having a "it just works out of the box without doing anything" experience using GH-pages, so doing this for JTD somehow (even if on a branch, whatever, to keep repo otherwise clean) would be great.

I mention this as a happy new user for my site (built from your nifty template) that was working great... until this week when something in my GH Pages deploy broke, and I'm wondering if I broke it (don't think so), or if some version of a gem is actually broken inside GH's environment.

[mattxwang]

Thanks everyone for chiming in! @ShaneCurcuru, I think your suggestion makes sense: "working out of the box" should be one feature of our theme. Out of curiosity, do you have any other suggestions for our template that could make it easier to use?

Deploying from a fork is a tad bit challenging (since we'd have to keep the fork in sync with main), but I'll think a bit if there's a simple/elegant way to do this. If all else fails, I'll just use the CNAME file and add it to our main repo.

[ShaneCurcuru]

TL;DR: I bet you have a bunch of users who just want it to work with the safest and lowest-maintenance GH Pages deployment; hence optimize install docs to make that "just work no matter what".

---

I don't have the experience to give advice for your core team/repo But from a user's perspective, I'd love to see "Get Started on GitHub Pages" install doc that includes two things:

• A super-simple "use this template to create a repo" that you click, add content (and perhaps CNAME, etc. for domain setup), and it magically just works with the latest GitHub versions and Action scripts (which I realize are in beta).
• A set of beginner-focused descriptions of how that install template sets up the users new repo to work: how JTD has certain defaults; how one would typically setup doc structure; how the default GH Pages integration works, including pointers to how to ensure a local environment works for building as well. The one key configuration to explain is how to build a whole doc site (like mine), or build a /docs subdir site for a code project.

I've had (separate) issues getting my local environment working, which is why I finally just nuked my Gemfile.lock to fix the GH Pages build on my site (because I don't know what gems I added locally that GH Pages doesn't support). Someone suggested using the official GH Pages build & deploy actions, which I just installed to try...

Which now fails too!

github-pages 228 | Error: The just-the-docs theme could not be found.
https://github.com/Punderthings/fossfoundation/actions/runs/5058854157/jobs/9079550741

And I thought this would be simple (i.e. I could just wing it without understanding the details of how using your template would interact with the beta Actions for build/deploy pages).

Sorry for the rant, but trying to provide perspective from a long-term open source person who's just a bit rusty coming back to coding. Thanks for asking, happy to provide any more focused feedback to make myself useful.

[max06]

Not trying to be mean: Have a look at https://github.com/just-the-docs/just-the-docs-template :)

And your build fails because it's remote_theme: just-the-docs/just-the-docs instead of theme - but yeah, that's not very well documented in our own readme.

[ShaneCurcuru]

Oh, no worries - I'm definitely complaining about stuff outside JTD's scope here! (Meaning I understand if y'all just ignore me here.)

But I just put back the Gemfile/_config.yml to the JTD template config, followed instructions to re-setup the Pages deployment (both ways, just in case, actions vs. classic - and back, in case GH does some internal configuration), and it still doesn't work. So yes, I did check theme vs remote_theme, but it seems either GH Pages has had some recent borking update for your gem, or I've somehow wedged some non-obvious setting on my repository at this point.

github-pages 228 | Error: The just-the-docs theme could not be found.
https://github.com/Punderthings/fossfoundation/actions/runs/5061915993/jobs/9086771282

[max06]

We'll figure it out! :)

[mattxwang]

Just getting to all the pending pings now. @ShaneCurcuru, that error message makes it seem like you're using the github-pages gem to build & deploy instead of using the Gemfile, etc. Is it possible that the deploy source for your repository is configured to use the github-pages gem instead of your Action?

In particular, check Settings > Pages > "Build and Deployment" - this should be set to GitHub Actions. This is not the default (GitHub product decision), but certainly something I could improve with the template docs.