bookingit¶ ↑

A basic publishing system that takes Mardown and Git repositories and produces a readable “book” in the following forms:

• Website

• PDF

• EBook

This only produces a website version, currently

The idea is that you can show the evolution of code by referencing particular versions or diffs beteween verions. Further, you can show the actual output of commands run from particular verisons of the repo.

Let’s say we have a Rails app locally in a git repo called “foobar”. We coudl write the following:

Here is how our controller looks currently:

    git://foobar.git/app/controlleres/users_controller.rb#initial-version

We'd like to change the mailer call to use Resque

    git://foobar.git/app/controllers/users_controller.rb#initial-version..add-resque-to-controller

Instead of interpreting the code blocks as verbatim text, bookingit notices the single-line URL and will read the file or diff based on it, and substitute that into the output. It would be the same as if we wrote our Markdown like so:

Here is how our controller looks currently:

```ruby
class UsersController < ApplicationController::Base
  def create
    @user = User.new(params.require(:user))
    if @user.save
      UserMailer.welcome_email(user).deliver
      redirect_to root_path
    else
      render 'new'
    end
  end
end
```

We'd like to change the mailer call to use Resque

```diff
--- a/app/controllers/users_controller.rb
+++ b/app/controllers/users_controller.rb
  def create
    @user = User.new(params.require(:user))
    if @user.save
-     UserMailer.welcome_email(user).deliver
+     Resque.enqueue(WelcomeEmailJob,user.id)
      redirect_to root_path
    else
```

Here is what is currently supported:

• git://some_repo.git/path/in/repo.rb#sha1_or_tag - show the contents of the file from the git repo at the given version (either SHA1 or tag)

• git://some_repo.git/path/in/repo.rb#sha1_or_tag..other_sha1_or_tag - show a diff of the contents of the file between the two versions.

• git://some_repo.git/path/in/repo.rb#..other_sha1_or_tag - shortcut for showing a diff between the given SHA1 or tag and the previous revision.

• git://some_repo.git/#sha1_or_tag!rake test - check out the repo at the given SHA1 or tag, then run the command after the bang, and include the output of that command in the text

• sh:///some/filesystem/path#ls -l - cd to the given path, run the command, and include its output in the text.

The paths used can be relative (e.g. git://some_repo.git) or absolute (e.g. git:///some/other/repo.git). Relative paths are relative to the directory where ran bookingit. You can change where the git repos are located by setting git_repos_basedir in your config (see below).

For URLs that contain shell commands, bookingit will fail if the shell command fails, because the assumption is that your embedded commands are expected to succeed (exit 0). If you need to run a shell command that is expected to fail (e.g. demonstrate a failing test case), append !nonzero to the URL, e.g. git://some_repo.git/!rake test!nonzero. In this form, bookingit will fail if the command succeeds.

The book’s configuration is driven by config.json, which looks like so:

{
  "front_matter": [
    "intro.md"
  ],
  "main_matter": [
    "chapter1.md",
    "chapter2.md"
  ],
  "back_matter": [
    "appendix.md"
  ],
  "rendering": {
    "stylesheets": "styles.css",
    "git_repos_basedir": "./git_repos",
    "languages" : {
      ".super": "superscript",
      "/Makefile": "make"
    }
  },
  "templates": {
    "index": "/full/path/to/index/html"
  }
}

The book’s contents are described in front_matter, main_matter, and back_matter. The values of these can be a single file or an array of files. The likely pattern is that you would have a single entry for front_matter, an array in main_matter for each chapter, and an optional back_matter for things like appendeces or a colophon.

Example:

{
  "front_matter": "intro.md"
  "main_matter": [
    "chapter1.md",
    "chapter2.md",
    "chapter3.md",
    "chapter4.md"
  ],
  "back_matter": "appendix.md"
}

The rendering section allows some control over the rendering process. It supports three keys:

git_repos_basedir

path to where your git repos are, for bringing in code. For example, if you specify the value “./repos”, then a url like git://my_repo.git/foo/bar.rb#version-1 would look in ./repos/my_repo/foo/bar.rb for the file contents. This path should be relative to where you run bookingit.

languages

A map of file extensions or regexps to language names for syntax detection. If the key starts and ends with a /, it will be interpreted as a regexp, otherwise as a file extension

stylesheets

An array of stylesheets that will be copied and linked to each HTML page

syntax_theme

A highlight.js name for the syntax highlighting theme to use.

The templates section allows you to specify a Mustache template for various bits of the generated markup. The files listed must be full-qualified paths and must omit the .mustache extension, which must be present on the file (e.g. if you specify /tmp/foo.html, the file should be located in /tmp/foo.html.mustache.

Current templates are:

index

The template of the main home page or splash page. See the built-in one for values you have access to.

In addition to values provided by bookingit, you can specify any values you want in your config.json file and they will be available in your templates under the config namespace, e.g.:

{
  "front_matter": "intro.md"
  "main_matter": [
    "chapter1.md",
    "chapter2.md",
    "chapter3.md",
    "chapter4.md"
  ],
  "back_matter": "appendix.md",
  "templates": {
    "index": "/tmp/foo.html"
  },
  "title": "My Great Book!",
  "subtitle": "A long journey from Milan to Minsk"
}

Then, in /tmp/foo.html

<html>
  <body>
    <h1>{{#config}}{{title}}{{/config}}</h1>
    <h2>{{#config}}{{subtitle}}{{/config}}</h2>
  </body>
</html>

There are a few other options that control content:

clicky

If present, the id attribute will be used to set up Clicky tracking

typekit

If present, the id attribute will be used to insert the TypeKit boilerplate

favicon

If set to true, will include /favicon.ico meta tag in your output

applie-mobile-web

If set to true, will include a few meta tags that help the app work in “bookmarked to the homescreen” mode