About Cooklang Federation

Step 1: Write Recipes in Cooklang Format

Create .cook files using the Cooklang markup language. Cooklang is a plain-text format that's both human-readable and machine-parseable.

Example recipe file (chocolate-cookies.cook):

---
servings: 24
time: 45 minutes
tags: dessert, cookies, baking
difficulty: easy
---

Preheat #oven to 180°C.

Cream @butter{200%g} and @sugar{150%g} together for ~{5%minutes} until fluffy.

Add @eggs{2} and @vanilla extract{1%tsp}, mix well.

In a separate bowl, combine @flour{300%g}, @baking soda{1%tsp}, and @salt{1/2%tsp}.

Gradually fold dry ingredients into wet mixture.

Stir in @chocolate chips{200%g}.

Drop spoonfuls onto greased #baking sheet.

Bake for ~{12-15%minutes} until golden brown.

Cool on #wire rack before serving.

Step 2: Generate an Atom/RSS Feed

Create a feed XML file that lists all your recipes with metadata. You can generate this manually or use the CLI tool.

Option A: Use the Federation CLI (Recommended)

# Generate feed from a directory of .cook files
cargo run -- publish --input ./my-recipes --output feed.xml

# This will scan all .cook files and create a properly formatted Atom feed

Option B: Create manually

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:cooklang="https://cooklang.org/feeds/1.0">

  <title>My Recipe Collection</title>
  <link href="https://example.com/feed.xml" rel="self"/>
  <link href="https://example.com/"/>
  <updated>2025-10-20T12:00:00Z</updated>
  <id>https://example.com/feed.xml</id>
  <author>
    <name>Your Name</name>
    <uri>https://example.com</uri>
  </author>

  <entry>
    <title>Chocolate Chip Cookies</title>
    <id>https://example.com/recipes/chocolate-cookies</id>
    <link href="https://example.com/recipes/chocolate-cookies" rel="alternate"/>
    <link href="https://example.com/recipes/chocolate-cookies.cook" rel="enclosure" type="text/plain"/>
    <updated>2025-10-20T12:00:00Z</updated>
    <summary>Classic chocolate chip cookies with a crispy edge and chewy center.</summary>

    <cooklang:recipe>
      <cooklang:servings>24</cooklang:servings>
      <cooklang:time total="45" units="minutes"/>
      <cooklang:tags>
        <cooklang:tag>dessert</cooklang:tag>
        <cooklang:tag>cookies</cooklang:tag>
        <cooklang:tag>baking</cooklang:tag>
      </cooklang:tags>
      <cooklang:difficulty>easy</cooklang:difficulty>
    </cooklang:recipe>
  </entry>

  <!-- Add more entries for each recipe -->
</feed>

Step 3: Host Your Files

Upload both your feed.xml and all .cook files to any static web hosting service. All files must be publicly accessible.

git init
git add feed.xml recipes/
git commit -m "Add recipes"
git push origin main
# Enable Pages in repo settings

# Create a directory structure:
/
  feed.xml
  recipes/
    cookies.cook
    pasta.cook
# Deploy via web UI or CLI

Requirements:

• Feed must be served over HTTPS (recommended for security)
• Files must be accessible without authentication
• Set Content-Type: application/atom+xml for feed.xml
• Set Content-Type: text/plain; charset=utf-8 for .cook files
• Enable CORS headers if you want to allow browser-based clients

Step 4: Register Your Feed with the Federation

Submit a pull request to add your feed to this federation instance. See the GitOps section above for the full process.

Quick summary:

1. Fork the federation repository
2. Add your feed URL to config/feeds.yaml:

   - url: https://example.com/feed.xml
     name: My Recipe Collection
     author: Your Name
     description: A collection of family recipes
     tags: [desserts, italian, vegetarian]

3. Commit and push your changes
4. Create a pull request with a description of your recipe collection
5. Wait for CI validation (checks feed accessibility and format)
6. Once approved and merged, the crawler will index your recipes within 24 hours

Step 5: Keep Your Feed Updated

The federation crawler checks feeds periodically (typically daily). To propagate updates:

• Add new recipes: Add entries to your feed and upload the new .cook files
• Update recipes: Modify the .cook file and update the entry's <updated> timestamp
• Remove recipes: Delete the entry from your feed (the .cook file can remain for archival)
• Always update the feed's root <updated> timestamp when making changes

Tip: The crawler uses conditional HTTP requests (ETags, Last-Modified headers) to efficiently detect changes. Make sure your hosting provider supports these headers for optimal performance.