[elharo]

Add a test that validates markdown syntax

The test scans all Markdown docs under content/markdown (*.md and *.md.vm) and fails with file:line details. It runs as part of the existing mvn verify build in the Verify Site workflow.

Fix existing unescaped occurrences in release notes (rc-4 through rc-7) so CI passes.

[elharo]

Is the test actually running? Do we need to add it to the CI config?

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

4 open issues

• This dependency has no explicit version. If the project (or parent) doesn’t already manage… · New
• The PR description says the test scans content/markdown/**/*.md and *.md.vm, but the… · New
• Files.readAllLines(file) uses the platform default charset, which can make this test fail or… · New
• This line-by-line regex scan will also flag matches inside fenced code blocks (and potentially… · New

What changed in this PR

Adds a CI-enforced validation to ensure JIRA issue keys used as Markdown link labels have escaped brackets (e.g., [\[MNG-1234\]](URL)), preventing broken links in generated docs.

Changes:

• Add a JUnit test that scans Markdown docs for unescaped [[KEY]](URL) link labels and reports file:line violations.
• Add JUnit Jupiter as a test dependency.
• Update existing release notes (rc-4 through rc-7) to use escaped-bracket link labels.

File	Description
src/​test/​java/​org/​apache/​maven/​site/​MarkdownDocsTest.java	Introduces the docs-scanning CI test and violation reporting.
pom.xml	Adds JUnit Jupiter dependency needed to run the new test.
content/​markdown/​docs/​4.0.0-rc-7/​release-notes.md	Escapes issue-key link labels to satisfy the new validation.
content/​markdown/​docs/​4.0.0-rc-6/​release-notes.md	Escapes issue-key link labels to satisfy the new validation.
content/​markdown/​docs/​4.0.0-rc-5/​release-notes.md	Fixes/normalizes issue-key links to escaped form for the new validation.
content/​markdown/​docs/​4.0.0-rc-4/​release-notes.md	Escapes issue-key link labels to satisfy the new validation.

_{Review effort: Lite}

[elharo]

Addressed the review comments in 47bdbe2:

• The test now parses documents with flexmark (the parser behind Doxia Markdown) and detects any [[...]](...) link syntax, rather than matching JIRA keys with a regex.
• IOException is propagated so a file read failure fails the test directly.
• Files are read as UTF-8, and fenced code blocks are skipped by the parser.

The test runs as part of mvn verify in the existing Verify Site workflow (verify-site.yml), so no CI workflow change is needed.

[elharo]

The test already runs in the Verify Site workflow. The workflow invokes ./mvnw ... verify site, and Surefire executes the test during verify. The latest run for e1015de4 shows:

[INFO] Running org.apache.maven.site.MarkdownDocsTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

See https://github.com/apache/maven-site/actions/runs/40420110047. The required Verify and build Maven Site check therefore covers this test; no workflow change is needed.