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.
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](
http://www.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
