just-the-docs/just-the-docs-template

This goes against GitHub Pages documentation

stefano-xy opened this issue · 2 comments

stefano-xy commented

According to GitHub Pages documentation, the correct way to use GitHub Pages is to include in the gemfile something like this:

# If you have any plugins, put them here!
group :jekyll_plugins do
  gem "github-pages", "~> 227"
end

github-pages then pulls everything you need. You can then add just-the-docs in the remote_theme and that's it, and let GitHub Pages run its predefined actions for you.

Am I wrong?

mattxwang commented

Hi @ragazzojp, sorry for getting back to you late - didn't realize that I don't have notifs on for this repo.

If using the pages gem fits your use-case, you can still continue doing so! However, GitHub Pages is now Actions-based by default (August 10th, so pretty recently), which gives two key benefits:

  • introspection - now, if the build fails, it's easier to see why
  • flexibility - we can use Jekyll 4, for example

In turn, it's much easier for us to support users of the theme if they use GitHub Actions (rather than the pages gem) - especially since the pages gem will likely not get upgraded to Jekyll 4 anytime soon (see: github/pages-gem#651).

I agree that it could be more confusing for people who are not familiar with Actions. Perhaps we need to improve our documentation there, though copying this template should have everything work out of the box.

Let me know if that makes sense! If you have other suggestions, let me know!

ragazzojp commented

Understood, thanks, I'll have a look at the update documentation.