influxdata / influxdata/docs-v2

Vale under-reports on pages with front matter, so product pages are linted less strictly than shared content

Open
#7,617 0 comments 0 reactions 0 assignees View on GitHub
area:ci
Dominant language
JavaScript
Stars
82
Forks
326
Avg merge
1d 1h
Merged PRs (30d)
82

Description

## Summary

Vale reports fewer alerts on a page **with** front matter than on the identical
body **without** it. Because `content/shared/**` files are body-only and product
pages carry front matter, shared content is linted strictly and product pages
are not.

## Evidence

Bisected on `content/enterprise_influxdb/v1/supported_protocols/collectd.md`
(before it was migrated to shared content), using the same body in both cases:

| body | no front matter | with front matter |
| --- | --- | --- |
| lines 1-14 | 4 errors | 4 errors |
| lines 1-20 | 4 errors | **0 errors** |
| full file | 4 errors | **0 errors** |

Findings:

- Path is irrelevant. Same result at `content/enterprise_influxdb/v1/` and at
`content/shared/`.
- Any front matter triggers it -- `title:` alone is enough. It is not specific
to `description: >` or `aliases:`.
- A short synthetic body is **not** affected, so it depends on body length as
well as front-matter presence.
- Lines 15-20 of the trigger case are ordinary prose: no shortcodes, no `---`,
no `vale off` directive.

The suppressed alerts are real: `Google.Latin` on `e.g.`, `Google.Spacing` on
double spaces after a period.

Mechanism not identified. It looks like an offset bug in Vale's front-matter
handling rather than anything in our configuration.

## Impact

- **The corpus is less linted than it appears.** A product page passing Vale is
not evidence its prose is clean.
- **Migrating content into `content/shared/` exposes pre-existing errors**, and
`pr-vale-check.yml` blocks on errors. Moving 31 InfluxDB v1 pages surfaced 22
errors that had always been there. Anyone doing a shared-content migration
should budget for this.
- Existing `content/shared/influxdb-v2` reports 16 errors across 300 files while
equivalent product pages report 0 -- consistent with this, not with the shared
files being worse written.

## Suggested next steps

1. Quantify the gap: run Vale over a sample of product pages with front matter
stripped and compare alert counts.
2. Check whether this reproduces on current upstream Vale; if so, report it
upstream with the minimal case above.
3. If it is not fixable soon, consider linting product pages with front matter
stripped in CI so the gate is honest.

## Notes

Found while migrating InfluxDB v1 content to shared files. Two Vale configs run
locally: the default `.vale.ini`, and `.vale-instructions.ini` via the
`lint-instructions` pre-commit hook. The latter also covers `content/shared/**`
and caught a `Vale.Repetition` the default run did not report, so both are worth
running before committing shared content.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with content/enterprise_influxdb/v1/supported_protocols/collectd.md and reproduce the front-matter comparison using the default .vale.ini and .vale-instructions.ini. Check pr-vale-check.yml and compare Vale output with front matter present versus stripped, including the minimal case described. Done means the cause is identified and either upstream reproduction/reporting or an agreed CI linting path is documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
ci-cd, documentation, testing
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.