Metadata-Version: 2.4
Name: bitemark
Version: 0.2.0
Summary: Reference implementation for `BiteMark` - a markup language for recipes based on Markdown.
Project-URL: Documentation, https://github.com/t4k1t/bitemark#readme
Project-URL: Issues, https://github.com/t4k1t/bitemark/issues
Project-URL: Source, https://github.com/t4k1t/bitemark
Author-email: Thomas Kager <t4k1t+dev@protonmail.com>
License-Expression: MIT
License-File: LICENSE.txt
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# BiteMark

[![PyPI - Version](https://img.shields.io/pypi/v/bitemark.svg)](https://pypi.org/project/bitemark)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/bitemark.svg)](https://pypi.org/project/bitemark)
[![codecov](https://codecov.io/gh/t4k1t/bitemark/graph/badge.svg?token=Y5D4KX42LL)](https://codecov.io/gh/t4k1t/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

```markdown
# <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:
```markdown
# 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:
  ```markdown
  <!--
  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:

```bash
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:

```bash
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
