1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
---
layout: docs
title: Troubleshooting
prev_section: deployment-methods
next_section: sites
permalink: /docs/troubleshooting/
---
If you ever run into problems installing or using Jekyll, here are a few tips
that might be of help. If the problem you’re experiencing isn’t covered below,
please [report an issue]({{site.help_url}}/issues/new) 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 Ubuntu 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
following commands before installing Jekyll:
{% highlight bash %}
export GEM_HOME=/home/private/gems
export GEM_PATH=/home/private/gems:/usr/local/lib/ruby/gems/1.8/
export PATH=$PATH:/home/private/gems/bin
export RB_USER_INSTALL='true'
{% endhighlight %}
On OSX, you may need to update RubyGems:
{% highlight bash %}
sudo gem update --system
{% endhighlight %}
If you still have issues, you may need to [use XCode to install Command Line
Tools](http://www.zlu.me/ruby/os%20x/gem/mountain%20lion/2012/02/21/install-native-ruby-gem-in-mountain-lion-preview.html)
that will allow you to install native gems using the following command:
{% highlight bash %}
sudo gem install jekyll
{% endhighlight %}
To install RubyGems on Gentoo:
{% highlight bash %}
sudo emerge -av dev-ruby/rubygems
{% endhighlight %}
On Windows, you may need to install [RubyInstaller
DevKit](https://wiki.github.com/oneclick/rubyinstaller/development-kit).
## Problems running Jekyll
On Debian or Ubuntu, you may need to add `/var/lib/gems/1.8/bin/` to your path
in order to have the `jekyll` executable be available in your Terminal.
## Base-URL Problems
If you are using base-url option like:
{% highlight bash %}
jekyll serve --baseurl '/blog'
{% endhighlight %}
… then make sure that you access the site at:
{% highlight bash %}
http://localhost:4000/blog/index.html
{% endhighlight %}
It won’t work to just access:
{% highlight bash %}
http://localhost:4000/blog
{% endhighlight %}
## Configuration problems
The order of precedence for conflicting [configuration settings](../configuration/)
is as follows:
1. Command-line flags
2. Configuration file settings
3. Defaults
That is: defaults are overridden by options specified in `_config.yml`,
and flags specified at the command-line will override all other settings
specified elsewhere.
## Markup Problems
The various markup engines that Jekyll uses may have some issues. This
page will document them to help others who may run into the same
problems.
### Maruku
If your link has characters that need to be escaped, you need to use
this syntax:
{% highlight text %}
{% endhighlight %}
If you have an empty tag, i.e. `<script src="js.js"></script>`, Maruku
transforms this into `<script src="js.js" />`. This causes problems in
Firefox and possibly other browsers and is [discouraged in
XHTML.](http://www.w3.org/TR/xhtml1/#C_3) An easy fix is to put a space
between the opening and closing tags.
### Liquid
The latest version, version 2.0, seems to break the use of `{{ "{{" }}` in
templates. Unlike previous versions, using `{{ "{{" }}` in 2.0 triggers the
following error:
{% highlight bash %}
'{{ "{{" }}' was not properly terminated with regexp: /\}\}/ (Liquid::SyntaxError)
{% endhighlight %}
### Excerpts
Since v1.0.0, Jekyll has had automatically-generated post excerpts. Since
v1.1.0, Jekyll also passes these excerpts through Liquid, which can cause
strange errors where references don't exist or a tag hasn't been closed. If you
run into these errors, try setting `excerpt_separator: ""` in your
`_config.yml`, or set it to some nonsense string.
<div class="note">
<h5>Please report issues you encounter!</h5>
<p>
If you come across a bug, please <a href="{{ site.help_url }}/issues/new">create an issue</a>
on GitHub describing the problem and any work-arounds you find so we can
document it here for others.
</p>
</div>
|
