Skip to content

Rewrite the site index and download pages - #181

Draft
slachiewicz wants to merge 1 commit into
masterfrom
docs/site-prose-alternative
Draft

Rewrite the site index and download pages#181
slachiewicz wants to merge 1 commit into
masterfrom
docs/site-prose-alternative

Conversation

@slachiewicz

Copy link
Copy Markdown
Member

An alternative proposal for the same two files as #173, offered so the two passes can be compared side by side. Only one of them should land.

Points that the diff does not show:

  • Five headings become sentence case, which changes their generated ids (Proxy_Settings to Proxy_settings, and the same for Local Repository, Remote Repositories, Offline Mode, and Output Artifacts). The former ids are preserved as explicit <a id> anchors, so no published link breaks. maven-site-plugin 3.22.0 keeps those anchors; on 3.21.0 and earlier they are dropped.
  • More information was a second <h1> on the page. It is now an <h2>.
  • The Mirrors section had a heading and a code sample but no prose. The introductory sentence is new content rather than a rewrite.
  • The download page keeps the verification step as a requirement and splits the two verification methods into a list. It also keeps the recommendation to use the current release, attributed rather than stated impersonally.
  • The properties are prefixed with the ref id of the <pom> element, e.g. ${pom.version} is ambiguous about what the prefix is. The rewrite names the id and the resulting property separately.

Verified: mvn site on this branch, then the rendered target/site/index.html anchors diffed against https://maven.apache.org/resolver-ant-tasks/index.html. No published anchor is missing, five are added, and no id is duplicated.

This change was created with AI assistance.

Sentence-cases five headings, which changes their generated ids. The
previous ids are kept as explicit anchors so no published link breaks;
do not drop those anchors when editing these headings.

Adds an introductory sentence to the Mirrors section, which had none.
@slachiewicz slachiewicz added the documentation Improvements or additions to documentation label Aug 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant