Install Docs that Work on MacOS 10.14 (#7561)

Merge pull request 7561
This commit is contained in:
Liam Rosenfeld 2019-04-12 14:01:31 -04:00 committed by jekyllbot
parent ef588d6bc8
commit 6c872cf6a1
1 changed files with 66 additions and 36 deletions

View File

@ -3,19 +3,19 @@ title: Jekyll on macOS
permalink: /docs/installation/macos/ permalink: /docs/installation/macos/
--- ---
## Install Command Line Tools
First, you need to install the command-line tools to be able to compile native extensions, open a terminal and run: First, you need to install the command-line tools to be able to compile native extensions, open a terminal and run:
```sh ```sh
xcode-select --install xcode-select --install
``` ```
## Set up Ruby ## Install Ruby
Jekyll requires Ruby > {{ site.min_ruby_version }}. Jekyll requires Ruby > {{ site.min_ruby_version }}.
As macOS Mojave 10.14 comes only with ruby 2.3.x, you'll have to install Ruby through Homebrew. As macOS Mojave 10.14 comes only with ruby 2.3.x, you'll have to install a newer version of Ruby.
### Install latest stable Ruby with Homebrew {#brew}
### With Homebrew {#brew}
To run the latest Ruby version you need to install it through [Homebrew](https://brew.sh). To run the latest Ruby version you need to install it through [Homebrew](https://brew.sh).
```sh ```sh
@ -33,43 +33,17 @@ export PATH=/usr/local/opt/ruby/bin:$PATH
Then relaunch your terminal and check your updated Ruby setup: Then relaunch your terminal and check your updated Ruby setup:
``` ```sh
which ruby which ruby
/usr/local/opt/ruby/bin/ruby # /usr/local/opt/ruby/bin/ruby
ruby -v ruby -v
ruby 2.6.2p47 (2019-03-13 revision 67232) [x86_64-darwin18] # ruby 2.6.2p47 (2019-03-13 revision 67232) [x86_64-darwin18]
``` ```
Yay, we are now running current stable Ruby! Yay, we are now running current stable Ruby!
We can install bundler and jekyll: ### With rbenv {#rbenv}
```sh
gem install bundler jekyll
```
That's it, you're ready to roll!
{: .note }
We strongly recommend that you install Ruby gems in your home directory to avoid file permissions problems and using `sudo`.
You can do this with the `--user-install` option, for instance by running:
```sh
gem install --user-install bundler jekyll
```
Or you can change the default gem path, by adding those lines to your shell config file, .e.g. `~/.bash_profile` or `~/.bashrc` if your shell is bash:
```
export GEM_HOME=$HOME/gems
export PATH=$HOME/gems/bin:$PATH
```
Relaunch your terminal and run `gem env` to check that default gem paths point to your home directory by default.
### Manage multiple Ruby environments with rbenv {#rbenv}
People often use [rbenv](https://github.com/rbenv/rbenv) to manage multiple People often use [rbenv](https://github.com/rbenv/rbenv) to manage multiple
Ruby versions. This is very useful when you need to be able to run a given Ruby version on a project. Ruby versions. This is very useful when you need to be able to run a given Ruby version on a project.
@ -95,11 +69,67 @@ Now you can install the Ruby version of our choice, let's go with current latest
rbenv install 2.6.2 rbenv install 2.6.2
rbenv global 2.6.2 rbenv global 2.6.2
ruby -v ruby -v
ruby 2.6.2p47 (2019-03-13 revision 67232) [x86_64-darwin18] # ruby 2.6.2p47 (2019-03-13 revision 67232) [x86_64-darwin18]
``` ```
That's it! Head over [rbenv command references](https://github.com/rbenv/rbenv#command-reference) to learn how to use different versions of Ruby in your projects. That's it! Head over [rbenv command references](https://github.com/rbenv/rbenv#command-reference) to learn how to use different versions of Ruby in your projects.
### Problems? ## Install Jekyll
Now all that is left is installing [Bundler](/docs/ruby-101/#bundler) and Jekyll.
### Local Install
```sh
gem install --user-install bundler jekyll
```
and then get your Ruby version using
```sh
ruby -v
# ruby 2.6.1p33 (2019-01-30 revision 66950) [x86_64-darwin18]
```
Then append your path file with the following, replacing the `X.X` with the first two digits of your Ruby version.
```
export PATH=$HOME/.gem/ruby/X.X.0/bin:$PATH
```
To check your that you gem paths point to your home directory run:
```sh
gem env
```
And check that `GEM PATHS:` points to a path in your home directory
{: .note }
Every time you update Ruby to a version with a different first two digits, you will need to update your path to match.
### Global Install
{: .note .warning}
We strongly recommend against installing Ruby gems globally to avoid file permissions problems and using `sudo`.
#### On Mojave (10.14)
Because of SIP Protections in Mojave, you must run:
```sh
sudo gem install bundler
sudo gem install -n /usr/local/bin/ jekyll
```
#### Before Mojave (<10.14)
You only have to run:
```sh
sudo gem install bundler jekyll
```
## Problems?
Check out the [troubleshooting](/docs/troubleshooting/) page or [ask for help on our forum](https://talk.jekyllrb.com). Check out the [troubleshooting](/docs/troubleshooting/) page or [ask for help on our forum](https://talk.jekyllrb.com).