How to Contribute to HowToCook: A Complete Guide to the Contribution Workflow

The HowToCook contribution workflow involves forking the repository, creating a new branch, adding or editing Markdown recipe files using the provided template, running automated linters, and submitting a Pull Request for maintainer review.

The HowToCook repository by Anduin2017 is a community-driven cookbook where contributors share cooking instructions through structured Markdown files. Understanding the contribution workflow is essential for anyone looking to add new dishes or improve existing recipes, as the project maintains strict formatting standards enforced through automated linting.

Prerequisites and Initial Setup

Forking and Cloning the Repository

Begin by creating your own copy of the repository and downloading it locally.

1. Fork the repository on GitHub to create your own copy under your account.

2. Clone your fork locally using the command:

   git clone https://github.com/<your-username>/HowToCook.git

3. Navigate to the project directory:

   cd HowToCook

Creating and Editing Recipe Content

Using the Official Template

All new recipes must follow the standardized structure defined in the official template located at dishes/template/示例菜/示例菜.md.

Copy the template file to your new recipe location and remove all comment blocks before filling in the required sections:

• Title – The dish name with difficulty rating (e.g., "预估烹饪难度：★★★")
• Ingredients and Tools – Exact measurements and required equipment
• Calculations – Mathematical formulas for ingredient scaling (if applicable)
• Step-by-Step Operations – Numbered or bulleted cooking instructions

File Organization and Naming Conventions

Place your completed Markdown file in the appropriate subdirectory under dishes/:

• dishes/breakfast/ – Morning meals
• dishes/staple/ – Rice, noodles, and staple foods
• dishes/meat_dish/ – Meat-based entrees
• dishes/vegetable_dish/ – Vegetable preparations

Name files using descriptive Chinese characters with the .md extension (e.g., 麻油拌面.md).

Validating Your Contribution with Linters

Before submitting, ensure your Markdown complies with the project's style rules by running the automated linters.

Execute the linting command:

npm run lint

The project uses two configuration files to enforce standards:

• .markdownlint.json – Validates Markdown syntax, heading spacing, and list formatting
• .textlintrc – Checks text content for style consistency

Fix any reported errors, paying special attention to:

• One blank line required between headings and body text
• Consistent list indentation
• Proper use of Chinese punctuation marks

Submitting Your Changes

Committing and Pushing

Once your recipe passes linting, commit your changes with a descriptive message:

git add dishes/staple/麻油拌面.md
git commit -m "Add recipe for sesame oil noodles"
git push origin add-spicy-noodles

Opening a Pull Request

Navigate to the original Anduin2017/HowToCook repository on GitHub and open a Pull Request (PR) against the master branch.

The maintainers will review your submission for:

• Compliance with the template structure
• Accuracy of cooking instructions
• Proper linting and formatting
• Adherence to the CODE_OF_CONDUCT.md

If adjustments are needed, maintainers will request changes through the PR review interface. Once approved, your recipe will be merged and published to the official cookbook.

Summary

• The contribution workflow centers on Markdown files in the dishes/ directory, requiring no coding knowledge beyond Git basics.
• Always start from the template at dishes/template/示例菜/示例菜.md and remove all comments before submission.
• Run npm run lint before committing to ensure compliance with .markdownlint.json and .textlintrc rules.
• Submit changes via Pull Request to the master branch after reading CODE_OF_CONDUCT.md.

Frequently Asked Questions

Do I need to know how to code to contribute to HowToCook?

No programming knowledge is required. The contribution workflow uses only Markdown text formatting and basic Git commands. You write cooking instructions in plain text following the provided template, and automated linters check your formatting rather than code syntax.

What happens if my recipe fails the linter checks?

If npm run lint reports errors, your Pull Request will likely receive a request for changes from maintainers. Common issues include missing blank lines after headings, inconsistent list formatting, or improper punctuation. Fix the errors locally, commit the changes, and push to update your existing PR.

Can I modify existing recipes, or only add new ones?

Both actions are welcome in the contribution workflow. You can edit existing Markdown files in the dishes/ directory to correct errors, improve clarity, or update measurements, or you can create new files following the template structure. All changes follow the same fork-branch-PR process.

Where can I find the contribution guidelines document?

The official contribution guidelines are located in CONTRIBUTING.md at the repository root. Additionally, the CODE_OF_CONDUCT.md file outlines behavioral expectations for community interaction. Both documents should be reviewed before starting the contribution workflow.

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