Skip to content

Add frontmatter warning for mapped_pages edits#141

Merged
theletterf merged 9 commits into
mainfrom
copilot/warn-on-changes-to-mapped-pages
May 13, 2026
Merged

Add frontmatter warning for mapped_pages edits#141
theletterf merged 9 commits into
mainfrom
copilot/warn-on-changes-to-mapped-pages

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented May 11, 2026

Most contributors should not add or modify mapped_pages in doc frontmatter; that metadata should be maintained by technical writers. This PR introduces a dedicated Vale warning to flag those edits while keeping guidance explicit in lint output.

  • New lint rule: Elastic.MappedPages

    • Adds styles/Elastic/MappedPages.yml.
    • Triggers a warning when mapped_pages appears inside YAML frontmatter (supports LF/CRLF).
    • Uses reviewer-updated wording that emphasizes rare scenarios and asks contributors to consult their local technical writer before pushing changes.
  • Rule coverage in existing lint fixture flow

    • Updates .github/test-fixtures/sample-violations.md to include frontmatter with mapped_pages.
    • Updates .github/workflows/test-lint.yml to assert Elastic.MappedPages fires in the fixture-based rule check list.
  • Repo hygiene adjustment

    • Updates .gitignore to ignore Python bytecode/cache artifacts and removes previously tracked cache files from lint/ and report/.
# styles/Elastic/MappedPages.yml
extends: existence
message: "mapped_pages should only be added or updated in rare scenarios. Talk with your local technical writer before pushing changes to this key."
level: warning
nonword: true
scope: raw
tokens:
  - '(?ms)\A---\r?\n.*?^[ \t]*mapped_pages:.*?^---'

Copilot AI linked an issue May 11, 2026 that may be closed by this pull request
Copilot AI and others added 6 commits May 11, 2026 22:12
Agent-Logs-Url: https://github.com/elastic/vale-rules/sessions/1430eb4b-2fd3-4e75-a59e-cb13f4962ab5

Co-authored-by: bmorelli25 <5618806+bmorelli25@users.noreply.github.com>
Agent-Logs-Url: https://github.com/elastic/vale-rules/sessions/1430eb4b-2fd3-4e75-a59e-cb13f4962ab5

Co-authored-by: bmorelli25 <5618806+bmorelli25@users.noreply.github.com>
Agent-Logs-Url: https://github.com/elastic/vale-rules/sessions/1430eb4b-2fd3-4e75-a59e-cb13f4962ab5

Co-authored-by: bmorelli25 <5618806+bmorelli25@users.noreply.github.com>
Agent-Logs-Url: https://github.com/elastic/vale-rules/sessions/1430eb4b-2fd3-4e75-a59e-cb13f4962ab5

Co-authored-by: bmorelli25 <5618806+bmorelli25@users.noreply.github.com>
Copilot AI changed the title [WIP] Introduce rule to warn on changes to mapped_pages in documentation Add frontmatter warning for mapped_pages edits May 11, 2026
Copilot AI requested a review from bmorelli25 May 11, 2026 22:17
Comment thread styles/Elastic/MappedPages.yml Outdated
Comment thread styles/Elastic/MappedPages.yml
Copy link
Copy Markdown
Member

@bmorelli25 bmorelli25 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LG from my perspective. Ready for a review from someone else

@bmorelli25 bmorelli25 marked this pull request as ready for review May 13, 2026 17:24
Use a key-line match that works with the local Vale config and keep the workflow assertions compatible with released styles until the new rule ships.

Co-authored-by: GPT-5.5 <gpt-5.5@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@github-actions
Copy link
Copy Markdown

Vale Linting Results

Summary: 11 warnings, 9 suggestions found

⚠️ Warnings (11)
File Line Rule Message
.github/test-fixtures/sample-violations.md 2 Elastic.MappedPages mapped_pages should only be added or updated in rare scenarios. Talk with your local technical writer before pushing changes to this key.
.github/test-fixtures/sample-violations.md 6 Elastic.Articles Use 'an FAQ' instead of 'a FAQ'. The article depends on pronunciation, not spelling.
.github/test-fixtures/sample-violations.md 6 Elastic.Articles Use 'an HTML' instead of 'a HTML'. The article depends on pronunciation, not spelling.
.github/test-fixtures/sample-violations.md 6 Elastic.Articles Use 'an SQL' instead of 'a SQL'. The article depends on pronunciation, not spelling.
.github/test-fixtures/sample-violations.md 6 Elastic.Articles Use 'an HTML' instead of 'a HTML'. The article depends on pronunciation, not spelling.
.github/test-fixtures/sample-violations.md 7 Elastic.BritishSpellings Use American English spelling 'optimize' instead of British English 'optimise'.
.github/test-fixtures/sample-violations.md 7 Elastic.BritishSpellings Use American English spelling 'customize' instead of British English 'customise'.
.github/test-fixtures/sample-violations.md 7 Elastic.BritishSpellings Use American English spelling 'behavior' instead of British English 'behaviour'.
.github/test-fixtures/sample-violations.md 11 Elastic.DontUse Don't use 'just'.
.github/test-fixtures/sample-violations.md 11 Elastic.DontUse Don't use 'please'.
.github/test-fixtures/sample-violations.md 11 Elastic.DontUse Don't use 'aka'.
💡 Suggestions (9)
File Line Rule Message
.github/test-fixtures/sample-violations.md 8 Elastic.WordChoice Consider using 'efficiently' instead of 'Simply', unless the term is in the UI.
.github/test-fixtures/sample-violations.md 8 Elastic.WordChoice Consider using 'allowlist' instead of 'whitelist', unless the term is in the UI.
.github/test-fixtures/sample-violations.md 8 Elastic.WordChoice Consider using 'blocklist' instead of 'blacklist', unless the term is in the UI.
.github/test-fixtures/sample-violations.md 9 Elastic.OxfordComma Use the Oxford comma in 'reading, writing and executing.'.
.github/test-fixtures/sample-violations.md 10 Elastic.Wordiness Consider using 'to' instead of 'In order to'.
.github/test-fixtures/sample-violations.md 10 Elastic.Wordiness Consider using 'because' instead of 'due to the fact that'.
.github/test-fixtures/sample-violations.md 10 Elastic.Wordiness Consider using 'many' instead of 'a large number of'.
.github/test-fixtures/sample-violations.md 12 Elastic.Exclamation Use exclamation points sparingly. Consider removing the exclamation point.
.github/test-fixtures/sample-violations.md 12 Elastic.Exclamation Use exclamation points sparingly. Consider removing the exclamation point.

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

@theletterf theletterf merged commit 050593f into main May 13, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Warn on changes to mapped_pages

3 participants