influxdata / influxdata/docs-v2
Vale under-reports on pages with front matter, so product pages are linted less strictly than shared content
- 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