New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Install Jekyll on macOS #6881

Merged
merged 2 commits into from Apr 12, 2018

Conversation

Projects
None yet
6 participants
@DirtyF
Member

DirtyF commented Mar 28, 2018

This PR aims at providing detailed explanation to install Jekyll on macOS.

screenshot update after the review:

jekyll-install-macos

@DirtyF DirtyF requested a review from jekyll/documentation Mar 28, 2018

## Install on macOS {#macOS}
We only cover latest macOS High Sierra 10.13 here, who ships a new Ruby version, older systems will need to install Homebrew, see below.
We only cover latest macOS High Sierra 10.13 here, who comes with Ruby 2.3.3, older systems will need to [install a more recent Ruby version via Homebrew](#homebrew).
First, you need to [install Xcode from the AppStore](https://itunes.apple.com/fr/app/xcode/id497799835?mt=12). Then to install the command-line tools, open a terminal and run:

This comment has been minimized.

@coliff

coliff Mar 28, 2018

Member

Suggest to use URL:
https://itunes.apple.com/app/xcode/id497799835?mt=12
instead of country-specific

This comment has been minimized.

@chrisfinazzo

chrisfinazzo Mar 28, 2018

Contributor

Better idea - the Mac App Store is terrible, avoid it if you possibly can. I know this requires auth to get past the login, but if we're being honest, most people installing on macOS probably know about this already and can deal with this requirement.

To that end, I have found this document to be more useful regarding how to obtain Xcode.

## Install on macOS {#macOS}
We only cover latest macOS High Sierra 10.13 here, who ships a new Ruby version, older systems will need to install Homebrew, see below.
We only cover latest macOS High Sierra 10.13 here, who comes with Ruby 2.3.3, older systems will need to [install a more recent Ruby version via Homebrew](#homebrew).
First, you need to [install Xcode from the AppStore](https://itunes.apple.com/fr/app/xcode/id497799835?mt=12). Then to install the command-line tools, open a terminal and run:

This comment has been minimized.

@coliff

coliff Mar 28, 2018

Member

AppStore should be two words (App Store)

```
Great, let's install Jekyll, we'll also need bundler to help us handle plugins and themes:
Great, let's install Jekyll, we'll also need [bundler](http://bundler.io/) to help us handle [plugins](../plugins) and [themes](../themes):

This comment has been minimized.

@coliff
## Install on macOS {#macOS}
We only cover latest macOS High Sierra 10.13 here, who ships a new Ruby version, older systems will need to install Homebrew, see below.
We only cover latest macOS High Sierra 10.13 here, who comes with Ruby 2.3.3, older systems will need to [install a more recent Ruby version via Homebrew](#homebrew).

This comment has been minimized.

@coliff

coliff Mar 28, 2018

Member

Should this be:

We only cover latest macOS High Sierra 10.13 here, which comes with Ruby 2.3.3...
(which not who)

@chrisfinazzo

Looks good, save for a few things that I noted.

```
Great, let's install Jekyll, we'll also need bundler to help us handle plugins and themes:

This comment has been minimized.

@chrisfinazzo

chrisfinazzo Mar 28, 2018

Contributor

Feels like this should be two sentences.

"Great, let's install Jekyll. We'll also need Bundler to help us handle plugins and themes:"

From that point on, continue.

## Install on macOS {#macOS}
We only cover latest macOS High Sierra 10.13 here, who ships a new Ruby version, older systems will need to install Homebrew, see below.
We only cover latest macOS High Sierra 10.13 here, who comes with Ruby 2.3.3, older systems will need to [install a more recent Ruby version via Homebrew](#homebrew).
First, you need to [install Xcode from the AppStore](https://itunes.apple.com/fr/app/xcode/id497799835?mt=12). Then to install the command-line tools, open a terminal and run:

This comment has been minimized.

@chrisfinazzo

chrisfinazzo Mar 28, 2018

Contributor

Better idea - the Mac App Store is terrible, avoid it if you possibly can. I know this requires auth to get past the login, but if we're being honest, most people installing on macOS probably know about this already and can deal with this requirement.

To that end, I have found this document to be more useful regarding how to obtain Xcode.

@DirtyF

This comment has been minimized.

Member

DirtyF commented Mar 28, 2018

Thanks @coliff @chrisfinazzo adressed your feedback.

<code>Preferences &#8594; Downloads &#8594; Components</code>.
</p>
</div>
Great, let's install Jekyll. We also need [bundler](https://bundler.io/) to help us handle [plugins](../plugins) and [themes](../themes):

This comment has been minimized.

@oe

oe Apr 3, 2018

Member

bundler is capitalized iirc

bundle exec rake build
ls pkg/*.gem | head -n 1 | xargs gem install -l
# Install rbenv and ruby-build
brew install rbenv

This comment has been minimized.

@oe

oe Apr 3, 2018

Member

does the homebrew installation of rbenv include ruby-build?

This comment has been minimized.

@chrisfinazzo

chrisfinazzo Apr 3, 2018

Contributor

Just tried it...

brew info lists it as "recommended" for rbenv and will download the latest tarball during rbenv installation process.

On macOS 10.13.

This comment has been minimized.

@oe

oe Apr 3, 2018

Member

ok cool!

```sh
jekyll --version
gem list jekyll
```
You can also use [RubyGems](https://rubygems.org/gems/jekyll) to find the current versioning of any gem. But you can also use the `gem` command line tool:
You can use RubyGems to find [the current versioning of Jekyll](https://rubygems.org/gems/jekyll). Another way to check if you have the latest version is to run the command `gem outdated`. This will provide a list of all the gems on your system that need to be updated. If you aren't running the latest version, run this command:

This comment has been minimized.

@oe

oe Apr 3, 2018

Member

s/versioning/version

@mattr-

This is looking great! I have a few tweaks and a larger suggestion that we can discuss as it would alter the structure of the document significantly. Thanks for tackling this!

<a href="../windows/#installation">Windows-specific docs page</a>.
</p>
</div>
We only cover latest macOS High Sierra 10.13 here, which comes with Ruby 2.3.3, older systems will need to [install a more recent Ruby version via Homebrew](#homebrew).

This comment has been minimized.

@mattr-

mattr- Apr 3, 2018

Member

Let's remove latest from this sentence since we're explicitly referencing the version number and code name and once a new release comes out, it won't be the latest anymore.

## Install with RubyGems
First, you need to [install Xcode from the App Store](https://itunes.apple.com/app/xcode/id497799835?mt=12) or [from Apple Developer website](https://developer.apple.com/xcode/). Then to install the command-line tools, open a terminal and run:

This comment has been minimized.

@mattr-

mattr- Apr 3, 2018

Member

Technically, XCode isn't required. On macOS 10.13, you can just run xcode-select --install in a terminal window to get the command line tools installed.

use the `-v` switch to indicate the version you'd like to install:
From there you can either use a [theme](../themes/) or create your own layouts.
### Install via Homebrew {#homebrew}

This comment has been minimized.

@mattr-

mattr- Apr 3, 2018

Member

If macOS 10.13 has the appropriate version requirements for Ruby out of the box, I'm not sure I see a reason to add a section on installing via Homebrew.

If we want to keep this section. I think it would be better if we rearrange the documentation to be something along the lines of:

                 |-> Set up Ruby included with the OS  +
Install on macOS +                                     | -> Install Jekyll -> Generate your first website
                 |-> Install a newer Ruby via Homebrew +

I was quite confused when I got to this section for two reasons:

  1. We don't install Jekyll via Homebrew, so just what the heck is going on here 😃
  2. We already set up Ruby, we don't need to do it again.

What do y'all think?

ruby -v
2.3.3
gem update --system

This comment has been minimized.

@mattr-

mattr- Apr 3, 2018

Member

Do we require a newer version of Rubygems outside of what's installed by default? If not, we shouldn't recommend that people upgrade Rubygems on their system.

Apply review feedback
Co-Authored-By: Matt Rogers <codemattr@gmail.com>
Co-Authored-By: olivia <olivia@fastmail.com>
@DirtyF

This comment has been minimized.

Member

DirtyF commented Apr 3, 2018

@mattr- @oe thanks for the feedback, updated the screenshot accordingly.

Most users can stop reading after the first part (working with macOS system ruby version), other sections are optional, so I kept the the jekyll new part at the beginning.

Working with latest version of Ruby is mostly useful for developers or for people who like living on the edge and benefit from a some kind faster Ruby.

@oe

oe approved these changes Apr 12, 2018

LGTM 😍

Concerns addressed

@DirtyF

This comment has been minimized.

Member

DirtyF commented Apr 12, 2018

@jekyllbot: merge +docs

@jekyllbot jekyllbot merged commit 7dc4d4f into master Apr 12, 2018

3 checks passed

WIP ready for review
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details

@jekyllbot jekyllbot deleted the docs/install branch Apr 12, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment