Update creating-a-github-pages-site-with-jekyll.md #2178

monfresh · 2020-12-16T22:21:45Z

Why:

The previous instructions for installing the github-pages gem via the Gemfile were 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.

Examples of people who got stuck:

This is my attempt to make things clearer by being more specific step by step. By pointing to the Rubygems page for github-pages, it removes any ambiguity that the previous dependency page introduced since it lists a bunch of different gems, and it's not absolutely clear which version you're supposed to look for, as evidenced by the person who pinned the github-pages gem to a version number for the jekyll gem.

Here's the issue I created for this PR: #2177

What's being changed:

Instead of an image containing the confusing suggestion to run bundle update github-pages, I rephrased the instructions in the image so that they can be followed step by step, and added a step to run bundle update, since that is what is needed to install the github-pages gem, and the previous instructions did not mention that.

I also updated Step 7 because it was both confusing and incorrect. Running jekyll 3.9.0 new . does not work. 3.9.0 is being interpreted as a subcommand, and it is not a valid subcommand. 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. Furthermore, if we did create a Gemfile by running bundle init for example, it would cause an error when running bundle exec jekyll new . because Jekyll expects the directory to be empty. Jekyll creates its own Gemfile so it doesn't make sense to start a new Jekyll site with Bundler.

To avoid all of this confusion, I simplified 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 results in dependency issues.

Check off the following:

All of the tests are passing.
I have reviewed my changes in staging. (look for the deploy-to-heroku link in your pull request, then click View deployment)
For content changes, I have reviewed the localization checklist
For content changes, I have reviewed the Content style guide for GitHub Docs.

The previous instructions for installing the `github-pages` gem via the Gemfile were confusing. If you search for `could not find gem github-pages` in your favorite search engine, you'll find many people didn't uncomment the line and/or tried to run `bundle update github-pages` instead of `bundle install`. This is my attempt to make things clearer by being more specific step by step.

welcome · 2020-12-16T22:21:46Z

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

I was initially focused on steps 8-10, but I thought I should try all of the commands to make sure everything works. As far as I can tell, you cannot pass in a version number to the `jekyll new` command, at least not the way it was documented here. 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 thought it was easier to skip that section. Because people installing Jekyll today will have version 4.2.0, and because github-pages only supports 3.9.0, one must run `bundle update` instead of `bundle install` to resolve all dependencies.

janiceilene · 2020-12-17T22:28:29Z

@monfresh Thanks so much for opening a PR! I'll get this triaged for review ⚡

github-actions · 2020-12-25T17:26:09Z

This PR is stale because it has been open 7 days with no activity and will be automatically closed in 3 days. To keep this PR open, update the PR by adding a comment or pushing a commit.

monfresh · 2020-12-25T18:26:37Z

Commenting to prevent this PR from being closed on Monday.

github-actions · 2021-01-02T17:34:58Z

This PR is stale because it has been open 7 days with no activity and will be automatically closed in 3 days. To keep this PR open, update the PR by adding a comment or pushing a commit.

BenWhetton

It is important to target guides at a specific audience to avoid bloating the guide with too many low level details which should already be known by the users. I believe there are a couple of instances of this in this pull request (see inline comments)

This pull request introduces some fixed version numbers which will quickly become out-of-date, no longer matching what the users sees. I understand why this has been proposed but I don't think it is a good solution. It will likely cause different kinds of confusion.
I've proposed some changes inline which I think are clearer than the original text without using explicit versions.

content/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll.md

github-actions · 2021-01-16T18:05:46Z

This PR is stale because it has been open 7 days with no activity and will be automatically closed in 3 days. To keep this PR open, update the PR by adding a comment or pushing a commit.

…es-site-with-jekyll.md Co-authored-by: Ben Whetton <ben.whetton@gmail.com>

monfresh · 2021-01-19T21:18:03Z

Thanks for the suggestions, @BenWhetton. I've accepted them.

hubwriter

@monfresh - This is a nice improvement to that page. Thanks for taking the time to do this.

I've made a couple of little suggestions for changes. The main one just changes the order of the 2 edits to the Gemfile.

If you agree with these changes, please just apply them and we can get this merged and live on the site.

Thanks again. 👍

content/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll.md

…es-site-with-jekyll.md Co-authored-by: hubwriter <hubwriter@github.com>

monfresh · 2021-02-15T21:33:35Z

@hubwriter Thanks for the suggestions. I accepted them.

hubwriter

Great. This is looking good - let's get it merged. 👍

hubwriter · 2021-02-17T15:02:01Z

@monfresh & @BenWhetton - many thanks for contributing to the GitHub documentation. Much appreciated. 🙇‍♂️

* Update creating-a-github-pages-site-with-jekyll.md The previous instructions for installing the `github-pages` gem via the Gemfile were confusing. If you search for `could not find gem github-pages` in your favorite search engine, you'll find many people didn't uncomment the line and/or tried to run `bundle update github-pages` instead of `bundle install`. This is my attempt to make things clearer by being more specific step by step. * Update step 7 as well I was initially focused on steps 8-10, but I thought I should try all of the commands to make sure everything works. As far as I can tell, you cannot pass in a version number to the `jekyll new` command, at least not the way it was documented here. 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 thought it was easier to skip that section. Because people installing Jekyll today will have version 4.2.0, and because github-pages only supports 3.9.0, one must run `bundle update` instead of `bundle install` to resolve all dependencies. * Update content/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll.md Co-authored-by: Ben Whetton <ben.whetton@gmail.com> * Update content/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll.md Co-authored-by: Ben Whetton <ben.whetton@gmail.com> * Update content/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll.md Co-authored-by: hubwriter <hubwriter@github.com> * Update content/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll.md Co-authored-by: hubwriter <hubwriter@github.com> * Update creating-a-github-pages-site-with-jekyll.md Co-authored-by: Moncef Belyamani <moncef@example.com> Co-authored-by: Ben Whetton <ben.whetton@gmail.com> Co-authored-by: hubwriter <hubwriter@github.com>

janiceilene added content This issue or pull request belongs to the Docs Content team core labels Dec 17, 2020

github-actions bot added the stale There is no recent activity on this issue or pull request label Dec 25, 2020

github-actions bot removed the stale There is no recent activity on this issue or pull request label Dec 26, 2020

github-actions bot added the stale There is no recent activity on this issue or pull request label Jan 2, 2021

BenWhetton mentioned this pull request Jan 6, 2021

Instructions for installing the github-pages gem are confusing #2177

Closed

BenWhetton suggested changes Jan 6, 2021

View reviewed changes

content/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll.md Outdated Show resolved Hide resolved

content/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll.md Outdated Show resolved Hide resolved

janiceilene removed the stale There is no recent activity on this issue or pull request label Jan 8, 2021

github-actions bot added the stale There is no recent activity on this issue or pull request label Jan 16, 2021

felicitymay added never-stale Do not close as stale and removed stale There is no recent activity on this issue or pull request labels Jan 19, 2021

hubwriter self-assigned this Jan 19, 2021

monfresh and others added 2 commits January 19, 2021 16:16

Update content/github/working-with-github-pages/creating-a-github-pag…

31c3ca2

…es-site-with-jekyll.md Co-authored-by: Ben Whetton <ben.whetton@gmail.com>

Update content/github/working-with-github-pages/creating-a-github-pag…

604d91c

…es-site-with-jekyll.md Co-authored-by: Ben Whetton <ben.whetton@gmail.com>

janiceilene added the waiting for review Issue/PR is waiting for a writer's review label Feb 5, 2021

hubwriter reviewed Feb 10, 2021

View reviewed changes

content/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll.md Outdated Show resolved Hide resolved

content/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll.md Outdated Show resolved Hide resolved

hubwriter and others added 3 commits February 10, 2021 14:59

Merge branch 'main' into patch-1

c97b65d

Update content/github/working-with-github-pages/creating-a-github-pag…

c736e80

…es-site-with-jekyll.md Co-authored-by: hubwriter <hubwriter@github.com>

Update content/github/working-with-github-pages/creating-a-github-pag…

7a0b91d

…es-site-with-jekyll.md Co-authored-by: hubwriter <hubwriter@github.com>

Merge branch 'main' into patch-1

329caa3

Update creating-a-github-pages-site-with-jekyll.md

cb6bdb8

hubwriter approved these changes Feb 17, 2021

View reviewed changes

Merge branch 'main' into patch-1

8a29179

hubwriter enabled auto-merge (squash) February 17, 2021 14:59

hubwriter merged commit fc0f5a6 into github:main Feb 17, 2021

snyk-bot mentioned this pull request Sep 2, 2021

[Snyk] Upgrade nock from 13.0.4 to 13.1.1 hixio-mh/docs-#49

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Update creating-a-github-pages-site-with-jekyll.md #2178

Update creating-a-github-pages-site-with-jekyll.md #2178

Uh oh!

monfresh commented Dec 16, 2020 •

edited

Loading

Uh oh!

welcome bot commented Dec 16, 2020

Uh oh!

janiceilene commented Dec 17, 2020

Uh oh!

github-actions bot commented Dec 25, 2020

Uh oh!

monfresh commented Dec 25, 2020

Uh oh!

github-actions bot commented Jan 2, 2021

Uh oh!

BenWhetton left a comment

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Jan 16, 2021

Uh oh!

monfresh commented Jan 19, 2021

Uh oh!

hubwriter left a comment

Uh oh!

Uh oh!

Uh oh!

monfresh commented Feb 15, 2021

Uh oh!

hubwriter left a comment

Uh oh!

hubwriter commented Feb 17, 2021

Uh oh!

Uh oh!

Update creating-a-github-pages-site-with-jekyll.md #2178

Update creating-a-github-pages-site-with-jekyll.md #2178

Uh oh!

Conversation

monfresh commented Dec 16, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why:

What's being changed:

Check off the following:

Uh oh!

welcome bot commented Dec 16, 2020

Uh oh!

janiceilene commented Dec 17, 2020

Uh oh!

github-actions bot commented Dec 25, 2020

Uh oh!

monfresh commented Dec 25, 2020

Uh oh!

github-actions bot commented Jan 2, 2021

Uh oh!

BenWhetton left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Jan 16, 2021

Uh oh!

monfresh commented Jan 19, 2021

Uh oh!

hubwriter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

monfresh commented Feb 15, 2021

Uh oh!

hubwriter left a comment

Choose a reason for hiding this comment

Uh oh!

hubwriter commented Feb 17, 2021

Uh oh!

Uh oh!

monfresh commented Dec 16, 2020 •

edited

Loading