Obsidian-Grocy-Bridge/README.md

🛒 Grocy Shopping List Bridge

Send ingredients from your Obsidian recipe notes straight into your Grocy shopping list.
Works seamlessly with other recipe plugins — supports fuzzy product matching, auto-matching with thresholds, free-text items, and manual overrides.

---

🚀 Quick Start

1. Install: Copy this plugin into .obsidian/plugins/grocy-shoppinglist-bridge/ and enable it in Obsidian.
2. Configure: In plugin settings, set your Grocy URL and API Key.
3. Use: Open a recipe note → click the 🛒 ribbon button → ingredients appear in your Grocy shopping list.

---

✨ Features

• Parse ## Ingredients sections automatically (supports nested subheadings like ### Sauce, #### Marinade).
• Smart ingredient normalization:
  • 1 large egg → eggs
  • 3 cloves garlic (minced) → garlic
• Fuzzy matching against Grocy's products with adjustable confidence.
• Multiple fallback strategies when no match is found.
• Manual overrides via inline annotations (grocy_id, grocy:).
• Ribbon button + command palette support.
• Works out-of-the-box with Recipe Grabber.
  Imported recipes are parsed automatically.
• Plays nicely with Recipe View.
  If you use the HTML comment syntax (<!-- grocy_id: … -->), Recipe View will hide the annotation from the rendered card.

---

📥 Installation

1. Download the repo.
2. Copy into your vault:

   .obsidian/plugins/grocy-shoppinglist-bridge/
   

3. Reload community plugins in Obsidian.
4. Enable Grocy Shopping List Bridge.

---

📑 Usage

Recipe note example

## Ingredients
- 1 large egg
- 3 cloves garlic (minced)
- 1 broccoli crown

### Sauce
- 2 tbsp soy sauce
- 1 tsp sesame oil

## Directions
Mix and cook...

• Click the 🛒 ribbon button or run:

  Grocy: Add ingredients to shopping list
  

• All bullet points under Ingredients (and its subheadings) are added.
• Stops before the next top-level section (e.g. ## Directions).

---

⚙️ Settings

Setting	Description
Grocy URL	Base URL of your Grocy (e.g. http://localhost/grocy or https://your-domain/grocy)
API Key	Create in Grocy → Settings → Manage API keys
Shopping List ID	Usually 1 unless you have multiple lists
Auto-confirm unique match	If only one candidate matches, add automatically
Auto-match threshold	Default 6 — top candidate score required for auto-add
Require score margin	Default 2 — top candidate must be this many points above runner-up
Debug matching	Log candidate scores & decisions to Obsidian console
No-match fallback	What to do when no good product is found: • Ask (chooser + free-text option) • Prompt free-text (type a note) • Free-text (auto-add note) • Skip

---

🖊️ Forcing Matches (Annotations)

If you want exact control over which Grocy product is used:

By Grocy ID

- 2 tomatoes (grocy_id: 42)

Or with an HTML comment (hidden in Recipe View):

- 2 tomatoes <!-- grocy_id: 42 -->

⚠️ Recipe View will display clean ingredients without showing the grocy_id comment, if using the HTML notation.

By Product Name

- 1 chili pepper (grocy: jalapeño)

This forces the matcher to look for “jalapeño” specifically.

---

🚀 Example Workflows

Fully Automated

• Auto-confirm unique = ✅
• Threshold = 6, Margin = 2
• Fallback = Free-text

→ Most items auto-add. Unmatched lines go in as notes.

---

Semi-Automated

• Auto-confirm unique = ✅
• Fallback = Ask

→ Confident matches auto-add, ambiguous ones ask you.

---

Manual Control

• Auto-confirm unique = ❌
• Fallback = Ask

→ You confirm every item via chooser.

---

🔍 Debugging

• Enable Debug matching in settings.
• Open View → Toggle Developer Tools → Console in Obsidian.
• You'll see logs like:

  Match: 1 large egg → needle: eggs
  top: {id:12, name:"Eggs", score:11}
  Auto-matched → Eggs