dashorst opened a new issue, #1771:
URL: https://github.com/apache/maven-site/issues/1771
### Improvement proposal
Restructuring the site moves pages and renames sections, and every link and
bookmark to an old address breaks unless someone notices. #1751 made a rule of
it: each PR adds a `Redirect Permanent` line for every published URL it
replaces. #1767 put back 17 section ids that three rewritten guides had
dropped, found and checked by hand after the rewrites were merged.
I propose a check in `mvn site`, so that the build of a pull request fails
when it breaks a published address:
- `src/published-addresses.txt` lists every page the site has published,
each with the ids on it that a link can point at: 794 pages and 2,270 anchors,
recorded from a build of master.
- After `site`, a single-file Java tool (on jsoup, like `Update.java`)
follows each listed address through the `.htaccess` files of the rendered site
the way mod_alias does: `Redirect` and `RedirectMatch`, a directory's rules
before its parent's, the first match wins. It fails when an address leads to no
page, or to a page without the anchor. An address that `Redirect gone` matches
is retired on purpose, not broken. Redirects to parts of maven.apache.org this
build does not write (plugin sites, `/ref/`, `download.cgi`) are not followed.
Run on master just before #1767, with the list as it was on 25 October, it
reports the 17 ids:
```
Addresses: 781 published, 2 redirected, 2 to sites outside this build, 0
retired, 3 broken
/guides/mini/guide-creating-archetypes.html lacks
#a4._Install_the_archetype_and_run_the_archetype_plugin
/guides/mini/guide-http-settings.html lacks
#Configuring_GET.2C_HEAD.2C_PUT.2C_or_All_of_the_Above #Connection_Timeouts
#Example.3A_Lifting_auth_scope_restriction_for_external_authentication_systems
#Example.3A_Using_Preemptive_Authentication #Fine-Tuning_HttpClient_Parameters
#HTTP_Headers #Ignoring_Cookies #Introduction #Non-String_Parameter_Values
#Read_time_out #Support_for_General-Wagon_Configuration_Standards
#Taking_Control_of_Your_HTTP_Headers #The_Basics
/guides/mini/guide-wagon-providers.html lacks #Available_Wagon_Providers
#Command-Line_Configuration #settings.xml_Configuration
```
Today's master passes. The check takes about a second.
When it fails, it says how to fix it:
```
/guides/mini/guide-java-target.html does not exist, and no redirect leads
away from it
it moved to /docs/java/target.html, which has 5 of its 5 anchors:
Redirect Permanent /guides/mini/guide-java-target.html
/docs/java/target.html
/guides/mini/guide-wagon-providers.html lacks #Available_Wagon_Providers
To fix a broken address, do one of these:
- redirect it to its new place: Redirect Permanent <old> <new> in
content/filtered-resources/.htaccess
- put a dropped anchor back above the section that holds its content: <a
id="Available_Wagon_Providers"></a>
- retire it on purpose: Redirect gone <old>, or delete the anchor from
src/published-addresses.txt
Not on the list yet: 1 address and 0 anchors; add them with: mvn site
-Daddresses=record
```
A page that moved as a whole keeps the ids of its headings, so the check
recognises its new place and writes the `Redirect` line. Where an anchor went
it cannot tell; that is for the editor. It edits no files: every change to
`.htaccess` or the list stays a deliberate line in the diff.
New pages and anchors are reported but do not fail the build; `mvn site
-Daddresses=record` adds them to the list. A workflow on master could do this,
like the release metadata update.
Not covered: links inside the page text, and `RewriteRule`, which the site
does not use.
Related: #1062 (MNGSITE-24) asked for dead-link checking; the Doxia
Linkcheck profile that closed it is no longer in the pom.
I have an implementation and will open a PR.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
