Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

More writing.

  • Loading branch information...
commit cf71631c343894456dea827b2ad3abf487c440ec 1 parent 6c0e4b3
@mojombo mojombo authored
View
2  doc/book/book.asc
@@ -4,5 +4,7 @@ Jekyll
:Email: <tom@mojombo.com>
include::ch00-preface.asc[]
+
include::ch01-quick-start.asc[]
+
include::ch02-directory-layout.asc[]
View
27 doc/book/ch00-preface.asc
@@ -1,11 +1,24 @@
== Preface
-Jekyll began life as a very simple project that I wrote to make it easy for me
-to write blog posts in Markdown and have them converted into a static site
-that could be hosted anywhere. My main focus was simplicity and the reduction
-of configuration.
+Jekyll was born out the desire to create a blog engine that would make it
+possible to write posts in my local text editor, version those posts with Git,
+and keep up with my desire to tweak the styles and layout of my site.
+
+In other words, I wanted something that fit into my existing software
+development workflow and toolchain. Jekyll handles not only this case, but a
+wide variety of other situations that call for static site generation based on
+converted content and layout templates.
+
+At its core, Jekyll is a text transformation engine. The concept behind the
+system is this: you give it text written in your favorite markup language, be
+that Markdown, Textile, or just plain HTML, and it churns that through a
+layout or series of layout files. Throughout that process you can tweak how
+you want the site URLs to look, what data gets displayed on the layout and
+much more.
+
+If you're looking for a simple, yet powerful solution to your blogging or
+static site needs, Jekyll may be just what you've been looking for.
-Several months later we chose Jekyll as the static site generator that would
=== What this book covers
@@ -23,4 +36,6 @@ _Chapter X, Deploying your Jekyll Site_
_Chapter X, Customizing Jekyll with Plugins_
-_Chapter X, Migrating to Jekyll from your Existing Blog_
+_Chapter X, Migrating to Jekyll from your Existing Blog_
+
+_Chapter X, Configuration Reference_
View
57 doc/book/ch01-quick-start.asc
@@ -1,8 +1,9 @@
-== Quick Start
+== 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:
@@ -11,6 +12,9 @@ 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:
@@ -33,7 +37,7 @@ 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
+==== 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@.
@@ -41,7 +45,7 @@ Maruku comes with optional support for LaTeX to PNG rendering via blahtex
(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
+==== RDiscount
If you prefer to use
http://github.com/rtomayko/rdiscount/tree/master[RDiscount] instead of
@@ -64,7 +68,7 @@ Or, in your @_config.yml@ file put the following so you don't have to specify th
markdown: rdiscount
----
-=== Pygments
+==== Pygments
If you want syntax highlighting via the @{% highlight %}@ tag in your posts,
you'll need to install http://pygments.org/[Pygments].
@@ -91,7 +95,7 @@ sudo pacman -S python-pygments
.Archlinux python2 for Pygments
----
-sudo pacman -S python2-pygments
+$ sudo pacman -S python2-pygments
----
NOTE: python2 pygments version creates a `pygmentize2` executable, while
@@ -105,14 +109,45 @@ sudo apt-get install python-pygments
.Gentoo
----
-sudo emerge -av dev-python/pygments
+$ 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:
-Creating a Jekyll site usually involves the following, [[once jekyll is installed.|Install]]
+----
+$ 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
+----
-# Set up the basic structure of the site
-# Create some posts, or [[import them from your previous platform|Blog migrations]]
-# Run your site locally to see how it looks
-# Deploy your site
+Congratulations! You have now successfully created and converted your first
+Jekyll site!
View
20 doc/book/ch02-directory-layout.asc
@@ -1,13 +1,8 @@
-== Directory Layout
+== Chapter 2: Directory Layout
-At its core, Jekyll is a text transformation engine. The concept behind the
-system is this: you give it text written in your favorite markup language, be
-that Markdown, Textile, or just plain HTML, and it churns that through a
-layout or series of layout files. Throughout that process you can tweak how
-you want the site URLs to look, what data gets displayed on the layout and
-more.
-
-A basic Jekyll site usually looks something like this:
+If you followed the Quick Start in the last chapter, you have a Jekyll site on
+your local machine. Let's take a closer look at it and see what makes it tick.
+The file layout should look something like this:
----
.
@@ -26,13 +21,16 @@ A basic Jekyll site usually looks something like this:
Notice that some of the files and directories begin with an underscore. These
have special meaning to Jekyll. The underscore ensures that they will not
-interfere with the rest of your site's normal content.
+interfere with the rest of your site's normal content. It also means that if
+any of your normal files start with an underscore, they will cause problems,
+so try to avoid this.
=== _config.yml
This file stores configuration data. A majority of these options can be
specified from the command line executable but it's easier to throw them in
-here so you don't have to type them out every time.
+here so you don't have to type them out every time. Detailed explanations of
+configuration directives can be found in Chapter X.
=== _layouts
Please sign in to comment.
Something went wrong with that request. Please try again.