More writing.

tobi · Mar 14, 2011 · cf71631 · cf71631
1 parent 6c0e4b3
commit cf71631
Show file tree

Hide file tree

Showing 4 changed files with 78 additions and 28 deletions.
diff --git a/doc/book/book.asc b/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[]
diff --git a/doc/book/ch00-preface.asc b/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_
diff --git a/doc/book/ch01-quick-start.asc b/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,15 +37,15 @@ 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@.
 
 (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!
diff --git a/doc/book/ch02-directory-layout.asc b/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