IKE Docs
IKE Doc Maven Plugin 43
- Parent Project IKE Docs
- Reports Project Information 6 Project Reports 2
IKE Doc Maven Plugin
The ike-doc-maven-plugin provides the idoc:* goal prefix — AsciiDoc rendering, multi-renderer PDF wrappers (Prince, Apache FOP, RenderX XEP, Antenna House, WeasyPrint), DocBook XSL patching, breadcrumb injection for site navigation, and renderer log scanning.
| Coordinate | Value |
|---|---|
| Group ID | network.ike.docs |
| Artifact ID | ike-doc-maven-plugin |
| Goal prefix | idoc: |
| Packaging | maven-plugin |
| Java version | 25 |
For workspace-spanning goals (ws:* prefix), see the ws plugin[1] in ike-platform. For single-repo release orchestration (ike:*), see the ike plugin[2] in ike-tooling. The three plugins are deliberately separate — idoc:* is doc rendering, ike:* is single-repo release, ws:* fans out across a workspace’s checked-out subprojects.
Plugin shape
This is a regular Maven plugin — no <extensions>true</extensions>, no custom <packaging> type registered via META-INF/plexus/components.xml, no participation in the build extension realm. Goals look up at execution time, the plugin’s <version> interpolates from ${ike-docs.version} like any other managed plugin, and consumers inherit the version through ordinary <pluginManagement> indirection.
This was not always the case. Earlier revisions registered the <packaging>ike-doc</packaging> custom type here, which forced this plugin to be loaded as a build extension and consequently forced its <version> to be a literal string everywhere it was declared. That constraint was retired alongside the migration to a classifier-canonical doc shape (see Design rationale below).
What this means for plugin consumers: nothing changes about how you invoke idoc:* goals. What changed is that the plugin no longer forces literal-version pins in your POM, and no longer contributes <packaging>ike-doc</packaging> to your reactor. Doc modules now use <packaging>pom</packaging> (or <packaging>jar</packaging> for hybrid Java-plus-docs modules) plus an adoc classifier attachment; activation is path-conditional on src/docs/asciidoc/ existence in ike-parent’s `doc-pipeline profile.
Goals at a glance
| Goal | Purpose |
|---|---|
idoc:asciidoc |
Render AsciiDoc sources via AsciidoctorJ — the heart of the doc pipeline. Handles IKE-specific renderer profiles (Prawn / Prince / AH / WeasyPrint / XEP / FOP / DocBook / single-page HTML). |
idoc:render-pdf |
Wrapper around the five external PDF renderers (Prince, AH, FOP, WeasyPrint, XEP). Selects the active renderer per -Dike.pdf.<name>=true toggles set by the doc-pipeline profile. |
idoc:adocstudio |
Generate Adoc Studio sidecar projects for assembly modules. |
idoc:patch-docbook |
Patch the stock DocBook XSL 1.79.2 stylesheets to suppress two known Saxon warnings. Applied during the docbook-xsl artifact build. |
idoc:fix-svg |
Remove bare <rect/> elements that Mermaid emits as artifacts in generated HTML — they cause rendering glitches in some browsers. |
idoc:inject-breadcrumb |
Inject navigation breadcrumbs and theme overrides into JaCoCo HTML reports so they fit visually with the rest of the Maven site. |
idoc:copy-default-pdf |
Promote one renderer’s PDF as the default. With multiple renderers producing output in pdf-prince/, pdf-fop/, etc., this picks the first available and copies it to a single canonical pdf/ location. |
idoc:prepare-renderer-output |
Create the per-renderer output directories (pdf-prince/, pdf-fop/, etc.) before the renderers run. |
idoc:scan-logs |
Scan renderer log files (renderer-*.log) for error patterns and print a summary. Used after multi-renderer runs to flag failures fast. |
idoc:package-doc |
Zip src/docs/asciidoc/ and assign as primary artifact. Originally bound to the <package> phase of the retired ike-doc lifecycle; superseded by maven-assembly-plugin’s `adoc classifier execution in ike-parent’s `doc-pipeline profile. Retained at present pending a final decision in the open question on ike-issues#321[3]; may be removed in a follow-up. |
Design rationale
This plugin’s shape — regular plugin, no extensions, no custom packaging — is the result of a deliberate architectural decision documented in ike-issues#321[3] and the dev-classifier-canonical-doc-shape topic in ike-lab-documents/topics/. Brief summary, since the issue will eventually close and this page is what surviving teams will land on:
Why no extensions
A plugin with <extensions>true</extensions> is loaded into the build extension realm at project-load time — during Maven’s “Scanning for projects” phase, before the Model Builder runs property interpolation. This means the plugin’s <version> in the POM cannot be a ${property}; it must be a literal string.
For a single-repo reactor with one plugin, the constraint is manageable. For our cross-repo cascade (ike-tooling → ike-docs → ike-platform → consumers), it became toxic: every consumer POM had to carry the literal version of every extension plugin from upstream, the literal had to be kept in sync manually across repos, and routine version-property tooling (ws:align-publish, versions:set-property) was structurally unable to maintain it. The pain surfaced as ike-issues#236[4] — pre-flight release checks repeatedly catching stale literals after upstream releases that the alignment tooling could not see.
Why no <packaging>ike-doc</packaging>
The historical reason for <extensions>true</extensions> here was to register a custom <packaging>ike-doc</packaging> type for documentation modules — a packaging that produces a .zip of AsciiDoc sources as the primary artifact, with a lean lifecycle that skips compile/test phases.
Inspection revealed two structural problems with that frame:
- The custom packaging produced a primary artifact nobody used. Across 43
<packaging>ike-doc</packaging>modules inike-lab-documents, zero dependencies referenced<type>ike-doc</type>. Consumers exclusively used a parallel<classifier>asciidoc</classifier><type>zip</type>attachment (built bymaven-assembly-pluginfrom the same source directory). Same content, two coordinates, redundant. - Custom packaging cannot serve hybrid modules.
<packaging>is single-valued: a Java module that ships reference docs cannot be bothjarandike-doc. Hybrid modules are the norm in any non-trivial project. Every comparable docs-as-code project in the JVM ecosystem (Hibernate, Eclipse Collections, Vert.x, Quarkus, OptaPlanner, Apache projects) handles this via classifier attachments for exactly this reason. No project in the surveyed set invents a custom packaging type for documentation.
The architectural decision was therefore to retire <packaging>ike-doc</packaging> in favor of a classifier- canonical shape: <classifier>adoc</classifier><type>zip</type> attached to either a <packaging>pom</packaging> (doc-only) or <packaging>jar</packaging> (hybrid) primary. Activation is path-conditional on src/docs/asciidoc/ existence in ike-parent’s `doc-pipeline profile — not packaging type — so hybrid modules become first-class without per-module ceremony.
The artifact-uniformity argument for staying Maven-canonical
A natural objection: most large JVM projects (Spring, many Apache projects, Quarkus) publish docs as static sites to gh-pages or CDN-hosted destinations rather than as Maven artifacts. Why not follow that pattern?
Examined point-by-point, those rationales do not transfer. Most of the apparent reasons (continuous publication, search-driven discovery, contributor friction, CDN economics) have Maven-snapshot-plus-post-deploy-rsync solutions and so do not argue against staying inside the Maven artifact ecosystem. What genuinely remains as a non-Maven argument — Antora as a turnkey product — does not apply here, because we have already built the equivalent rendering pipeline (`ike-parent’s render profiles, Prince/FOP/XEP chains, knowledge.design rsync deploy, the asciidoctor toolchain). Spring would have to throw away their pipeline to gain Antora’s turnkey-ness; we have ours, so the comparison does not apply.
For our constraints — small team, cross-repo doc dependencies via topic libraries, an already-built rendering pipeline, and a standing commitment to artifact uniformity — staying inside the Maven artifact ecosystem is the rigorous choice. We hold every shipped artifact, code or documentation, to the same engineering standard: signed (Bouncy Castle GPG, parallel-safe), versioned, deployed to Nexus, mirrorable, and reproducibly buildable years later. We do not want one class of output operating under different rules than another. The single-pipeline discipline is the standard we are protecting.
The classifier-canonical shape is fully Maven-canonical — every artifact deploys to Nexus, signed and versioned, just like every other output of the project. The choice between custom packaging and classifier is not a Maven-vs-non-Maven choice; both stay inside the Maven ecosystem. Custom packaging was buying an aesthetic type-system marker; classifier-canonical buys a single mechanism that handles doc-only and hybrid uniformly.
Tracking
- ike-issues#321[3] — primary tracking issue (umbrella); subsumes #220, #236, #320.
- ike-issues#216[5] — repo split that established the cross-repo boundary the extension realm was working around.
- Design note:
dev-classifier-canonical-doc-shapeinike-lab-documents/topics/(full Socratic discovery captured for posterity).
See also
ike:*plugin in ike-tooling[2] — single-repo release orchestration.ws:*plugin in ike-platform[1] — workspace-spanning goals.- ike-docs reactor home[6].
- Source on GitHub[7].
- Issue tracker[8].