How to Search Recipes by Difficulty in the HowToCook Repository

You can search recipes by difficulty in HowToCook either by browsing the auto-generated starsystem/ index files (e.g., 2Star.md) or by running a grep search for the 预估烹饪难度 marker in the raw markdown files.

The HowToCook project uses a star-based difficulty system to help cooks find recipes matching their skill level. Each recipe file contains a difficulty rating line that the build system parses to generate searchable indexes. Whether you prefer browsing static lists or querying the source directly, the repository provides deterministic ways to search recipes by difficulty using the embedded star ratings.

Understanding the Star-Based Difficulty System

Every recipe in the dishes/ directory includes a metadata line indicating its complexity:

预估烹饪难度：★★

The difficulty ranges from 0 stars (simple assembly) to 8 stars (professional techniques), with each ★ character representing one level. The build script .github/readme-generate.js uses the countStars helper function (lines 65-72) to tally these symbols deterministically across all markdown files.

Method 1: Browse the Auto-Generated Star Index Files

The simplest way to find recipes by difficulty is to open the pre-built index files in the starsystem/ directory. The organizeByStars function (lines 75-119) in the build script generates these files automatically during the CI process.

Each file follows the naming pattern <n>Star.md and contains a bulleted list of all recipes with that difficulty:

# 2 星难度菜品

- [炒青菜](../dishes/vegetable_dish/炒青菜.md)
- [鸡蛋羹](../dishes/vegetable_dish/鸡蛋羹/鸡蛋羹.md)

To browse 3-star recipes, navigate to starsystem/3Star.md in the repository. These files are regenerated automatically via the CI workflow defined in .github/workflows/ci.yml whenever the repository is built.

Method 2: Search Raw Markdown Files with Grep

For programmatic access or live searches against the source, use grep to target the 预估烹饪难度 line directly. This method works on the raw repository without requiring a build step.

Search for exactly 2-star recipes:

grep -R "预估烹饪难度：★★$" dishes/ | cut -d: -f1

Search for 3-star recipes using regex quantifiers:

grep -R "预估烹饪难度：★\{3\}" dishes/ | cut -d: -f1

This approach returns the file paths of all matching recipes, which you can then open or process further in scripts.

Programmatic Access with Node.js

You can replicate the repository's own logic in a Node.js script to list recipes by difficulty. This implementation mirrors the countStars logic from .github/readme-generate.js:

const fs = require('fs/promises');
const path = require('path');

async function listByStars(starCount) {
  const files = await fs.readdir('dishes', { recursive: true, withFileTypes: true });
  
  for (const file of files) {
    if (!file.isFile() || !file.name.endsWith('.md')) continue;
    
    const fullPath = path.join('dishes', file.path, file.name);
    const content = await fs.readFile(fullPath, 'utf-8');
    
    // Count star symbols exactly as the build script does
    const stars = (content.match(/★/g) || []).length;
    
    if (stars === starCount) {
      console.log(`${stars}★ – ${fullPath}`);
    }
  }
}

// Example: list all 4-star recipes
listByStars(4);

This script traverses the dishes/ directory, counts ★ characters in each file, and outputs paths matching your target difficulty.

Summary

• HowToCook uses a star rating system (0-8 ★) embedded in each recipe's markdown as 预估烹饪难度：★★.
• The star index files in starsystem/<n>Star.md provide a human-readable, browsable list of recipes by difficulty, regenerated automatically by .github/readme-generate.js.
• Grep searches against the raw dishes/ directory allow programmatic discovery without building the repository.
• The countStars function in the build script provides a deterministic, regex-based counting method you can replicate in your own tools.

Frequently Asked Questions

How does the HowToCook repository determine a recipe's difficulty rating?

The difficulty is determined by the number of ★ (star) characters appearing in the line 预估烹饪难度：★★ within each markdown file. The build script's countStars helper uses a simple regex match to count these symbols, allowing ratings from 0 to 8 stars based on cooking complexity and technique requirements.

Can I search for recipes by difficulty without cloning the repository?

Yes. You can browse the auto-generated index files directly on GitHub by navigating to starsystem/1Star.md, starsystem/2Star.md, etc., in the repository web interface. Alternatively, use GitHub's search bar with the query 预估烹饪难度：★★ path:dishes to find files containing specific difficulty ratings without downloading the codebase.

Why are there separate markdown files for each difficulty level in the starsystem folder?

These files serve as static indexes that improve repository navigation and SEO. The organizeByStars function in .github/readme-generate.js creates them during the build process to provide a stable, human-readable reference that works offline and loads faster than dynamic searches. They also integrate with the main README.md, which links to these indexes under the "按难度索引" section.

How do I find recipes with zero stars (simplest difficulty) versus high difficulty?

For zero-star recipes, open starsystem/0Star.md, which lists dishes requiring minimal or no cooking. For high-difficulty recipes (7-8 stars), navigate to starsystem/7Star.md or starsystem/8Star.md. You can also use the Node.js script provided above, changing listByStars(0) or listByStars(8) to target the extremes of the difficulty spectrum.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}