TITLE: 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], 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.

  [gitbooks]: 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
    * 400 g brown flour
    * 100 g white bread flour
    * 7 g sachet of yeast
    * 1 tsp salt
    * 2.5 tsp olive oil
    * 300 ml warm water

    ## 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.

  {IMAGE}


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:

    * [Introduction](README.md)
    * Bread
        * [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)
    * Dessert
        * [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] 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].

  [Gitbook.com]: http://www.gitbook.com
  [Here is my Gitbook of recipes]: https://johngodlee.gitbooks.io/recipes/content/

  {IMAGE}