Automatic formatting step causes diff pollution in navigation file, which makes contributing difficult and error-prone

[tvenable-mie]

Description

The product documentation repository automatically runs prettier --write against every staged Markdown file during git commit.

This is installed through the npm prepare script and Husky. The pre-commit hook runs npx lint-staged, whose Markdown rule executes prettier --write.

Because Prettier operates on the entire file, a one-line change to a large generated document can become a whole-file formatting rewrite. lint-staged then stages those changes automatically, allowing them into the commit.

Reproduction

1. Run npm install or npm ci.
2. Make a one-line change to content/navigation.md.
3. Stage the file with git add content/navigation.md.
4. Run git commit.
5. Inspect the commit with git show --stat.

Observed Result

A one-line navigation addition produced:

2 files changed, 1751 insertions(+), 1643 deletions(-)
content/navigation.md | 3288 lines changed

The hook changed front-matter quoting, list markers, list indentation, and other formatting unrelated to the intended edit.

The hook output only reported that it was “Running tasks for staged files” and “Applying modifications from tasks.” It did not clearly warn that thousands of unrelated lines were being added to the commit.

Expected Result

A pre-commit quality check should not silently expand a focused documentation change into a whole-file rewrite.

Generated or externally managed files should retain their source formatting unless a developer explicitly requests a formatting migration.

Root Cause

• prepare automatically installs Husky.
• Husky runs npx lint-staged on every commit.
• The lint-staged Markdown rule uses prettier --write, not a read-only check.
• content/navigation.md and other wikiGDrive-managed content are not excluded.
• Prettier formats complete files rather than changed lines.
• lint-staged stages the resulting modifications automatically.

Recommended Fix

• Remove write-mode formatting from the pre-commit hook. Prefer prettier --check for files that are expected to conform.
• Exclude wikiGDrive-generated or externally managed content from automatic formatting.
• At minimum, add content/navigation.md to .prettierignore.
• Consider excluding all generated content/** paths and formatting only explicitly maintained source directories.
• Add a regression test that stages a one-line navigation change, invokes the hook, and confirms that the diff remains one line.
• Make full-repository formatting an explicit developer command rather than an automatic commit side effect.

Until fixed, HUSKY=0 git commit or git commit --no-verify bypasses the hook, but that should only be a temporary workaround after manually reviewing the staged diff.

Additional Info: How It Runs Automatically
The command is triggered by this chain:

1. npm install or npm ci runs the npm prepare lifecycle script:

   • package.json contains "prepare": "husky".
   • Husky sets the local Git configuration core.hooksPath to .husky/_.

2. When git commit runs, Git invokes the generated .husky/_/pre-commit wrapper.

3. The wrapper loads h, which executes the repository hook unless HUSKY=0 is set.

4. pre-commit runs:

   npx lint-staged

5. lint-staged reads its configuration from package.json:

   "*.{json,md,css,html}": [
     "prettier --write"
   ]

6. Any staged Markdown file therefore gets passed to prettier --write. Prettier rewrites the entire file, not only the staged lines.

7. lint-staged automatically stages the rewritten version, so the formatting changes become part of the commit.

content/navigation.md is not excluded by .prettierignore, despite being a large wikiGDrive-generated file whose existing format does not match .prettierrc.

The behavior was introduced by commit 44bea076ee20630c8acd1567cc54e923d302696e, “feat: Migrate documentation theme from Bootstrap to Tailwind CSS with mieweb/ui components (#124)”, on February 3, 2026.