<p>

<a href="https://github.com/xcapaldi/recipemd-go/releases"><img src="https://img.shields.io/github/release/xcapaldi/recipemd-go.svg" alt="Latest Release"></a>

<a href="https://pkg.go.dev/xcapaldi/recipemd-go?tab=doc"><img src="https://godoc.org/xcapaldi/recipemd-go?status.svg" alt="GoDoc"></a>

</p>

A Go library for parsing, scaling, and rendering recipes in the [RecipeMD](https://recipemd.org) format.

This format builds on top of structured Markdown such that both humans and programs can digest it.

*Go, parser, RecipeMD, Markdown*

**1 Go module**

- *1 pkg* `github.com/xcapaldi/recipemd-go`

- *1 pkg* `github.com/yuin/goldmark` Markdown parser

- *1* `parse` — parse a recipe and output JSON

- *1* `scale` — scale a recipe by factor or target yield

- *1* `flatten` — inline all linked sub-recipe ingredients

- *1* `renderhtml` — render a recipe as an HTML `<article>`

go get github.com/xcapaldi/recipemd-go

[RecipeMD](https://recipemd.org/specification.html) is a Markdown-based format for writing recipes.

A recipe file is plain Markdown with a defined structure:

A classic Roman pasta.

*Italian, pasta*

**2 servings**

- *200 g* spaghetti

- *100 g* guanciale

- *2* eggs

- *50 g* Pecorino Romano

- *1 tbsp* black pepper, coarsely ground

Boil pasta. Render guanciale. Whisk eggs with cheese and pepper.

Toss together off the heat.

The document has three sections divided by `---` thematic breaks:

| Section | Content |

|---|---|

| Preamble | H1 title, optional description, optional *tags* (italic), optional **yields** (bold) |

| Ingredients | Unordered lists; H2+ headings introduce named ingredient groups |

| Instructions | Free-form Markdown text |

Amounts are wrapped in emphasis: `*2 tbsp*`. Supported number formats:

integers (`3`), decimals (`1.5`), fractions (`1/2`), improper fractions

(`1 1/2`), and Unicode vulgar fractions (`½ ¼ ¾`).

Shockingly there are multiple competing specifications in the world of plaintext cooking:

- [Open Recipe Format](https://open-recipe-format.readthedocs.io/en/latest/) -- YAML

- [hrecipe](https://microformats.org/wiki/hrecipe) -- XML

- [schema.org Recipe](https://schema.org/Recipe)

- [Cooklang](https://cooklang.org) -- DSL

Of the above, the only one that goes beyond a strictly formatted schema is Cooklang.

It is an extensive project with a CLI, web server and thoughtful features like inline ingredent declarations (these are extracted at render time).

Despite this, it lacks one fundamental advantage working in plain text -- it's not very readable in it's raw format.

This may seem like a minor inconvenience but it makes reading and writing recipes less accessible to humans and (increasingly important) AI agents.

The beauty of RecipeMD is that it's a ruleset on standard Markdown syntax with all of that format's inherent flexibility (images/tables/etc).

The nature of Cooklang's strict DSL enables some advanced features but I believe they can be acheived in RecipeMD through contextual analysis.

As an example working in the raw formats, here is a moderately complex recipe in both:

Tender charred chicken in a rich, spiced tomato-cream sauce.

*Indian, chicken, curry*

**4 servings**

- *700 g* boneless chicken thighs, cut into chunks

- *150 g* plain yogurt

- *2 tbsp* lemon juice

- *3 cloves* garlic, minced

- *1 tsp* fresh ginger, grated

- *1 tsp* garam masala

- *1 tsp* cumin

- *1/2 tsp* turmeric

- *1/2 tsp* cayenne pepper

- *1 tsp* salt

- *2 tbsp* ghee

- *1* large onion, finely diced

- *4 cloves* garlic, minced

- *1 tbsp* fresh ginger, grated

- *1 tbsp* garam masala

- *1 tsp* cumin

- *1 tsp* coriander

- *1/2 tsp* turmeric

- *1/2 tsp* cayenne pepper

- *400 g* canned crushed tomatoes

- *200 ml* heavy cream

- *1 tsp* salt

- *300 g* basmati rice

- *1* handful fresh cilantro, roughly chopped

Combine chicken with all marinade ingredients in a bowl. Cover and refrigerate for at least 1 hour, ideally overnight.

Preheat a broiler or grill to high. Thread chicken onto skewers and cook for 10–12 minutes, turning once, until charred in spots and just cooked through. Set aside.

Cook rice according to package directions.

Heat ghee in a large saucepan over medium heat. Add onion and cook for 8–10 minutes until deep golden. Add garlic and ginger; cook 2 minutes until fragrant.

Stir in garam masala, cumin, coriander, turmeric, and cayenne. Toast 1 minute. Add crushed tomatoes and simmer uncovered for 15 minutes, stirring occasionally, until sauce thickens.

Pour in cream and stir to combine. Add the grilled chicken and simmer 5 minutes to meld flavors. Season with salt.

Serve over rice, garnished with fresh cilantro.

`Parse` accepts any `io.Reader`:

import recipemd "github.com/xcapaldi/recipemd-go"

p := recipemd.NewParser()

f, _ := os.Open("carbonara.md")

defer f.Close()

recipe, err := p.Parse(f)

if err != nil {

log.Fatal(err)

}

fmt.Println(recipe.Title) // "Carbonara"

fmt.Println(recipe.Tags) // ["Italian", "pasta"]

fmt.Println(recipe.Yields) // [{Factor:2 Unit:"servings"}]

Parse collects all structural and value-level problems via `errors.Join`,

so a single call surfaces every issue at once. Individual errors carry line

and column information:

if parseError, ok := errors.AsType[*recipemd.ParseError](err); ok {

fmt.Printf("line %d, col %d: %s\n", parseError.Line, parseError.Column, parseError.Message)

}

While not part of the official spec, this implementation supports some parser options to make the format more ergonomic.

In particular `WithFrontmatter` will strip YAML/TOML frontmatter before parsing the remaining content as spec-complient RecipeMD.

This is particularly useful if you combine this format with another note management system (like [Denote](https://protesilaos.com/emacs/denote)) that relies on frontmatter.

In addition `WithGithubFormattedMarkdown` enables support for GFM features like tables, autolinks, task lists (in ingredients as well) and strikethrough.

parser := recipemd.NewParser(

recipemd.WithFrontmatter(), // strip YAML/TOML front matter

recipemd.WithGithubFormattedMarkdown(), // enable GFM (tables, task lists, …)

)

recipe.Scale(2)

desired, _ := recipemd.ParseAmountString("6 servings")

if err := recipe.ScaleForYield(desired); err != nil {

log.Fatal(err)

}

fmt.Print(p.RenderMarkdown(recipe, 2))

data, err := p.RenderJSON(recipe)

fmt.Println(p.RenderHTML(recipe, 3))

The `examples/` directory contains small, self-contained programs that

demonstrate common use cases:

| Example | Description |

|---|---|

| [`examples/parse`](examples/parse) | Parse a recipe and write compact JSON to stdout |

| [`examples/scale`](examples/scale) | Scale a recipe by factor or target yield, write RecipeMD to stdout |

| [`examples/flatten`](examples/flatten) | Inline all linked sub-recipes, write RecipeMD to stdout |

| [`examples/renderhtml`](examples/renderhtml) | Flatten and render as an HTML `<article>` |

Run any example directly:

go run ./examples/parse carbonara.md

go run ./examples/scale carbonara.md "4 servings"

go run ./examples/flatten main_dish.md

go run ./examples/renderhtml carbonara.md

go test ./...

The suite includes the [RecipeMD canonical test suite](https://github.com/tstehr/RecipeMD/tree/master/test),

extensive golden tests and unit tests.

This library is quite performant compared to the reference implementation but not due to any clever optimizations.

Go is simply much faster and this translates directly.

In practice, the difference should be almost unnoticeable for any level of personal use.

Nevertheless, here is a very crude benchmark parsing and scaling a short recipe:

| Implementation | Command | Runs | Total | Avg/run | Speedup |

|----------------|---------|-----:|------:|--------:|--------:|

| Python recipemd 5.0.0 | `recipemd -y "10 ml" testdata/canonical/recipe.md` | 100 | 13,956 ms | 139.5 ms | 1x |

| Go (examples/scale) | `scale testdata/canonical/recipe.md "10 ml"` | 100 | 434 ms | 4.3 ms | **32x** |

MIT — see [LICENSE](LICENSE).