HPCE/gitea-pages
0
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Activity

added more robust instructions for installing jekyll on windows and mac

Browse Source
This commit is contained in:
tomjohnson1492
2016-03-24 12:17:03 -07:00
parent 283dfa3b73
commit fb11fbbee9
10 changed files with 630 additions and 385 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
mydoc/mydoc_about_ruby_gems_bundler.md Normal file
View File

@ -0,0 +1,114 @@
---
title: About Ruby, Gems, Bundler, and other Prerequisites
tags: [getting_started, troubleshooting]
keywords:
summary: "Ruby is a programming language you must have on your computer in order to build Jekyll locally. Ruby has various gems (or plugins) that provide various functionality. Each Jekyll project usually requires certain gems."
sidebar: mydoc_sidebar
permalink: /mydoc_about_ruby_gems_etc/
---
## About Ruby
Jekyll runs on Ruby, a programming language. You have to have Ruby on your computer in order to run Ruby-based programs like Jekyll. Ruby is installed on the Mac by default, but you must add it to Windows.
## About Ruby Gems
Ruby has a number of plugins referred to as "gems." Just because you have Ruby doesn't mean you have all the necessary Ruby gems that your program needs to run. Gems provide additional functionality for Ruby programs. There are literally *millions* of [Rubygems](https://rubygems.org/) available for you to use.
Some gems depend on other gems for functionality. For example, the Jekyll gem might depend on 20 other gems that must also be installed.
Each gem has a version associated with it, and not all gem versions are compatible with each other.
## Rubygem package managers
[Bundler](http://bundler.io/) is a gem package manager for Ruby, which means it goes out and gets all the gems you need for your Ruby programs. If you tell Bundler you need the Jekyll gem, it will retrieve all the dependencies on the Jekyll gem as well -- automatically.
Not only does Bundler retrieve the right gem dependencies, but it's smart enough to retrieve the right versions of each gem. For example, if you get the [github-pages](https://rubygems.org/gems/github-pages) gem, it will retrieve all of these other gems:
```
github-pages-health-check = 1.1.0
jekyll = 3.0.3
jekyll-coffeescript = 1.0.1
jekyll-feed = 0.4.0
jekyll-gist = 1.4.0
jekyll-github-metadata = 1.9.0
jekyll-mentions = 1.1.2
jekyll-paginate = 1.1.0
jekyll-redirect-from = 0.10.0
jekyll-sass-converter = 1.3.0
jekyll-seo-tag = 1.3.2
jekyll-sitemap = 0.10.0
jekyll-textile-converter = 0.1.0
jemoji = 0.6.2
kramdown = 1.10.0
liquid = 3.0.6
mercenary ~> 0.3
rdiscount = 2.1.8
redcarpet = 3.3.3
RedCloth = 4.2.9
rouge = 1.10.1
terminal-table ~> 1.
```
Note that Bundler goes out and retrieves not only the gem, but the right version of the gem.
You'll see here that the github-pages gem requires version 3.0.3 of the jekyll gem.
However, the latest version of the jekyll gem is 3.1.2. This means that github-pages is compatible with only an older version of the jekyll gem.
Trying to keep track of which gems and versions are appropriate for your project can be a nightmare. This is the problem Bundler solves. They [explain](http://bundler.io/):
> Bundler provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed.
>
> Bundler is an exit from dependency hell, and ensures that the gems you need are present in development, staging, and production. Starting work on a project is as simple as bundle install.
## Gemfiles
Bundler looks in a project's "Gemfile" (no file extension) to see which gems are required by the project. The Gemfile lists the source and then any gems, like this:
```
source "https://rubygems.org"
gem 'github-pages'
gem 'jekyll'
```
The source indicates the site where Bundler will retrieve the gems: https://rubygems.org.
The gems it retrieves are listed separately on each line.
Here no versions are specified. Sometimes gemfiles will specify the versions like this:
```
gem 'kramdown', '1.0'
```
This means Bundler should get version 1.0 of the kramdown gem.
To specify a subset of versions, the Gemfile looks like this:
```
gem 'jekyll', '~> 2.3'
```
The `~>` sign means greater than or equal to the last digit before the last period in the number.
Here it will get any gem equal to 2.3 but less than 3.0.
If it adds another digit, the scope is affected:
```
gem `jekyll`, `~>2.3.1'
```
This means to get any gem equal to 2.3.1 but less than 2.4.
If it looks like this:
```
gem 'jekyll', '~> 3.0', '>= 3.0.3'
```
This will get any Jekyll gem between versions 3.0 and up to 3.0.3.
See this [Stack Overflow post](http://stackoverflow.com/questions/5170547/what-does-tilde-greater-than-mean-in-ruby-gem-dependencies) for more details.

115
mydoc/mydoc_install_dependencies.md
View File

@ -1,115 +0,0 @@
---
title: Adding all project dependencies
tags: [getting-started, troubleshooting]
keywords:
summary: "You want to be sure that you have all the required gems and other utilities on your computer to make the project run. Jekyll runs on Ruby, and there are various plugins for Ruby that enable different functionality. These Ruby plugins are referred to as gems, and you install the gems you need for your projects."
sidebar: mydoc_sidebar
permalink: /mydoc_install_dependencies/
---
To manage the various gems and their versions needed for your project, you can use a package manager called Bundler. Many projects will have a gemfile in their project that lists the gems required for the project. You then run Bundler in order to automatically install the required gems and any dependencies for those gems on your machine.
## RubyGems
Make sure you have RubyGems. This should be installed by default on Mac.
Open Terminal and type `which gem`. You should get a response indicating the location of Rubygems, such as `/Users/MacBookPro/.rvm/rubies/ruby-2.2.1/bin/gem`.
If you need to install Rubygems, see [Download RubyGems](https://rubygems.org/pages/download).
## Install Bundler
[Bundler](http://bundler.io/) is a package manager for RubyGems.
You install Bundler by using the gem command with RubyGems:
```
gem install bundler
```
If you're prompted to which to superuser mode (`sudo`) to get the correct permissions to install Bundler in that directory, avoid doing this. All other applications that need to use Bundler will likely not have the needed permissions to run.
If you get a permissions error when trying to install Bundler, use Homebrew to install a Ruby package manager called rbenv.
Install Homebrew:
```
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
```
Use brew to install rbenv:
```
brew install rbenv
```
Initialize rbenv:
```
rbenv init
```
Log out of terminal, and then then log back in.
Install Bundler:
```
gem install bundler
```
Open the gemfile:
```
open gemfile
```
You should see some gems listed. If you don't have a gemfile, your project may not need any gems, or those gems may not be managed at the project level but rather directly installed manually. You can create a gemfile by typing `bundle init`.
Your gemfile might look like this:
```
# A sample Gemfile
source "https://rubygems.org"
# gem "rails"
gem 'github-pages'
gem 'pygments.rb'
gem 'redcarpet'
```
Use Bundler to install the needed gems:
```
bundle install
```
Finally, you can run the following to make sure the installed gems get associated or initialized with your project:
```
bundle exec jekyll serve
```
## Ruby permissions errors
While trying to install a missing gem, you get an error message that says,
>ERROR: While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /Library/Ruby/Gems/2.0.0 directory.
This most likely happens with El Capitan on the Mac.
As long as you have brew installed (see the previous section), run the following:
```
brew update
brew install ruby
```
Close your terminal, and then restart a fresh session.
Now run the gem you're trying to install, such as the following:
```
gem install kramdown
```

122
mydoc/mydoc_install_jekyll_on_mac.md Normal file
View File

@ -0,0 +1,122 @@
---
title: Install Jekyll on Mac
tags: [getting_started, troubleshooting]
keywords:
summary: "Installation of Jekyll on Mac is usually less problematic than on Windows. However, you may run into permissions issues with Ruby that you must overcome. You should also use Bundler to be sure that you have all the required gems and other utilities on your computer to make the project run. "
sidebar: mydoc_sidebar
permalink: /mydoc_install_jekyll_on_mac/
---
## Ruby and RubyGems
Ruby and [RubyGems](https://rubygems.org/pages/download) are usually installed by default on Macs. Open your Terminal and type 'which ruby' and `which gem` to confirm that you have Ruby and Rubygems. You should get a response indicating the location of Rubygems, such as `/Users/MacBookPro/.rvm/rubies/ruby-2.2.1/bin/gem`.
However, you will likely run into permissions errors when executing from the operating system's version of Ruby. A sample error looks like this:
```
>ERROR: While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /Library/Ruby/Gems/2.0.0 directory.
```
Instead of changing the write permissions on your OS's version of Ruby, you can install another instance of Ruby (one that is writable) to get around this.
## Install Homebrew
Homebrew is a package manager for the Mac, and you can use it to install alternative Ruby libraries. To install Homebrew, run this command:
```
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
```
## Install Ruby through Homebrew
If you already had Homebrew installed on your computer, first update it:
```
brew update
```
Install Ruby through Homebrew:
```
brew install ruby
```
Log out of terminal, and then then log back in.
When you type `which ruby` and `which gem`, you should get responses like this:
```
/usr/local/bin/ruby
```
And this:
```
/usr/local/bin/gem
```
Now Ruby and Rubygems are installed under your username, so these directories are writeable.
Note that if you don't see these paths, try restarting your computer or try installing rbenv, which is a Ruby version management tool.
You can install rbenv through Homebrew using this command:
```
brew install rbenv
```
Then initialize rbenv:
```
rbenv init
```
If you still have issues, you need to resolve them before installing Bundler.
## Install Bundler
At this point you should have a writeable version of Ruby on your machine. Now you need to get all the gems (or Ruby plugins) that you need for your Jekyll project. [Bundler](http://bundler.io/) is a package manager for RubyGems.
You install Bundler by using the gem command with RubyGems:
```
gem install bundler
```
If you're prompted to switch to superuser mode (`sudo`) to get the correct permissions to install Bundler in that directory, avoid doing this. All other applications that need to use Bundler will likely not have the needed permissions to run.
## Customize the Gemfile
Bundler goes out and retreives all the gems that are specified in your project's Gemfile. If you have a gem that depends on other gems to work, Bundler will go out and retrieve all of the dependencies as well. (To learn more about Bundler, see {{site.data.urls.mydoc_about_ruby_gems_bundler.link}}.
Open the Gemfile (in any text editor) in the Jekyll doc theme project:
```
open Gemfile
```
The theme's gemfile looks as follows:
```
# A sample Gemfile
source "https://rubygems.org"
# gem "rails"
gem 'github-pages'
gem 'jekyll'
```
If you're publishing on Github Pages, leave the `github-pages` gem there. But if not, remove `github-pages` -- Github sometimes has dependencies that conflict with the latest versions of the Jekyll gem and Kramdown, which can be frustrating.
Use Bundler to install all the needed Ruby gems:
```
bundle install
```
Now run Jekyll serve to build the theme:
```
jekyll serve
```

44
mydoc/mydoc_install_jekyll_on_windows.md
View File

@ -34,6 +34,7 @@ sidebar: mydoc_sidebar
{% endcomment %}
{{site.data.alerts.tip}} For a better terminal emulator on Windows, download <a href="https://sourceforge.net/projects/console/">Console</a>. This terminal allows you to create tabs and gives you more functionality. {{site.data.alerts.end}}
## Install Ruby
@ -44,29 +45,42 @@ sidebar: mydoc_sidebar
## Install Ruby Development Kit
1. Go to [RubyInstaller for Windows](http://rubyinstaller.org/downloads/).
2. Under the **Development Kit** section near the bottom, download one of the **For use with Ruby 2.0 and above...** options.
3. Extract Ruby onto your **C** drive in a folder called something like **RubyDevKit**.
3. Browse to the **RubyDevKit** location on your C drive using your Command Line Prompt.
3. Type `ruby dk.rb init`
3. Type `ruby dk.rb install`
2. Under the **Development Kit** section near the bottom, download one of the **For use with Ruby 2.0 and above...** options (either the 32-bit or 64-bit version).
3. Move your downloaded file onto your **C** drive in a folder called something like **RubyDevKit**.
4. Extract the compressed folder's contents into the folder.
5. Browse to the **RubyDevKit** location on your C drive using your Command Line Prompt.
{{site.data.alerts.tip}} To see the contents of your current directory, type <code>dir</code>. To drill into a directory, type <code>cd foldername</code>, where "foldername" is the name of the folder you want to enter. To move up a directory, type <code>cd ../</code>. To move into your user's directory, type <code>/users</code>.{{site.data.alerts.end}}
6. Type `ruby dk.rb init`
7. Type `ruby dk.rb install`
If you get stuck, see the [official instructions for installing Ruby Dev Kit](https://github.com/oneclick/rubyinstaller/wiki/Development-Kit).
## Install Bundler
1. In the downloaded theme, *delete* the existing **Gemfile** and **Gemfile.lock** files.
1. Type `gem install bundler`.
2. Browse to the documentation-jekyll-theme directory.
3. Type `bundle init`
4. Open the Gemfile in a text editor.
5. Paste in the following:
1. Using the command line, browse to the folder where you downloaded the Jekyll theme.
2. Delete the existing **Gemfile** and **Gemfile.lock** files:
```
del Gemfile
del Gemfile.lock
```
1. Install Bundler: `gem install bundler`
3. Initialize Bundler: `bundle init`
This will create a new Gemfile.
4. Open the Gemfile in a text editor. You may need to use your File Explorer and browse to the directory, and then open the Gemfile in a text editor such as Notepad.
5. Remove the existing contents and paste in the following:
```
# A sample Gemfile
source "https://rubygems.org"
gem 'wdm', '>= 0.1.0' if Gem.win_platform?
gem 'jekyll', '~> 3.1', '>= 3.1.2'
gem 'wdm'
gem 'jekyll'
```
6. Save and close the file.
@ -74,6 +88,6 @@ If you get stuck, see the [official instructions for installing Ruby Dev Kit](ht
## Serve the Jekyll site
1. Browse to the documentation-jekyll-theme directory.
1. Browse to the jekyll theme directory.
2. Type `jekyll serve`
3. Go to the preview address in the browser. (Make sure you include the `/` at the end.)