Permalink
Browse files

tweaks to installation page and split off troubleshooting page

  • Loading branch information...
cobyism committed Jul 31, 2012
1 parent b2a670f commit e9bf521d5a84b29e7150bc300cafcfcfb02707d6
@@ -74,6 +74,9 @@ <h4>Miscellaneous</h4>
<li class="{% if page.title == "Reporting issues" %}current{% endif %}">
<a href="{{ site.url }}/docs/issues">Reporting issues</a>
</li>
+ <li class="{% if page.title == "Troubleshooting" %}current{% endif %}">
+ <a href="{{ site.url }}/docs/troubleshooting">Troubleshooting</a>
+ </li>
<li class="{% if page.title == "Sites using Jekyll" %}current{% endif %}">
<a href="{{ site.url }}/docs/sites">Sites using Jekyll</a>
</li>
@@ -5,17 +5,17 @@ prev_section: home
next_section: usage
---
-Getting Jekyll installed and ready-to-go should only take a few minutes.
+Getting Jekyll installed and ready-to-go should only take a few minutes. If it ever becomes a pain in the ass, you should [file an issue](../issues) (or submit a pull request) about what might be a better way to do things.
### Requirements
Installing Jekyll is easy and straight-forward, but there’s a few requirements you’ll need to make sure your system has before you start.
-- Ruby
-- RubyGems
+- [Ruby](http://www.ruby-lang.org/en/downloads/)
+- [RubyGems](http://rubygems.org/pages/download)
- Linux, Unix, or Mac OS X
-Note that it is possible to get [Jekyll running on Windows](http://www.madhur.co.in/blog/2011/09/01/runningjekyllwindows.html), however the official documentation does not support installation on Windows platforms.
+Note: It is possible to get [Jekyll running on Windows](http://www.madhur.co.in/blog/2011/09/01/runningjekyllwindows.html), however the official documentation does not support installation on Windows platforms.
## Install with RubyGems
@@ -26,44 +26,9 @@ The best way to install Jekyll is via
gem install jekyll
{% endhighlight %}
-Jekyll requires the gems `directory_watcher`, `liquid`, `open4`, `maruku` and `classifier`. These are automatically installed by the `gem install` command.
+Jekyll requires the gems `directory_watcher`, `liquid`, `open4`, `maruku` and `classifier`. These are automatically installed by the `gem install` command, so chances are you won’t have to worry about them at all.
-### Installation Problems
-
-If you encounter errors during gem installation, you may need to install
-the header files for compiling extension modules for ruby 1.9.1. This
-can be done on Debian systems by running:
-
-{% highlight bash %}
-sudo apt-get install ruby1.9.1-dev
-{% endhighlight %}
-
-or on Red Hat, CentOS, and Fedora systems by running:
-
-{% highlight bash %}
-sudo yum install ruby-devel
-{% endhighlight %}
-
-On [NearlyFreeSpeech](http://nearlyfreespeech.net/) you need to run the command with the following environment variable:
-
-{% highlight bash %}
-RB_USER_INSTALL=true gem install jekyll
-{% endhighlight %}
-
-On OSX, you may need to update RubyGems:
-
-{% highlight bash %}
-sudo gem update --system
-{% endhighlight %}
-
-To install gem on Gentoo:
-
-{% highlight bash %}
-sudo emerge -av dev-ruby/rubygems
-{% endhighlight %}
-
-On Windows, you may need to install [RubyInstaller
-DevKit](http://wiki.github.com/oneclick/rubyinstaller/development-kit).
+If you have problems installing Jekyll, check out the [troubleshooting](../troubleshooting) page or [report an issue](../issues) so the Jekyll community can improve the experience for everyone.
## Optional Extras
@@ -75,13 +40,14 @@ If you want syntax highlighting via the `{{ "{% highlight " }}%}` tag in your
posts, you’ll need to install [Pygments](http://pygments.org/).
#### Installing Pygments on OSX
+
Mac OS X (Leopard onwards) come preinstalled with Python, so on just about any OS X machine you can install Pygments simply by running:
{% highlight bash %}
sudo easy_install Pygments
{% endhighlight %}
-##### Homebrew
+##### Installing Pygments using Homebrew
Alternatively, you can install Pygments with [Homebrew](http://mxcl.github.com/homebrew/), an excellent package manager for OS X:
{% highlight bash %}
@@ -94,7 +60,7 @@ pip install pygments
**ProTip™**: Homebrew doesn’t symlink the executables for you. For the Homebrew default Cellar location and Python 2.7, be sure to add `/usr/local/share/python` to your `PATH`. For more information, check out [the Homebrew wiki](https://github.com/mxcl/homebrew/wiki/Homebrew-and-Python).
-##### MacPorts
+##### Installing Pygments using MacPorts
If you use MacPorts, you can install Pygments by running:
@@ -105,54 +71,60 @@ sudo port install python25 py25-pygments
Seriously though, you should check out [Homebrew](http://mxcl.github.com/homebrew/)—it’s awesome.
-**On Archlinux:**
+#### Installing Pygments on Arch Linux
-`sudo pacman -S python-pygments`\
-Or to use python2 for pygments:\
-`sudo pacman -S python2-pygments`\
-**Note**: python2 pygments version creates a `pygmentize2` executable,
-while jekyll tries to find `pygmentize`. \
-Either create a symlink
-`# ln -s /usr/bin/pygmentize2 /usr/bin/pygmentize` or use the python3
-version. (This advice seems to be outdated — python2-pygments does
-install pygmentize).
+You can install Pygments using the pacman package manager as follows:
-**On Ubuntu and Debian:**
+{% highlight bash %}
+sudo pacman -S python-pygments
+{% endhighlight %}
-`sudo apt-get install python-pygments`
+Or to use python2 for Pygments:
+{% highlight bash %}
+sudo pacman -S python2-pygments
+{% endhighlight %}
-**On Fedora:**
+#### Installing Pygments on Ubuntu and Debian
-`sudo yum install python-pygments`
+{% highlight bash %}
+sudo apt-get install python-pygments
+{% endhighlight %}
-**On Gentoo:**
+#### Installing Pygments on RedHat, Fedora, and CentOS
-`sudo emerge -av dev-python/pygments`
+{% highlight bash %}
+sudo yum install python-pygments
+{% endhighlight %}
-### LaTeX to PNG
+#### Installing Pygments on Gentoo
-Maruku comes with optional support for LaTeX to PNG rendering via
-blahtex (Version 0.6) which must be in your \$PATH along with `dvips`.
+{% highlight bash %}
+sudo emerge -av dev-python/pygments
+{% endhighlight %}
-(NOTE: [remi’s fork of
-Maruku](http://github.com/remi/maruku/tree/master) does not assume a
-fixed location for `dvips` if you need that fixed)
+### LaTeX Support
+
+Maruku comes with optional support for LaTeX to PNG rendering via
+blahtex (Version 0.6) which must be in your `$PATH` along with `dvips`. If you need Maruku to not assume a fixed location for `dvips`, check out [Remi’s Maruku fork](http://github.com/remi/maruku).
### RDiscount
-If you prefer to use
-[RDiscount](http://github.com/rtomayko/rdiscount/tree/master) instead of
-[Maruku](http://maruku.rubyforge.org/) for markdown, just make sure it’s
-installed:
+If you prefer to use [RDiscount](http://github.com/rtomayko/rdiscount) instead of [Maruku](http://maruku.rubyforge.org/) for markdown, just make sure you have it installed:
-`sudo gem install rdiscount`
+{% highlight bash %}
+sudo gem install rdiscount
+{% endhighlight %}
-And run Jekyll with the following option:
+And then run Jekyll with the following option:
-`jekyll --rdiscount`
+{% highlight bash %}
+jekyll --rdiscount
+{% endhighlight %}
-Or, in your `_config.yml` file put the following so you don’t have to
-specify the flag:
+Or, specify RDiscount as the markdown engine in your `_config.yml` file to have Jekyll run with that option by default (so you don’t have to specify the flag every time).
-`markdown: rdiscount`
+{% highlight bash %}
+# In _config.yml
+markdown: rdiscount
+{% endhighlight %}
@@ -2,7 +2,7 @@
layout: docs
title: Reporting issues
prev_section: contributing
-next_section: sites
+next_section: troubleshooting
---
Move along, people. Nothing to see here.
@@ -1,7 +1,7 @@
---
layout: docs
title: Sites using Jekyll
-prev_section: issues
+prev_section: troubleshooting
next_section: resources
---
@@ -0,0 +1,46 @@
+---
+layout: docs
+title: Troubleshooting
+previous: issues
+next: sites
+---
+
+If you ever run into problems installing or using Jekyll, here’s a few tips that might be of help. If the problem you’re experiencing isn’t covered below, please [report an issue](../issues) so the Jekyll community can make everyone’s experience better.
+
+## Installation Problems
+
+If you encounter errors during gem installation, you may need to install
+the header files for compiling extension modules for ruby 1.9.1. This
+can be done on Ubunutu or Debian by running:
+
+{% highlight bash %}
+sudo apt-get install ruby1.9.1-dev
+{% endhighlight %}
+
+On Red Hat, CentOS, and Fedora systems you can do this by running:
+
+{% highlight bash %}
+sudo yum install ruby-devel
+{% endhighlight %}
+
+On [NearlyFreeSpeech](http://nearlyfreespeech.net/) you need to run the command with the following environment variable:
+
+{% highlight bash %}
+RB_USER_INSTALL=true gem install jekyll
+{% endhighlight %}
+
+On OSX, you may need to update RubyGems:
+
+{% highlight bash %}
+sudo gem update --system
+{% endhighlight %}
+
+To install RubyGems on Gentoo:
+
+{% highlight bash %}
+sudo emerge -av dev-ruby/rubygems
+{% endhighlight %}
+
+On Windows, you may need to install [RubyInstaller
+DevKit](http://wiki.github.com/oneclick/rubyinstaller/development-kit).
+
View
@@ -438,7 +438,6 @@ h1, h2, h3, h4, h5, h6 {
margin: 0;
}
-
a {
color: #fc0;
text-decoration: none;
@@ -463,3 +462,9 @@ p {
.right { float: right; }
.align-right { text-align: right; }
.align-left { text-align: left; }
+
+/* Article HTML */
+
+h5 {
+ margin: 1.5em 0 1em;
+}

0 comments on commit e9bf521

Please sign in to comment.