HowToCook: A Programmer's Structured Recipe Book for Home Cooking
Programmer's guide about how to cook at home.
At a glance
- What is it?
- HowToCook is a community-driven, Markdown-based cookbook that applies formal language principles to home cooking, offering structured recipes and a Docker-based viewer. It is a practical resource for programmers who want precise, unambiguous cooking instructions.
- Who is it for?
- Adopt HowToCook if you are a programmer who values precise, structured instructions and wants a community-maintained recipe collection that you can self-host. It is not for you if you prefer video tutorials, interactive cooking apps, or curated editorial content.
- Can I use it commercially?
- Yes. Unlicense is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- GitHub does not report a main language for this repository.
Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.
Star history
- Anduin2017/HowToCook103,939 ★ · +1,987
| Repository | 2026-08-24 | 2026-11-14 |
|---|---|---|
| Anduin2017/HowToCook | 102k | 103.9k |
1,987 Stars in the last 82 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The Problem: Ambiguous Recipes for Formal Minds
The scope is broad, covering vegetarian and meat dishes, plus technique guides for tools like pressure cookers, air fryers, and microwaves. The README lists dozens of dishes, from simple stir-fries to complex braises. This is not a minimal project; it has grown to include regional Chinese cuisines and even Indian and Pakistani recipes. The breadth suggests active community contribution. The project's homepage, howtocook.aiursoft.com, hosts a visual browser, but the repository itself is the source of truth.
How It Works: Markdown as a Recipe Specification Language
The project also includes a 'tips' directory with guides on kitchen setup, washing dishes, and choosing what to eat. These are not recipes but general knowledge, formatted as Markdown files. This adds a layer of practical advice beyond individual dishes. The README lists several, including food safety and techniques like blanching and stir-frying. This suggests the project aims to be a complete cooking reference, not just a collection of dishes.
Getting It Running: Docker and Local Setup
For contributors, the workflow is Git-based: fork the repository, edit or add a Markdown file following the template, and submit a pull request. The README says 'directly modify and submit a Pull request' for issues. The repository's package.json defines a lint script that chains textlint, markdownlint and a manual lint step, plus a build script, so recipe files do get automated checks.
Limitations: When HowToCook Is the Wrong Tool
The Docker viewer's default credentials are a security concern. The README openly lists the default username and password, which is fine for local use, but if someone deploys the container on a public server without changing them, the viewer could be compromised. The README does not mention how to change credentials or secure the deployment. This is a practical limitation for anyone considering self-hosting beyond their own machine.
Alternatives: How Other Projects Approach Structured Cooking
The key difference is the audience. HowToCook explicitly targets programmers who want formal, unambiguous instructions. Tandoor targets anyone who wants to organize their own recipes. HowToCook is a content project, not a software project in the traditional sense. The software part is minimal: the Docker viewer is a convenience. Tandoor is a software project with a database and APIs. This distinction matters when choosing: HowToCook gives you content, Tandoor gives you a tool.
Maintenance and License: Unlicense and Community Dynamics
Upgrading the Docker viewer is as simple as pulling the latest image. The 30-minute indexing time suggests the viewer caches data, so after an update, you may need to wait. This is a minor operational detail. Overall, the maintenance cost is low if you use the hosted site, and moderate if you self-host and want to keep the image updated.
Who Should Adopt It: A Concrete Judgement
If you do not read Chinese, or if you prefer video or interactive cooking guidance, this project is not for you. If you want a personal recipe manager with a database and UI, look elsewhere. HowToCook is a content repository, not a full application. Its value is in the structured text, not the software. For those who fit the profile, the first step is to browse the hosted site or clone the repository and read a few recipes to see if the format meets your needs. Check the template and a sample dish to understand the level of detail. Then decide if the community-driven quality is acceptable. The project is a niche tool, and it is honest about that.
Editorial conclusion
Adopt HowToCook if you are a programmer who values precise, structured instructions and wants a community-maintained recipe collection that you can self-host. It is not for you if you prefer video tutorials, interactive cooking apps, or curated editorial content. Before adopting, verify the recipe format matches your cooking style, check the Docker image's default credentials and index time, and review the contribution guide to see if you can commit to the template. The project's strength is its formal, template-driven approach, but its quality depends on community contributions, so inspect specific recipes for accuracy before trusting them.
Frequently asked questions
What is HowToCook?
HowToCook is a community cookbook of Chinese home cooking stored as Markdown files in a GitHub repository, written for readers who prefer explicit ingredients and steps over the free-form recipe posts found elsewhere. It is released under the Unlicense and browsable at howtocook.aiursoft.com.
How do I browse HowToCook recipes?
The project points readers at its website at https://howtocook.aiursoft.com/. To run the collection locally instead, install Docker, pull the aiursoft/howtocookviewer image and map port 5000 with docker run -d -p 5000:5000, after which indexing finishes automatically within 30 minutes of start.
How do I add a recipe to HowToCook?
Copy and edit the existing template at dishes/template/示例菜/示例菜.md, then open a pull request. The repository's npm lint script runs textlint with --fix, markdownlint across ./dishes and ./tips, and its own manuallint script, and the textlint step rewrites files in place.
What license is HowToCook released under?
The Unlicense, recorded both in the LICENSE file at the repository root and in the license field of package.json, where the package name is how-to-cook and the version is 1.6.0.
Official sources
Was this useful?