# How the HowToCook markdownlint Configuration Works: A Complete Guide

> Learn how the HowToCook markdownlint configuration works. Discover how a custom .markdownlint.json file enables flexible formatting while enforcing consistency.

- Repository: [Anduin Xue/HowToCook](https://github.com/Anduin2017/HowToCook)
- Tags: deep-dive
- Published: 2026-02-27

---

**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](https://github.com/Anduin2017/HowToCook/blob/master/.markdownlint.json) contains a JSON object that explicitly disables six rules by setting their values to `false`:

```json
{
    "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](https://github.com/Anduin2017/HowToCook/blob/master/package.json) defines an npm script that runs **markdownlint-cli** against the content directories:

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

```

### Executing the Linter

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

```bash
npm run markdownlint

```

The CLI automatically detects [.markdownlint.json](https://github.com/Anduin2017/HowToCook/blob/master/.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:

```bash
npm run lint

```

This command executes **markdownlint** alongside **textlint** and the manual verification script located at [.github/manual_lint.js](https://github.com/Anduin2017/HowToCook/blob/master/.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:

```json
{
    "MD013": true
}

```

After modifying [.markdownlint.json](https://github.com/Anduin2017/HowToCook/blob/master/.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](https://github.com/Anduin2017/HowToCook/blob/master/.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](https://github.com/Anduin2017/HowToCook/blob/master/.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](https://github.com/Anduin2017/HowToCook/blob/master/.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."