Building a GitBook with Mathematica

Question

GitBook is a fun little website that will take Markdown source material and build a little book out of it.

How can I use Mathematica to build a GitBook with a minimum of effort?

Answer 1

tl;dr

This is really quite easy with a toolkit I've been building; this is an example of a GitBook I built with these tools.

---

Preface

This answer is gonna build off some stuff I've been developing off-and-on for the past few months. Everything is packaged up and most of it is in a palette, so you'll be able to do this with minimal effort.

It started with my attempts to build websites with Mathematica. That turned out to be a decent success. This Mathematica tutorial is an example of a fun, non-trivial website I built with Mathematica.

Then halirutan brought GitBook to my attention and I realized I could adapt that quickly to my needs.

First I took my tutorial website and built a GitBook out of it.

But now I've done that one better and generalized that framework entirely, packaging up my GitBook builder.

Here's how we do this. It's really quite easy, although there is some minimal book-keeping involved.

Book Development

It may seem like there are many steps here, but most of them are so fast and boiler-plate that by using the palettes and templates I provide you can get a GitBook up and running in about 5 minutes (excluding the time it takes to actually write your content)

Initializing a website

My system builds off my work making a website builder, so to start I make a website that I simply never build an deploy.

I have a site-builder palette, which can be used to make a new one and add content. Alternately, you can simply copy down the content I have here and just build off of it.

Writing our content

For this sample GitBook I poached the content from the python tutorial to show that this system can do things beyond Mathematica code.

To make the content we use a stylesheet I developed for writing Markdown websites, which requires that one has installed my package BTools.

These notebooks are basically the same as any notebook:

"Text" cells get exported as plain text, "Code" cells get exported as code, etc.

There are also a bunch of custom cell types built-in with different export behaviors, all linked together via StyleKeyMapping for ease of access.

Book-keeping and Metadata

The only thing that's really different is a metadata block that's put at the top of the notebook (the style for which is accessed via Cmd+`:

This is used by pelican and my site builder, and we'll use it again here for setting up the GitBook SUMMARY.md

The main things we need for that are the "ID" and "Path" parameters. The "Path" gives the section it should be nested under and the "ID" gives the sorting in standard versioning syntax.

As an example, here's the used metadata for one page:

<|
 "Title" -> "Invoking the Interpreter",
 "Path" -> "Using the Python Interpreter/Invoking the Interpreter",
 "ID" -> "2.1"
 |>

And here is the the same for the following page:

<|
 "Title" -> "Argument Passing",
 "Path" -> "Using the Python Interpreter/Invoking the Interpreter",
 "ID" -> "2.1.1"
 |>

We see that in a given section of the book all that really changes is the "ID" (which doesn't even have to be in a list like that) and the "Title".

Creating the Intro Page

All of my websites have an About page to them, so I just use that as the GitBook README

So you'll have to add an About page under the pages directory of the site. Again the easiest thing is likely just to copy the sample site I have and edit that About page.

Building the Site

With the content part of the equation handled we can now actually get the book deployed.

I've written a package for this, but I'll do a quick walkthrough of the requisite steps.

Copying content

First we simply copy over the content from the site to our build directory. I take all of the md files from the "posts" directories of the site we've built, stripping the metadata, and anything else in the "content" directory

Creating the README.md

This is build from the "pages/About.md" file, stripping all of the metainfo first. I simply export that to a top-level "README.md" file

Creating the SUMMARY.md

This was the only at-all-challenging part of the whole endeavor. First I extract all of metainfo, then I sort this by "ID", group it by path components, build a new markdown notebook from these parts, and call NotebookMarkdownSave on that.

Setting up the GitHub Repo

Finally, all one needs to do is initialize a GitHub remote, initialize git on the book directory, and push that to GitHub.

Package-Level Flow

None of the preceding steps actually need to be done by hand, though. I have two functions in the package I linked to before, GitBookBuild and GitBookPush.

The first builds a GitBook from the site directory, and is called like so:

build = FileNameJoin@{$UserDocumentsDirectory, "GitHub", 
    "mathematica-gitbook"};

GitBookBuild[
  FileNameJoin@{$WebSiteDirectory, "gitbook"},
  build
  ];

The second will initialize the git repo, and can use the GitHub API to initialize a GitHub repo too. That's called like this:

remote =
  "https://github.com/b3m2a1/mathematica-gitbook";

GitBookPush[build, remote]

When all of this is done we get a GitHub repo like this:

Everytime you edit the source, simply call GitBookBuild and GitBookPush again and it'll push the changes.

Setting up the GitBook

The last step is just to go to gitbook.com, make an account, and make a new book that loads from the GitHub repo.

After the smoke clears, you get a nice new GitBook: