Producing Gitbooks

DATE: 2017-11-01

AUTHOR: John L. Godlee

I've been wanting to write up my recipes into a book for a while, but for the longest time I couldn't find a decent way to automate the process, and I wasn't about to do it manually. Then I found out about gitbooks[1], which are normally used for online documentation by the looks of it, but seemed perfect for my needs. THe following is a short post about how I used gitbooks and why I think they are great for keeping recipe books, scrapbooks, journals, etc.

1: https://github.com/GitbookIO/gitbook

I have all my recipes as markdown files nested inside folders like Dessert and Bread/Foccacia. A tree command of my recipes folder reveals something like this:

Recipes
    ├── Dessert
    │   ├── Baked_pumpkin_with_apple.md
    │   ├── Biscuit_variation.jpg
    │   ├── Chia_Seed_Chocolate_Pudding.md
    │   ├── Victoria_Sponge_Cake.md
    │   └── vegan_brownie.md
    ├── Drinks
    │   ├── Beech_Leaf_Gin.md
    │   ├── Blackberry_Wine.md
    │   ├── Blackcurrant_cordial.md
    └── Main_Dishes
        ├── Basil_Sage_Gnocchi.md
        ├── Beans_with_charred_chillies.md
        └── Chorizo_and_white_bean_stew.md

Each .md file looks like this:

# Brown Loaf

## Ingredients


## Method
1. Mix together flour, yeast, salt
2. Rub in olive oil, removing lumps
3. Pour in water and mix to dough
4. Knead for about 10 minutes
5. Cover with some oil and return to bowl
6. Cover with plastic and leave to rise for 1.5 hours
7. Put into loaf tin, or don't
8. Leave for another 30 minutes
9. Score and dust with flour
10. Bake at 180C for 35-40 minutes

At first I tried using pandoc to compile all of the files together as a .html or .pdf, and that worked to a degree. I came up with this little bash script to compile the files when I was in the root of the Recipes folder:

#!/bin/bash

# Pandoc call
for dir in ./* ; do (cd "$dir" && pandoc *.md --toc --toc-depth=1 --template=default.latex -V geometry:margin=40pt -V title="$dir" -o result.pdf) ; done

# Concatenate .pdf files
pdfjoin */*.pdf

This dives into each directory in turn, makes one .pdf per directory and gives it a title page, then joins them all together, so I end up with a book that has chapters named according to the folder the recipes were in. Not bad, but a couple of things kapt me unsatisfied. First, where a recipe is short, another recipe would get tacked onto the bottom, whereas really I would have liked a page break after each recipe. Second, the table of contents appears for each chapter, whereas I would have liked one table of contents.

Pandoc output pdf recipe

So for a long time this little project sat at the bottom of my to do list, waiting for a better option to come along. That's when I found out about gitbook.

I actually found out about AsciiDoc first, a friend showed me how they had been using AsciiDoc to make manuals for some software they had been writing, and was due to be distributed around their department in a few weeks. But I found that AsciiDoc works much better with the AsciiDoc markup language, whereas I already had all my recipes written in markdown, so I did some googling and quickly came up with gitbook, which seems to be built with markdown and git control in mind. It actually reminded me a lot of Jekyll in the way it works, which I use to make websites, so it was a good fit.

The first thing I needed to do was install gitbook on the command line:

npm install gitbook-cli -g

Then because I already have all my markdown files. All I needed to do was make a SUMMARY.md in the root directory, then build the book. But building a SUMMARY.md isn't trivial, and in fact can be very tedious.So I installed another npm package to help with that:

npm install

Then to generate the SUMMARY.md I can type:

book sm

A SUMMARY.md looks like this:


    * [Brown Loaf](Bread/Brown_Loaf.md)
    * [Ciabatta](Bread/Ciabatta.md)
    * [Olive Rosemary Foccacia](Bread/Olive_Rosemary_Foccacia.md)
    * [Rosemary Sweet Potato Rolls](Bread/Rosemary_Sweet_Potato_Rolls.md)
    * [Stuffing Rolls](Bread/Stuffing_Rolls.md)
    * [Sweet Potato Crescent Rolls](Bread/Sweet_Potato_Crescent_Rolls.md)

    * [Baked Pumpkin With Apple](Dessert/Baked_pumpkin_with_apple.md)
    * [Chia Seed Chocolate Pudding](Dessert/Chia_Seed_Chocolate_Pudding.md)

With the displayed name of the recipe (chapter) in square brackets, with the actual filepath next to it in curved brackets. By default, each chapter takes its name from the # HEADER at the top of each .md file, but can be changed manually by editing SUMMARY.md. The sections are bullet points above the chapters. README.md is the file which is displayed when you first navigate to the root of the compiled book, so can contain a description of the book, acknowledgements etc.

Now the book can be built:

gitbook build

You can navigate to the locally hosted root of the book by going to:

http://localhost:4000

Gitbook.com](http://www.gitbook.com[2]) offers a fairly decent option for hosting your gitbook for free, and if you already have a Github account you can upload the gitbook as a git repo to Github, and then link that Github repo to Gitbook.com, for continuous deployment, with a URL that you can share with others. [Here is my Gitbook of recipes

2: http://www.gitbook.com

Gitbook recipe book