[#1154] Replace legacy ForgeRock relative links in the guides with Antora xrefs - #1158
Merged
vharseko merged 1 commit intoOct 1, 2026
Merged
Conversation
…n the guides with Antora xrefs - Point the docs/openam/13 and openam/13 links in the agent guides at the matching chapters and anchors of this documentation set - Point the openam-web-policy-agents / openam-jee-policy-agents links at the bundled Web and Java EE Policy Agent guides - Fix the "Configuring Policies" link in the Tomcat chapter, which pointed at the CDSSO chapter - Write the chap-jee-agent-config xrefs without the ./ prefix, which the Antora converter turned into an invalid module reference Fixes OpenIdentityPlatform#1154
maximthomas
approved these changes
Oct 1, 2026
maximthomas
left a comment
maximthomas
left a comment
Contributor
There was a problem hiding this comment.
praise: Every legacy relative link in the guides now stays within this documentation set.
- No
link:../../and noxref:./remain underopenam-documentation/openam-doc-source/src/main/asciidocat the head. - The "Configuring Policies" link in
jee-users-guide/chap-apache-tomcat.adoc:31, which pointed at the CDSSO chapter, now targetsadmin-guide/chap-authz-policy.adoc#configure-policies-with-console.
This was referenced Oct 2, 2026
vharseko
added a commit
to OpenIdentityPlatform/doc.openidentityplatform.org
that referenced
this pull request
Oct 2, 2026
… Sitemap line (#38) Fixes #36 Fixes #37 **Stacked on #28.** Both issues extend the `Build` workflow and the baseline check that #28 adds, so this branch carries the commits of #28 (its current head, a2c1a17). Only the commits after it are this change; the branch will be rebased onto `master` once #28 is merged. ## #36: anchors of links - **`build.yml`**: lychee runs with `--include-fragments`. - **`.github/build-baseline/broken-links.jq`** (new): the broken links of the lychee report as `page <TAB> link`, used by both `check.sh` and the job summary. It drops a `Cannot find fragment` whose anchor is the name of the target page itself (`chap-resource-conf#chap-resource-conf`): Antora renders the page title without an id, so the browser opens the top of the page, which is where the link points anyway. lychee's regular expressions have no back references, so this is done on the JSON report, as proposed in #36. - The job summary lists and counts each page/link pair once, as `check.sh` does, and shows how many links were left out: `N checked, M broken (K more point to the top of their target page).` (K counts occurrences, as lychee's `errors` does.) - **Self-test**: with empty known lists, `check.sh` must pass a link to the top of its target page, and must exit 1 with a `New broken links` annotation on a broken anchor and on a missing page linked at its own id (`d/b.html#b` as `Cannot find file`). - **`broken-links.txt`**: 35 broken anchors are added with `check.sh --update`: the 37 listed in #36 but the two `.:chap-jee-agent-config.adoc` ones, which OpenIdentityPlatform/OpenAM#1158 has fixed on `master`. The 10 known links of #28 are unchanged. Reporting them in the product repositories is not done yet, it follows separately. ## #37: head meta tags and the robots.txt Sitemap line **`.github/build-baseline/head-meta.sh <site>`** (new), run as a new last step, also when the comparison with the known problems fails, so that one run reports both. It fails when: - `robots.txt` has no line `Sitemap: <site.url>/sitemap.xml`, `site.url` read from `antora-playbook.yml`, or `sitemap.xml` is missing; - a page carries other than exactly one each of `<meta name="description"`, `og:title`, `og:description`, `og:image`, `twitter:card`, `og:url`; `og:url` is not required on `404.html`. Redirect pages (`<meta http-equiv="refresh"`, as Antora writes them) and the API docs copied by `npm run copyApiDocs` (the same paths as the link check excludes) are skipped. Problems go to the job summary and as error annotations. A self-test step feeds the script a test site with an empty `robots.txt`, no `sitemap.xml`, a redirect page and a page without `og:image`, with `twitter:card` twice, that quotes a refresh tag, and requires exactly those four problems. ## Verification On a local build of this branch, with the commands of the workflow: - lychee with `--include-fragments`: 382 distinct broken anchors, of which 347 to the page itself and the 35 above; `check.sh`: 0 new, 0 no longer found; the job summary: 45 broken, 45 rows; - both self-test steps pass, and fail against each of 12 mutants: in `broken-links.jq` the status guard replaced by `true`, no filter, every fragment error dropped, the whole path compared, no `rtrimstr`; `check.sh` exiting on the new-entry path before the annotation; in `head-meta.sh` the tag count check deleted, `-eq 1` → `-ge 0`, a loose `http-equiv="refresh"` match, the robots.txt or the sitemap.xml check deleted, always exit 0; - `head-meta.sh build/site`: 285 pages checked, 0 problems.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #1154
About 30 relative links in the guides pointed to the old ForgeRock documentation layout and resolve to 404 on https://doc.openidentityplatform.org. They now point at the matching pages of this documentation set.
Changes
link:../../../docs/openam/13/…andlink:../../../openam/13/…in the Web and Java EE agent guides → xrefs to the matching Administration / Installation Guide chapters and anchors. Two anchors no longer exist and are mapped to their closest current sections:wildcard-syntax→chap-authz-policy.adoc#policy-patterns-wildcardsconfigure-authz-policy/chap-authz-policy→chap-authz-policy.adoc#configure-policies-with-consolelink:../../../openam-web-policy-agents/…/link:../../../openam-jee-policy-agents/…→xref:../web-users-guide/index.adoc[…]/xref:../jee-users-guide/index.adoc[…]; the#configure-web-policy-agentlink goes toweb-users-guide/chap-web-agents.adoc.link:../../../openam/admin-guide/chap-cdsso→xref:../admin-guide/chap-cdsso.adoc#chap-cdsso[…]. Inchap-apache-tomcat.adocthe "Configuring Policies" link also pointed at the CDSSO chapter; it now points at the policy section.xref:./chap-jee-agent-config.adoc#…inchap-apache-tomcat.adocandchap-jetty.adoc→xref:chap-jee-agent-config.adoc#…: AntoraMojo turned the./form intoxref:.:chap-….The xrefs use the form already used across the guides,
xref:../<guide>/<chapter>.adoc#<id>[…], which AntoraMojo rewrites toxref:<guide>:<chapter>.adoc#<id>[…].window=\_blankis dropped from these links, since they now stay within the site, and the link texts follow the target headings.Verification
link:../../orxref:./links remain in the guide sources.mvn -P man-pages packageinopenam-doc-sourcesucceeds; the Antora output contains the rewritten links (e.g.xref:admin-guide:chap-cdsso.adoc#chap-cdsso[), all nine PDFs build, and asciidoctor reports no warnings.Not in scope: about 20
link:../<guide>/index.html#<anchor>links (dev-guide, reference, jee-users-guide) open the guide's index page on the site rather than the anchored section; they can be handled separately.