153 lines
3.5 KiB
Plaintext
153 lines
3.5 KiB
Plaintext
== Chapter 1: Quick Start
|
|
|
|
This chapter is designed to get you up and running with Jekyll as quickly as
|
|
possible.
|
|
|
|
|
|
=== Installation
|
|
|
|
The best way to install Jekyll is via RubyGems:
|
|
|
|
----
|
|
gem install jekyll
|
|
----
|
|
|
|
This is all you need in order to get started with a basic Jekyll site. Some
|
|
options require additional packages to be installed.
|
|
|
|
If you encounter errors during gem installation, you may need to install the
|
|
header files for compiling extension modules for ruby 1.8:
|
|
|
|
.Debian
|
|
----
|
|
sudo apt-get install ruby1.8-dev
|
|
----
|
|
|
|
.Red Hat / CentOS / Fedora systems
|
|
----
|
|
sudo yum install ruby-devel
|
|
----
|
|
|
|
.NearlyFreeSpeech
|
|
----
|
|
RB_USER_INSTALL=true gem install jekyll
|
|
----
|
|
|
|
If you encounter errors like +Failed to build gem native extension+ on Windows
|
|
you may need to install http://wiki.github.com/oneclick/rubyinstaller/development-kit[RubyInstaller
|
|
DevKit].
|
|
|
|
==== LaTeX to PNG
|
|
|
|
Maruku comes with optional support for LaTeX to PNG rendering via blahtex
|
|
(Version 0.6) which must be in your $PATH along with @dvips@.
|
|
|
|
(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)
|
|
|
|
==== RDiscount
|
|
|
|
If you prefer to use
|
|
http://github.com/rtomayko/rdiscount/tree/master[RDiscount] instead of
|
|
http://maruku.rubyforge.org/[Maruku] for markdown, just make sure it's
|
|
installed:
|
|
|
|
----
|
|
sudo gem install rdiscount
|
|
----
|
|
|
|
And run Jekyll with the following option:
|
|
|
|
----
|
|
jekyll --rdiscount
|
|
----
|
|
|
|
Or, in your @_config.yml@ file put the following so you don't have to specify the flag:
|
|
|
|
----
|
|
markdown: rdiscount
|
|
----
|
|
|
|
==== Pygments
|
|
|
|
If you want syntax highlighting via the @{% highlight %}@ tag in your posts,
|
|
you'll need to install http://pygments.org/[Pygments].
|
|
|
|
.On OSX with Homebrew
|
|
----
|
|
brew install pip && pip install pygments
|
|
----
|
|
|
|
.On OSX with MacPorts
|
|
----
|
|
sudo port install python25 py25-pygments
|
|
----
|
|
|
|
.Bare OS X Leopard
|
|
----
|
|
sudo easy_install Pygments
|
|
----
|
|
|
|
.Archlinux
|
|
----
|
|
sudo pacman -S python-pygments
|
|
----
|
|
|
|
.Archlinux 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.
|
|
|
|
.Ubuntu and Debian
|
|
----
|
|
sudo apt-get install python-pygments
|
|
----
|
|
|
|
.Gentoo
|
|
----
|
|
$ sudo emerge -av dev-python/pygments
|
|
----
|
|
|
|
|
|
=== Creating your First Site
|
|
|
|
Jekyll comes with a handy generator that will create a barebones skeleton site
|
|
to help you get up and running in no time. Simply create an empty directory to
|
|
contain your site, navigate to it, and run the generator command:
|
|
|
|
----
|
|
$ mkdir mysite
|
|
$ cd mysite
|
|
$ jekyll gen
|
|
----
|
|
|
|
Make sure the directory is empty or Jekyll will refuse to run. If everything
|
|
was successful, you'll be left with a complete, valid Jekyll site that's ready
|
|
to be converted into a static site.
|
|
|
|
To perform the conversion, make sure you're in the root of your Jekyll site
|
|
directory and run:
|
|
|
|
----
|
|
$ jekyll --server
|
|
----
|
|
|
|
If all goes well, you should get a few lines with information about config
|
|
file detection, source and destination paths, and a success message.
|
|
|
|
The `--server` command line option fires up a simple web server that will
|
|
serve the static site we just generated so that we can easily preview what it
|
|
will look like once we deploy it to a production environment.
|
|
|
|
Open up your favorite web browser and navigate to:
|
|
|
|
----
|
|
http://localhost:4000
|
|
----
|
|
|
|
Congratulations! You have now successfully created and converted your first
|
|
Jekyll site! |