Instructions for installing the github-pages gem are confusing

[monfresh]

What article on docs.github.com is affected?

Creating a GitHub Pages site with Jekyll

What part(s) of the article would you like to see updated?

Steps 8 - 10 are confusing. If you search for could not find gem github-pages in your favorite search engine, you'll find that the instructions caused people to do one or more of the following things:

• they didn't uncomment the # gem "github-pages" line
• they tried to run bundle update github-pages
• they replaced VERSION with the version of jekyll listed on the Dependency versions page instead of the github-pages version.

Step 7 is also both confusing and incorrect. Running jekyll 3.9.0 new . does not work. The jekyll new command does not accept a version number, at least not like it is documented in GitHub docs. Also, the Bundler section is more confusing than helpful because for bundle exec to work, a Gemfile must exist in the directory, but the instructions don’t mention that. Instead of adding more steps, I think it's best to simplify step 7 to just jekyll new ., which will create the Jekyll site using whatever version of Jekyll is currently installed (most likely 4.2.0).

In step 8, they are told to comment out the jekyll gem, so it doesn't matter if they used a more recent version of jekyll to create the site initially. What matters is that after they save the Gemfile, they need to run bundle update because github-pages only supports jekyll 3.9.0 currently. Running bundle install will result in dependency issues.

See the linked PR below that I submitted to fix this.

Additional information

Examples of people who got stuck because of the documentation:

• https://talk.jekyllrb.com/t/why-cant-i-install-the-github-pages-plug-in-when-i-set-up-jekyll/3743
• https://talk.jekyllrb.com/t/how-to-install-github-pages-with-jekyll/3510

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[BenWhetton]

I also encountered this issue just last week. It would have been nice if #2178 had been merged already! It's likely costing users a lot of time to have these kinds of errors in such a key guide.
I have a sligtly different solution to propose than #2178 which uses the github-pages gem to ensure the correct version of jekyll is used to set up the jekyll scaffolding. This works even without a system-wide jekyll installation and will ensure that there are not compatibility issues if jekyll 4+ changes the behavior of jekyll new in some way

The problem as I would describe it:

When following the GitHub Pages Jekyll guide, the command in step 7: bundle exec jekyll VERSION new . does not work for multiple reasons:

• Bundler has not been initialised
• Jekyll has not been installed by bunder
• The default bundler install path may require root permissions to install gems.
• The command is incorrect. After resolving the other problems, bundle exec jekyll _VERSION_ new . works. However _VERSION_ is undocumented so it would be best to avoid it if possible.

Proposed solution

I worked through setting up a new Jekyll GitHub Pages site last week. By cross referencing various stackoverflow answers (which I forgot to keep links to) and the Jekyll bundler guide, I came up with the following procedure which I believe solves all of the above problems. This should replace the bundler version of step 7 of the GitHub Pages Jekyll guide:

• Initialise bundler: bundle init
• Configure bundler install path (optional but necessary for to avoid permissions issues in many situations): bundle config set --local path 'vendor/bundle (as shown in the Jekyll bundler guide)
• Add the github-pages gem bundle add --group=":jekyll-plugins" github-pages.
  This will install the correct version of Jekyll currently supported by github-pages without the user having to manually check what the correct version is and install that specific version. This step is not in the Jekyll bundler guide because it does not cover Github Pages-specific steps. Otherwise, I would simply recommend linking to that guide rather than duplicating it. The resulting Gemfile will look like this:

  # frozen_string_literal: true
  
  source "https://rubygems.org"
  
  git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
  
  # gem "rails"
  
  gem "github-pages", "~> 209", :group => :":jekyll-plugins"
  

• Create a Jekyll scaffold

  bundle exec jekyll new --force --skip-bundle .
  bundle install

  (as shown in the Jekyll bundler guide)

Now the user can continue with the rest of the GitHub Pages Jekyll guide from step 8 (with some of the fixes proposed in #2178).
I would recommend adding a link to the Jekyll bundler guide somewhere in the GitHub Pages Jekyll guide as well.

I also have a question about step 9. It would be useful to add a comment to explain what this step is for. Is the goal to prevent bundle update from performing an undesired major update of the github-pages gem?

It is a little confusing having the bundler and non-bundler instructions in the same guide. Perhaps it could be restructured in a way that makes it more clear.

The solution in #2178 is certainly an improvement. I think it would be good to add a link to the Jekyll bundler guide and to add the optional "Configure bundler install path" step. I personally like the pure bundler approach from the solution proposed above since it avoids having to install jekyll outside of bundler and it ensures that the procedure is not affected by any non-backwards compatible changes to the behavior of jekyll new.

[janiceilene]

Thanks for the thorough explanation @BenWhetton! I've triaged it to let the team take a look 👀

[ReimarBauer]

I'd ran in that common "versions" problem too. The hint with the undocumented version string _3.9.0_ helped also a bit, not sure about if it is forgotten or deprecated. I agree to @BenWhetton suggestions.
The documentation should show the bundle approach. bundle exec jekyll serve was for me the only option without versioning conflicts of 18n to try our pages locally.

[hubwriter]

The article that this issue relates to (https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site) has been updated since the original post above. However, more work is needed on this article - as per the comments by @BenWhetton, @ReimarBauer, and @taiya (below).

As some of the comments refer to the article prior to the changes in PR #2178 (merged 17 Feb 2021) it's useful to see what the article looked like before the update.

Here's the relevant section of the page before the changes in #2178 were merged:

As of writing, these steps now look like this:

[hubwriter]

Generally in the documentation we choose one way of doing things and document that - rather than overcomplicate things by documenting alternative ways of doing the same thing. Given that the prerequisites section of this help article tells the reader to install Bundler, I think @BenWhetton's suggestion for documenting the Bundler method is a good one. We should replace the current steps 7-10 with steps for using Bundler. We should document the steps directly in this help article rather than requiring the reader to go to https://jekyllrb.com/tutorials/using-jekyll-with-bundler/ and then come back here.

Thanks @BenWhetton for providing this information.