recipe_grid.markdown: Markdown recipe compiler

Recipe Grid extends Markdown syntax to provide a convenient way of describing recipes within a document. See the Markdown Recipe Syntax Reference for an overview of these extensions.

A recipe markdown document is compiled using:

recipe_grid.markdown.compile_markdown(markdown_source: str) → MarkdownRecipe

Compile a recipe grid flavoured markdown document, producing a MarkdownRecipe which may be rescaled and rendered into the final HTML form as required.

Internally calls recipe_grid.compiler.compile() and so may throw the same kinds of exceptions when syntax errors in the recipe sources are encountered.

This produces a MarkdownRecipe object which in turn may be compiled into a final HTML form using its MarkdownRecipe.render() method.

class recipe_grid.markdown.MarkdownRecipe(html: str = '', title: str | None = None, servings: int | None = None, pre_title_placeholder: str | None = None, post_title_placeholder: str | None = None, scaled_value_strings: ~typing.MutableMapping[str, ~recipe_grid.scaled_value_string.ScaledValueString] = <factory>, recipe_placeholders: ~typing.MutableMapping[str, ~recipe_grid.recipe.Recipe] = <factory>)

The result of parsing a recipe grid markdown file.

Most users should refer directly to the render() method which will produce a complete HTML listing for the recipe, optionally after scaling by a given factor. Other metadata (e.g. title and servings) may also be useful for indexing purposes.

html: str = ''

The compiled HTML for the markdown document with placeholders for various recipe-related values.

Specifically the following placeholders should be replaced with suitable HTML to produce a useful web page:

  • The ScaledValueString objects in scaled_value_strings must be scaled, rendered and substituted for the placeholders given in that dictionary. These include places where the curly-bracket syntax has been used within a recipe, and the title itself when it contains a number of servings.

  • The recipes in recipe_placeholders must be scaled and rendered as HTML tables and inserted in place of the provided placeholders.

  • When given pre_title_placeholder and post_title_placeholder must be replaced with a suitable surroundings for the title-containing H1 tag. For example, a <header> tag and the addition of notes about how the recipe was scaled.

All of the above steps are automated by the render() method.

title: str | None = None

The title of the recipe (with the serving count and prepositions removed, if present).

For example, given the markdown title “# Spam for 2”, this field will become “Spam”.

If None, no (H1 level) title was given in the recipe.

servings: int | None = None

The number of servings this recipe is for, if known from the title.

post_title_placeholder: str | None = None

Strings which may be substituted with content to insert before and after the title-containing <h1>, if one was identified successfully.

scaled_value_strings: MutableMapping[str, ScaledValueString]

Scaled value strings to be substituted within the recipe text. A mapping from placeholder string to corresponding ScaledValueString.

recipe_placeholders: MutableMapping[str, Recipe]

Compiled recipes, one per recipe code block, alongside the placeholder string.

property recipes: List[List[Recipe]]

An convenience view of :py;attr:recipe_placeholders containing just the recipes without placeholder strings.

render(scale: int | float | Fraction = 1) → str

Render this recipe scaled by a given factor.

Note

Unfortunately, though internally Recipe Grid’s Markdown parser is built as a marko extension, due to limitations of the marko extension API, this extension is not readily composible with other extensions. As a result, this extension is not exposed as a public API.