How the HowToCook markdownlint Configuration Works: A Complete Guide

TLDR: The Anduin2017/HowToCook repository uses a custom .markdownlint.json file to disable six specific linting rules, allowing Chinese cooking instructions and flexible Markdown formatting while maintaining consistency across the dishes/ and tips/ directories.

The open-source cooking repository Anduin2017/HowToCook manages thousands of Markdown recipe files containing Chinese characters and culinary formatting. To maintain quality without restricting content flow, the project implements a specialized markdownlint configuration that relaxes standard rules incompatible with Chinese typography. This setup allows contributors to write naturally while automated checks catch critical syntax errors.

The .markdownlint.json Configuration Structure

Located at the repository root, .markdownlint.json contains a JSON object that explicitly disables six rules by setting their values to false:

{
    "MD036": false,
    "MD024": false,
    "MD004": false,
    "MD029": false,
    "MD013": false,
    "MD007": false
}

Setting a rule to false instructs markdownlint to skip validation for that specific constraint.

Disabled Rules and Their Purposes

The configuration disables rules that conflict with the repository's Chinese cookbook content:

• MD036 – Disallows no space after heading markers. Turning this off allows headings like #Title without requiring a space after the hash.

• MD024 – Disallows duplicate heading IDs. Disabled to accommodate Chinese headings that naturally repeat across different recipe files.

• MD004 – Enforces consistent heading style. Turned off so authors can mix ATX (# Heading) and setext (underlined) heading formats.

• MD029 – Enforces ordered list numbering. Disabled to permit non-sequential numbering in cooking steps.

• MD013 – Limits line length. Turned off because Chinese cooking instructions often contain long sentences that exceed standard 80-character limits.

• MD007 – Enforces unordered list indentation. Disabled to accept flexible indentation levels for ingredient lists and tips.

NPM Script Integration

The project's package.json defines an npm script that runs markdownlint-cli against the content directories:

{
    "scripts": {
        "markdownlint": "markdownlint ./dishes ./tips"
    }
}

Executing the Linter

To check all Markdown files in the dishes/ and tips/ directories, run:

npm run markdownlint

The CLI automatically detects .markdownlint.json in the repository root and applies the disabled rules.

The Full Lint Pipeline

The repository combines markdownlint with additional quality checks via the lint script:

npm run lint

This command executes markdownlint alongside textlint and the manual verification script located at .github/manual_lint.js. The manual script runs after automated linting to perform repository-specific validations that markdownlint does not cover.

Customizing the markdownlint Configuration

To enable a previously disabled rule, change its value to true or remove the entry entirely. For example, to re-enable the line-length limit:

{
    "MD013": true
}

After modifying .markdownlint.json, subsequent runs of npm run markdownlint will enforce the new constraints and report any violations, such as lines exceeding the default 80-character threshold.

Summary

• The .markdownlint.json file contains six explicitly disabled rules (MD036, MD024, MD004, MD029, MD013, MD007) tailored for Chinese cookbook content.
• The package.json script "markdownlint": "markdownlint ./dishes ./tips" targets recipe directories while ignoring other files.
• Running npm run markdownlint validates formatting, while npm run lint executes the full pipeline including textlint and .github/manual_lint.js.
• Rule modifications take effect immediately upon editing the JSON configuration file.

Frequently Asked Questions

Where is the markdownlint configuration file located in HowToCook?

The configuration file resides at .markdownlint.json in the repository root, where markdownlint-cli automatically detects it during execution.

Why does the repository disable the MD013 line length rule?

MD013 is disabled because Chinese cooking instructions frequently contain long descriptive sentences that exceed the standard 80-character limit, making strict enforcement impractical for recipe content.

How do I run markdownlint locally on the HowToCook repository?

Execute npm run markdownlint to check only Markdown files, or run npm run lint to execute the complete validation pipeline including textlint and manual checks defined in .github/manual_lint.js.

What happens if I enable MD024 (duplicate headings) in the configuration?

Enabling MD024 would cause markdownlint to flag duplicate heading IDs across the dishes/ and tips/ directories, generating errors for common Chinese headings that repeat naturally across different recipe files, such as "Ingredients" or "Instructions."

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