Recipe Substitution Suggester Overlay

WHAT IT DOES

Recipe Substitution Suggester Overlay automatically scans recipe pages for ingredients and displays a comprehensive list of substitution options for each one. Whether you're out of an ingredient, cooking for someone with dietary restrictions, or simply want a healthier alternative, this tool provides instant suggestions. The built-in database covers over 200 common ingredients including dairy products (milk, butter, cheese, yogurt), eggs, flours, sweeteners, oils, meats, seafood, spices, herbs, vegetables, and baking ingredients. Each substitution includes a confidence rating (best, good, or ok) and relevant dietary tags like vegan, gluten-free, dairy-free, egg-free, or nut-free. You can filter suggestions by dietary preference to instantly see only the options that work for your needs. Click any ingredient to expand and view its substitutions, and copy the entire list for meal planning or grocery shopping.

WHERE IT RUNS

This script runs on any website that contains recipe content—food blogs, recipe aggregators, cooking sites, meal planning platforms, and social media recipe posts. It operates entirely within your browser tab, reading the page's DOM and structured data to find ingredient lists. The script cannot access other tabs, your browsing history, bookmarks, downloads, or any data outside the current page. All settings are stored locally using GM_setValue and never transmitted anywhere.

HOW TO USE

After installing with the BotGentz extension, the script automatically detects when you're on a recipe page. Click "Find Substitutions" to extract ingredients and see suggestions for each one. Each ingredient appears with a count of available substitution options—click on any ingredient to expand and view the full list. Substitutions are color-coded by confidence: green dots for best matches, yellow for good alternatives. Dietary tags appear alongside each suggestion. Use the dropdown menu to filter by dietary preference (vegan, gluten-free, dairy-free, egg-free, nut-free) and the confidence selector to show only best matches or all options. Copy the entire substitution list to your clipboard with one click for reference while shopping or cooking.

THE REAL MECHANISM

The script uses a three-layer extraction pipeline to find ingredients regardless of page structure. First, it scans all JSON-LD script blocks, recursively traversing the JSON object graph to find Schema.org Recipe nodes and extract their recipeIngredient arrays. Second, it falls back to microdata by querying elements with itemscope and itemtype containing "Recipe". Third, if no structured data exists, it scans visible text for common ingredient patterns. Once ingredients are collected, the script normalizes each ingredient name by removing quantities, units, and pluralization. It then queries a built-in substitution database organized as a key-value dictionary mapping ingredient names to arrays of substitution objects. Each substitution object contains the replacement text, confidence level, and dietary tag array. The database uses fuzzy matching—if an exact match isn't found, the script checks if any database key is contained within the ingredient name or vice versa, providing relevant suggestions even for slightly different ingredient names. Results are filtered by the user's dietary preference and confidence threshold, then rendered as a clean, interactive DOM list with no innerHTML from untrusted data.

THE PANEL

The Substitution Suggester panel is a BGPanel component that you can drag anywhere on your screen by its header. It snaps to the nearest edge when released, keeping your workspace organized. The panel collapses to a small bubble showing only the emoji icon when minimised—click to expand it again. You can resize the panel horizontally to see more substitution options. Press the Escape key to collapse the panel instantly. Your panel position and size are saved per-site, so it remembers where you like it on your favorite recipe sites.

PLEASE NOTE

This script requires the free BotGentz browser extension to function. The substitution database includes over 200 common ingredients and their alternatives, but it cannot cover every possible substitution. Some substitutions may vary based on the specific recipe context (baking vs. cooking, sweet vs. savory). Use suggestions as a guide and adjust quantities as needed. The script never reads or writes password fields, hidden inputs, or file inputs. It stores only your dietary preference, confidence threshold, and auto-show setting locally. No recipe data, ingredient lists, or substitution preferences are ever collected, transmitted, or shared.