Add Bundler Installation Instructions #6828

mkasberg · 2018-03-05T04:56:07Z

This commit addresses issue #6800. Specifically, this commit adds a
section for installing Jekyll using Bundler (as an alternative to the
gem command or RVM).

In addition, clean up the surrounding instructions a bit, and add some
helpful hints. One hint for Ubuntu users to get started quickly, and one
hint for people who run into permissions problems with gem install jekyll.

This commit addresses issue jekyll#6800. Specifically, this commit adds a section for installing Jekyll using Bundler (as an alternative to the gem command or RVM). In addition, clean up the surrounding instructions a bit, and add some helpful hints. One hint for Ubuntu users to get started quickly, and one hint for people who run into permissions problems with `gem install jekyll`.

ashmaroli · 2018-03-05T05:44:56Z

docs/_docs/installation.md

+bundle install --path vendor/bundle  # Set install path to ./vendor/bundle
+bundle add jekyll                    # Add & install Jekyll gem
+```
+


I'm not a fan of this method though..
A new user would get confused by having to run bundle exec jekyll new . and be greeted by an error message.,. while elsewhere in the docs, we simply instruct users to initialize a jekyll project with
jekyll new [jekyll-project-path]

We could distinct new with defaults from blank (working on a PR to have a working default directory structure. with blank)

ashmaroli · 2018-03-05T05:46:40Z

docs/_docs/installation.md

+Then, add Jekyll to your project's dependencies:
+
+```sh
+cd my-jekyll-project


you can't cd into a path that doesn't exist before-hand..

pathawks · 2018-03-05T06:12:19Z

docs/_docs/installation.md

+
+First, install Bundler (as a system-wide gem):
+```sh
+sudo gem install bundler


If the goal is to avoid permissions issues, using sudo is a non-starter.

what is the recommended method then?

gem install --user-install bundler

Agreed. I've always installed Bundler along with Ruby via apt on Ubuntu, but if you're on LTS it's a really old version of Bundler... But you're right, we shouldn't recommend that.

pathawks · 2018-03-05T06:14:43Z

docs/_docs/installation.md

@@ -37,11 +46,34 @@ Before you start, make sure your system has the following:
  </p>
 </div>

+## Install & Use Jekyll with Bundler


I don’t know if we want this ./vendor/bundle method to be presented first, as if it is the default/recommended method :/

pathawks · 2018-03-05T06:17:34Z

docs/_docs/installation.md

+  <p>
+    The above command performs a system-wide install of jekyll (on most
+    systems). If you get a permissions error, you can either run the command as root
+    (<code>sudo gem install jekyll</code>) or use


This always leads to conflicts with multiple versions of Jekyll being installed. There have been countless bug reports from users who installed Jekyll using sudo without understanding what that meant. Let’s recommend installing to ~/ instead of using sudo

Good point. No sudo.

pathawks · 2018-03-05T06:18:59Z

docs/_docs/installation.md

+    The above command performs a system-wide install of jekyll (on most
+    systems). If you get a permissions error, you can either run the command as root
+    (<code>sudo gem install jekyll</code>) or use
+    <a href="https://rvm.io/gemsets/basics">RVM</a> to manage your Gems.


Isn’t RVM for managing Ruby versions? I have always used RVM in addition to Bundler. Can we provide any more detail here?

is there a simpler method than the one listed here?

sudo apt-get install libgdbm-dev libncurses5-dev automake libtool bison libffi-dev gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 curl -sSL https://get.rvm.io | bash -s stable source ~/.rvm/scripts/rvm rvm install 2.5.0 rvm use 2.5.0 --default ruby -v

The only simpler method I can think of is if RVM is in your system's package manager repositories, I'm afraid.

pathawks · 2018-03-05T06:22:46Z

docs/_docs/installation.md

@@ -28,6 +29,14 @@ Before you start, make sure your system has the following:
  </p>
 </div>

+<div class="note info">


Do we really need three notes in a row?
Is there a better way to present this?

Agreed. Let's do a section per system.

DirtyF · 2018-03-05T09:20:26Z

Thanks @mkasberg, we need to do better on install instructions for different systems.

This feels too custom/advanced for a default install compared to the instructions for installing jekyll on Linux on CloudCannon.

I don't mind adding a dedicated Install on GNU/Linux section as long as there's a compromise from linux users on what should be the simplest default working method. What I see is that experienced command line users have each one a preferred method and we can't list them all. We just need a good default method.

This does not prevent to also add advanced methods and custom options like the --path you show here.

Resources:

how to install rbenv under Ubuntu/linux.

ghost

Our installation section is now so big, we definitely need a table of contents or something of the like. Also I'm not sure whether putting the bundler method first is the right choice here, while it is probably the right-est method, it's not the easiest one and not the one we should recommend.

ghost · 2018-03-05T10:37:30Z

docs/_docs/installation.md

+
+To use Jekyll with [Bundler](https://bundler.io/), add it as a
+dependency of your project. It can be installed in a sub-directory of the
+project. This avoids permissions issues, and also allows you to use different


permissions -> permission

ghost · 2018-03-05T10:40:34Z

docs/_docs/installation.md

+    The above command performs a system-wide install of jekyll (on most
+    systems). If you get a permissions error, you can either run the command as root
+    (<code>sudo gem install jekyll</code>) or use
+    <a href="https://rvm.io/gemsets/basics">RVM</a> to manage your Gems.


The only simpler method I can think of is if RVM is in your system's package manager repositories, I'm afraid.

mkasberg · 2018-03-06T01:56:53Z

Thanks for all the comments everyone, it's all good feedback.

I think perhaps this pull request is changing too much too quickly. @oe brings up a good point that while Bundler may be preferable for some users, perhaps it's not a good default if you're going for the simplest method. Also, I don't do jekyll new too often, so I wasn't thinking about that... I'll probably close this pull request (unmerged), but I wouldn't mind following up with a simpler pull request if there's some kind of consensus.

I guess the original thing that I wanted to fix is to make sure a new user knows what to do if they run into permissions problems at the gem install jekyll step. Particularly if they haven't used Ruby before and just want to run Jekyll as easily as possible. I know there are lots of ways to go about it, but is there any kind of consensus on what might be best for new users?

pathawks · 2018-03-06T02:21:54Z

I guess the original thing that I wanted to fix is to make sure a new user knows what to do if they run into permissions problems at the gem install jekyll step. Particularly if they haven't used Ruby before and just want to run Jekyll as easily as possible.

Yes. 💯

This has been a very difficult problem for us to solve. On the one hand, we do not distribute or support Ruby or Bundler and aren't really setup to support users that are still trying to get those things installed. On the other hand, this is the biggest hurdle for new users getting started with Jekyll, and I am sure we would have happier users (and quite possibly more developers) if installing Jekyll were not by far the most difficult step toward using (or contributing to) Jekyll.

What makes it especially tricky is that, as on display in this thread, it seems there are as many different ways to install Jekyll as there are users using Jekyll. This means there isn't necessarily anything as simple as "Copy these three lines and paste them into a shell."

You have done a lot of good work here and it would be a shame to just close the PR. I wonder if this could be spun into a tutorial for installing Jekyll on Ubuntu or something similar? Maybe for users that want to use a Docker container or install Jekyll system wide, make sure you have these dependencies and sudo install everything.

Thoughts @DirtyF?

crispgm · 2018-03-06T05:47:04Z

AFAIK, it's over lengthy for most users.

Shall we make a tl;dr as recommended installation method for OS with much population at the top?

DirtyF · 2018-03-06T15:22:22Z

We need to rethink the whole install page, so that's it's easier to follow for each OS:

I was thinking of something like:

We would need help on the GNU/Linux part. Anyone willing to contribute?

mkasberg · 2018-03-06T15:36:14Z

I could spin this PR off into a tutorial, "Using Jekyll as a Bundler Dependency," that's probably a better place for it. It can be done without the sudo gem install bundler step... I just need to figure out the best/simplest way.

I'm also willing to help with writing installation instructions for GNU/Linux, I think the idea of separate sections probably makes sense.

Based on discussion in PR jekyll#6828, move the instructions for setting up a project with Bundler to a tutorial. This is a better place for it since the installation instructions are targeted primarily at new users, and it can be confusing to list several different installation methods - particularly more complex ones.

pathawks

This is fantastic! I really like having this in the Tutorials section!

pathawks · 2018-03-07T05:17:18Z

I really like this document conceptually, but I'm a bit tired at the moment so somebody from @jekyll/documentation should also review 😴:+1:

ashmaroli · 2018-03-07T15:55:39Z

docs/_tutorials/using-jekyll-with-bundler.md

+because Jekyll gets confused if the Gemfile already exists.
+
+```sh
+bundle exec jekyll new --force --skip-bundle .


you missed the 'dot' . here.. bundle exec jekyll new .

@ashmaroli the dot is included here, at the end of the line

gosh.. I did not see that..
guess my brain registered it as a 'full-stop'.. 😛

ghost

This is really good!

DirtyF · 2018-03-16T23:27:18Z

@jekyllbot: merge +docs

ashmaroli reviewed Mar 5, 2018

View reviewed changes

pathawks requested changes Mar 5, 2018

View reviewed changes

DirtyF added the documentation label Mar 5, 2018

DirtyF requested a review from a team March 5, 2018 08:56

ghost reviewed Mar 5, 2018

View reviewed changes

DirtyF assigned adamhollett and unassigned adamhollett Mar 6, 2018

DirtyF self-assigned this Mar 6, 2018

mkasberg changed the title ~~Improve Installation Instructions~~ Add Bundler Installation Instructions Mar 7, 2018

pathawks approved these changes Mar 7, 2018

View reviewed changes

ashmaroli reviewed Mar 7, 2018

View reviewed changes

ghost approved these changes Mar 16, 2018

View reviewed changes

jekyllbot merged commit a275faa into jekyll:master Mar 16, 2018

jekyllbot added the documentation label Mar 16, 2018

jekyllbot added a commit that referenced this pull request Mar 16, 2018

Update history to reflect merge of #6828 [ci skip]

f6a4356

mkasberg mentioned this pull request Mar 20, 2018

Add ruby environment instructions to Install guide #6800

Closed

2 tasks

jekyll locked and limited conversation to collaborators Jul 12, 2019

jekyllbot added the frozen-due-to-age label Jul 12, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Bundler Installation Instructions #6828

Add Bundler Installation Instructions #6828

mkasberg commented Mar 5, 2018

ashmaroli Mar 5, 2018 •

edited

Loading

DirtyF Mar 5, 2018

ashmaroli Mar 5, 2018

pathawks Mar 5, 2018

DirtyF Mar 5, 2018

pathawks Mar 5, 2018

mkasberg Mar 6, 2018

pathawks Mar 5, 2018

pathawks Mar 5, 2018

mkasberg Mar 6, 2018

pathawks Mar 5, 2018

DirtyF Mar 5, 2018

ghost Mar 5, 2018

pathawks Mar 5, 2018

DirtyF Mar 5, 2018

DirtyF commented Mar 5, 2018

ghost left a comment

ghost Mar 5, 2018

ghost Mar 5, 2018

mkasberg commented Mar 6, 2018

pathawks commented Mar 6, 2018

crispgm commented Mar 6, 2018

DirtyF commented Mar 6, 2018

mkasberg commented Mar 6, 2018

pathawks left a comment

pathawks commented Mar 7, 2018

ashmaroli Mar 7, 2018

ghost Mar 7, 2018

ashmaroli Mar 7, 2018

ghost left a comment

DirtyF commented Mar 16, 2018

Add Bundler Installation Instructions #6828

Add Bundler Installation Instructions #6828

Conversation

mkasberg commented Mar 5, 2018

ashmaroli Mar 5, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DirtyF commented Mar 5, 2018

ghost left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mkasberg commented Mar 6, 2018

pathawks commented Mar 6, 2018

crispgm commented Mar 6, 2018

DirtyF commented Mar 6, 2018

mkasberg commented Mar 6, 2018

pathawks left a comment

Choose a reason for hiding this comment

pathawks commented Mar 7, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ghost left a comment

Choose a reason for hiding this comment

DirtyF commented Mar 16, 2018

ashmaroli Mar 5, 2018 •

edited

Loading