PyCook is a simple tool for turning a Git repo of recipes into a cookbook. The primary design requirements for PyCook are:

  1. A simple human-writable file format

  2. Recipes organized as individual files in a Git repo

  3. A simple tool to convert to a web page and print formats

  4. That tool should be able to produce 4x6 cards

Cookbook format

The cookbook is built around a Git repo of YAML files which looks something like this:

 |- cookbook.yaml
 |- breakfast
 |   |- index.yaml
 |   |- buttermilk-pancakes.yaml
 |   |- waffles.yaml
 |   |  ...
 |- deserts
 |   |- index.yaml
 |   |- fudge-brownies.yaml
 |   |- hacker-cookies.yaml
 |   |  ...
 | ...

The cookbook.yaml file contains a few basic things for the cookbook as a whole:

name: Ekstrand Family Recipes
author: Jason Ekstrand

In each sub-directory is an index.yaml file which contains the full name of that category of recipes

name: Breakfast

All the other YAML files are actual recipes:

name: Swedish Meatballs
from: Grandma Ekstrand

  - 1 [lb] Ground beef (80%)
  - 1/4 [lb] Ground pork
  - 1 [tsp] Salt
  - 1 [tsp] Sugar
  - 1 Egg, beaten
  - 1 [tbsp] Catsup
  - 1 Onion, grated
  - 1 [cup] Bread crumbs
  - 1 [cup] Milk

  - Soak crumbs in milk

  - Mix all together well

  - Make into 1/2 -- 3/4 [in] balls and brown in a pan on the stove
    (you don't need to cook them through; just brown)

  - Heat in a casarole dish in the oven until cooked through.

The one bit of smarts it does have is around quantities and units. One thing that constantly annoys me with recipes is the inconsistency with abbreviations of units. Take tablespoons, for instance. I’ve seen it abbreviated “T” (as opposed to “t” for teaspoon), “tbsp”, or “tblsp”, sometimes with a “.” after the abbreviation and sometimes not. To handle this, I have a tiny macro language where units have standard abbreviations and are placed in brackets. This is then substituted with the correct abbreviation to let me change them all in one go if I ever want to. It’s also capable of handling plurals properly so when you type [cup] it will turn into either “cup” or “cups” depending on the associated number. It also has smarts to detect “1/4” and turn that into vulgar fraction character “¼” for HTML output or a nice LaTeX fraction when doing PDF output.


PyCook is currently able to output three formats:

  1. An HTML website generated using Sphinx which is searchable and has a nice table of contents.

  2. An 8.5x11 PDF cookbook generated using LaTeX. As with most LaTeX documents, the table of contents is properly hyperlinked.

  3. 4x6 index cards for use when actually in the kitchen. It can generate either a stand-alone PDF of 4x6 pages or an 8.5x11 PDF sutable for double-sided printing onto Avery 5389 templates.