# Building a GitBook with Mathematica

**URL:** <https://community.wolfram.com/t/building-a-gitbook-with-mathematica/11775>\
**Category:** Staff Picks\
**Tags:** authoring-and-publishing, external-interfaces, staff-pick\
**Created:** [January 7, 2018, 6:04am UTC](https://community.wolfram.com/t/building-a-gitbook-with-mathematica/11775 "2018-01-07T06:04:51Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![b3m2a1](https://yyz1.discourse-cdn.com/wolfram/user_avatar/community.wolfram.com/b3m2a1/32/7562_2.png) [@b3m2a1](https://community.wolfram.com/u/b3m2a1)\
**Post date:** [January 7, 2018, 6:04am UTC](https://community.wolfram.com/t/building-a-gitbook-with-mathematica/11775/1 "2018-01-07T06:04:51Z")

</div>

This is a [cross post from the StackExchange](https://mathematica.stackexchange.com/a/163194/38205) that I thought might appeal to some here as well

* * *

### Preface

This 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](https://mathematica.stackexchange.com/q/152663/38205). That turned out to be a decent success. [This Mathematica tutorial](https://www.wolframcloud.com/app/objects/b3m2a1.testing/tutorial/main.html) is an example of a fun, non-trivial website I built with Mathematica.

Then halirutan brought [GitBook](https://www.gitbook.com) 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](https://b3m2a1.gitbooks.io/mathematica-tutorial/content/).

But now I’ve done that one better and generalized that framework entirely, [packaging up my GitBook builder](https://github.com/b3m2a1/mathematica-tools/blob/master/GitBookBuilder.wl).

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](https://github.com/b3m2a1/mathematica-gitbook/tree/master/src/content) and just build off of it.

### Writing our content

For this sample GitBook I poached the content from the [python tutorial](https://docs.python.org/3/tutorial/introduction.html) to show that this system can do things beyond Mathematica code.

To make the content we use [a stylesheet I developed for writing Markdown](https://github.com/b3m2a1/mathematica-BTools/blob/master/FrontEnd/StyleSheets/BTools/MarkdownNotebook.nb) websites, which requires that one has installed my package [BTools](https://github.com/b3m2a1/mathematica-BTools).

These notebooks are basically the same as any notebook:

[![asd](https://i.stack.imgur.com/giSXH.png)](https://i.stack.imgur.com/giSXH.png)

`"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+`:

[![meta](https://i.stack.imgur.com/DWLXT.png)](https://i.stack.imgur.com/DWLXT.png)

This is used by pelican and my site builder, and we’ll use it again here for setting up the [GitBook SUMMARY.md](https://toolchain.gitbook.com/pages.html)

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](https://b3m2a1.gitbooks.io/gitbook/content/2-using-the-interpreter/1-invoking-the-interpreter.html):

```
<|
 "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](https://b3m2a1.gitbooks.io/gitbook/content/2-using-the-interpreter/1-invoking-the-interpreter/1-argument-passing.html):

```
<|
 "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](https://toolchain.gitbook.com/structure.html)

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](https://github.com/b3m2a1/mathematica-tools/blob/master/GitBookBuilder.wl), 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](https://github.com/b3m2a1/mathematica-gitbook):

![gitbook](https://i.stack.imgur.com/Uhohr.png)][3](https://i.stack.imgur.com/Uhohr.png)

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](https://www.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](https://b3m2a1.gitbooks.io/gitbook/content/):

[![gitbook](https://i.stack.imgur.com/TGzSh.png)](https://i.stack.imgur.com/TGzSh.png)

---

<div class="post-metadata">

**Author:** ![wolframcommunity](https://yyz1.discourse-cdn.com/wolfram/user_avatar/community.wolfram.com/wolframcommunity/32/8335_2.png) [@wolframcommunity](https://community.wolfram.com/u/wolframcommunity)\
**Post date:** [January 12, 2018, 12:37pm UTC](https://community.wolfram.com/t/building-a-gitbook-with-mathematica/11775/2 "2018-01-12T12:37:45Z")

</div>

![2015-11-02_10-07-11.png](https://global.discourse-cdn.com/wolfram/original/3X/5/0/50e59c9ead62f729e7130d3ea1482555a75602b6.png)

- Congratulations! This post is now a [Staff Pick](http://community.wolfram.com/content?curTag=staff+picks) as distinguished by a badge on [your profile](http://community.wolfram.com/web/b3m2a1)! Thank you, keep it coming!
