bitemark 0.2.0

Reference implementation for `BiteMark` - a markup language for recipes based on Markdown.

BiteMark

Reference implementation for BiteMark - a markup language for recipes based on Markdown.

Why

I was looking for a uniform way to store my collected recipes in digital form. Since I've already stored my notes in Markdown format for many years, it seemed like a reasonable choice for recipes too:

1. It's human-readable - so are recipes!
2. It's structured - so are recipes!
3. It's easily extensible
4. It's straightforward to format text and lists

Why Not JSON-LD?

Many websites expose recipe metadata in JSON-LD format which is great for extracting the data, but while this is technically human-readable, it's not a great experience.

Specification

Recipe Structure

# <Recipe title>

## Ingredients

- <quantity> <unit> <ingredient>
- <quantity> <unit> <ingredient>

## Instructions

1. Step 1
2. Step 2

E.g. a very simple recipe could look like this:

# Spaghetti Carbonara

## Ingredients

- 200 g spaghetti
- 100 g pancetta

## Instructions

1. Boil pasta.
2. Fry pancetta.

Units

In order to facilitate unit conversion, units are sorted into two categories:

1. Volume
2. Mass

• Volume:
  • ml
  • liter / l
  • cup_us - American cup
  • cup_uk - UK cup
  • cup - Defaults to American cup
  • tablespoon / tbsp
  • teaspoon / tsp
  • pint
• Mass:
  • g / gram
  • kg / kilogram
  • oz / ounce
  • lb / pound

Non-liquid units can be converted between volume and mass based on a density table.

Multiple Recipes

• A Markdown file may contain multiple recipes, each beginning with a Markdown header (# or ##).

Metadata (Optional)

Metadata can be placed at the top of the recipe inside an HTML comment block. This is so the metadata won't be rendered. This little syntactic trick is necessary because, sadly, Markdown does not support comments directly.

Here is an example for common metadata:

<!--
servings: 4
cuisine: Italian
units: metric
-->

There are no formal restrictions on which keys can be used in metadata.

However, some keys have special meaning in the reference implementation:

• servings: Used as the baseline for ingredient scaling when -s / --servings is used.
• units: Used as the default unit system for display and conversion (metric, american, british) when no CLI unit override is passed.

If servings is missing or invalid, scaling falls back to a baseline of 2 servings.

CLI Usage

Run the interpreter with:

bitemark [-u UNIT|--unit UNIT] [-s SERVINGS|--servings SERVINGS] <markdown_file>

Options:

• -u, --unit: Override display unit system (for example metric, american, or british).
• -s, --servings: Scale ingredient quantities to the requested servings.

Examples:

bitemark examples/recipes/milk.md
bitemark -s 6 examples/recipes/milk.md
bitemark --unit american --servings 2 examples/recipes/milk.md

Scaling uses metadata servings as the baseline when present.

Goals of the Default Implementation

1. Implement specification as completely as possible
2. Provide test cases to test interpreter against
3. Act as testbed for changes to the BiteMark spec
4. Avoid dependencies outside the Python Standard Library