Repository navigation
[#1156] Add OpenAM How-To guides to site navigation - #42
Merged
vharseko merged 1 commit intoNov 6, 2026
Merged
Conversation
vharseko
added
documentation
vharseko
added a commit
to OpenIdentityPlatform/OpenAM
that referenced
this pull request
Nov 6, 2026
Publishes 54 practical wiki articles as a searchable How-To guide with 222 local images. Registers the guide in the documentation build and adds a deferred wiki migration patch. Companion site PR: OpenIdentityPlatform/doc.openidentityplatform.org#42. The migrated articles preserve code listings, section anchors and links between articles. Own-site documentation links use version-aware Antora xrefs. The custom authentication module tutorial has corrected compilation, packaging and installation instructions and explains how its preserved wiki listings differ from the repository sample. Linux Maven builds use a 6 GB heap in build, deploy and release workflows to address the JDK 11 PDF build's `OutOfMemoryError` at the previous head. macOS and Windows builds retain 4 GB. The Linux/JDK 11 build runs link-checker regression tests and validates generated How-To xrefs against explicit destination anchors, including generated service-reference anchors. The checker rejects unprotected intraword double hyphens and excludes anchor-like text in comment, listing and literal blocks. ### Validation at this head - Eight link-checker regression tests pass. Coverage includes exact closing delimiters, anchors between two blocks, longer delimiters and delimiters with trailing whitespace. - All five tested mutations are detected: accepting any closing delimiter, greedy block stripping, limiting delimiters to four characters, ignoring padding on both delimiters, and ignoring padding on the closing delimiter. - Existing generated-source check: 136 xrefs across 55 pages; 0 errors. - All three modified workflow YAML files parse successfully; `git diff --check` passes for this round. - A local JDK 11 PDF-only run with `-Xmx6g` was stopped before completion because it was taking too long. It provides no completed PDF-build validation. The fix still needs two successful `build-maven (ubuntu-latest, 11)` runs at this head, including one rerun; the 6 GB heap is not yet proven sufficient on CI. ### Earlier validation - doc-maven-plugin 3.2.2 preprocessing and Antora generation; current-version site integration build. All 55 rendered How-To pages were checked for local links, fragments and images (232 image occurrences), with no How-To diagnostics or unresolved elements. - A 318-page How-To PDF was built with `-Xmx4g` (28,009,356 bytes), and its restored heading and Adaptive Risk link annotation were checked. A later Ubuntu/JDK 11 CI build failed with heap exhaustion, so that earlier success does not establish reliability at 4 GB. - The tutorial's Java listings compiled and packaged with `openam-core` and `openam-shared` on JDK 11, 17, 21 and 27. - The regenerated wiki patch passed forward and reverse applicability checks at wiki revision `c68baf2f36df4bb0d3c0b3c7f96a43832b80e4f3`. The patch preserves historical whitespace. ### Publication order and follow-ups The [wiki patch](https://github.com/OpenIdentityPlatform/OpenAM/blob/0cc84f8c8d04745e3861cd91d8c8015eb1c78fce/openam-documentation/wiki-migration/wiki-how-to.patch) and [inventory/application instructions](https://github.com/OpenIdentityPlatform/OpenAM/blob/0cc84f8c8d04745e3861cd91d8c8015eb1c78fce/openam-documentation/wiki-migration/README.md) are included for later application. The patch is not applied automatically. Publish and verify the generated documentation, then merge and deploy the companion site navigation change. Before applying the wiki patch, complete the incoming wiki section-link preservation tracked in #1220. That issue also tracks version-specific cross-guide PDF URLs in the shared converter. The site build and external integration workflows were not rerun for this round. Fixes #1156
vharseko
force-pushed
the
docs/1156-how-to-navigation
branch
from
November 6, 2026 07:03
4f2c05a to
a25bb46
Compare
vharseko
added a commit
that referenced
this pull request
Nov 6, 2026
The offline link check reports valid OpenDJ release-note links such as `release-5.2.0` as missing. Antora publishes `release-5.2.0.html`, but lychee 0.24.2 replaces `.0` with `.html` when applying fallback extensions and looks for `release-5.2.html`. Remap local dotted release-page URLs to their HTML files while preserving fragments. Keep the workaround until lychee includes [lycheeverse/lychee#2276](lycheeverse/lychee#2276). Missing files and invalid fragments remain errors. Validation: six focused checks using lychee 0.24.2 and options extracted from the modified workflow pass. They cover dotted page names, valid fragments, explicit HTML links, names without dots, missing files and invalid fragments. The two valid dotted-link cases fail without the workaround. Workflow YAML parsing, `bash -n` for all eight shell steps and `git diff --check` pass. The full site build was not run locally. Related: #42.
vharseko
force-pushed
the
docs/1156-how-to-navigation
branch
from
November 6, 2026 08:31
a25bb46 to
3a1d9f5
Compare
vharseko
force-pushed
the
docs/1156-how-to-navigation
branch
from
November 6, 2026 09:37
3a1d9f5 to
1be1661
Compare
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
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.
Adds OpenAM How-To Guides to the site landing page, OpenAM navigation and PDF mapping.
Merge after the companion OpenAM documentation change has deployed its generated
how-tomodule. Generated pages and images remain owned by the existing OpenAM publication workflow.Validation: current-version Antora integration build with the companion generated module; all 55 How-To pages checked for local links, fragments and images. No new How-To diagnostics; existing warnings elsewhere remain unchanged. Historical release tags were excluded from the integration playbook.
Companion PR: OpenIdentityPlatform/OpenAM#1218.
Related issue: OpenIdentityPlatform/OpenAM#1156.