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-1would look in./repos/my_repo/foo/bar.rbfor the file contents. This path should be relative to where you runbookingit. 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
idattribute will be used to set up Clicky tracking typekit-
If present, the
idattribute will be used to insert the TypeKit boilerplate favicon-
If set to
true, will include/favicon.icometa 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