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, renderer log scanning, and doc-diff review packets (idoc:diff).

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.

For people who work through Claude rather than a terminal, The Topic Registry: A Plain-Language Guide[3] walks through idoc:topic-registry with a tutorial and every action it offers.

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:diff Generate and render a review packet: every changed AsciiDoc topic between two refs (or a ref and the working tree), marked inline with insertion/deletion roles. See Review packets below.
idoc:topic-registry Read the :topic-*: header of every AsciiDoc file under the module’s source root and write target/topic-registry.yaml: the topic registry, generated from the headers in IKE-TOPIC-REGISTRY.md’s shape instead of kept by hand. See Topic registry below. With `ike.adoc.layout=packages the registry is blob-keyed and incremental, and written with the term index under META-INF/ike/<groupId>/<artifactId>/. See AsciiDoc packages below.
idoc:manifest Write META-INF/ike/<groupId>/<artifactId>/manifest.yaml for a topic library laid out as packages: its coordinates, the packages it ships with their kind, and the path of its registry. Generated from the POM and the tree, never kept by hand.
idoc:lint-packages Lint the packages layout of a topic library and fail the build with every finding listed: the root holds only dotted-group directories and META-INF, every package begins with the module’s group, a topic’s directory equals its id’s domain prefix, images are inside packages. Lines still using {topics} are warnings.
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[4]; may be removed in a follow-up.

Review packets (idoc:diff)

Reviewing documentation changes offers two bad currencies: git diff is source-true but contextless; rendered books carry context but no deltas. idoc:diff closes the gap — a generated, renderable review packet in which every changed topic appears as its own chapter with word-level [.diff-ins]/[.diff-del] markup in place, deletions struck through, insertions highlighted, and non-prose changes (attributes, index terms, table and diagram interiors) reported in a per-topic change-summary note. Changed diagrams render alongside their source delta and previous rendering.

mvn idoc:diff                                    # HEAD vs working tree
mvn idoc:diff -Dike.diff.from=v1.2.3             # tag vs working tree
mvn idoc:diff -Dike.diff.from=A -Dike.diff.to=B  # any two commits
mvn idoc:diff -Dike.diff.topics=arch-overview    # share-scoped excerpt

The goal works at the Maven subproject level: a topics-library module (one whose source root holds topics/) yields the corpus packet (with an entry-keyed topic-registry delta); an assembly module yields the projection of the diff onto the topics its include:: lines name; an aggregator invocation produces a packet for every subproject able to generate one. The registry on each side is generated from the files on that side, as idoc:topic-registry would; no hand-kept registry file is read. Outputs land in target/doc-diff/ as packet sources, HTML, and a Prawn PDF — the goal is self-contained, so a bare invocation on a fresh checkout produces a styled packet (branded typography when the pipeline fonts are unpacked; a bundled fallback theme otherwise). Files a marked topic pulls in by relative include:: — diagram sources, shared snippets — are staged beside it, so an include that resolves from the source tree resolves from the packet too.

Changes are first-class, named entities: author a changes.yaml beside the module pom (or at the repository root) with an id, title, one-line description, issue refs, and touched files per change — or, for commit-to-commit comparisons, let the goal derive entities by grouping the range’s commits on their Refs:/Fixes: trailers. The entities project into a Record of Changes, a Change Glossary, and an index-driven Change Index. Each change boundary also carries a STAMP endnote — Status (Active/Inactive), Time, Author, Module (topic domain), Path (branch) — collapsed per paragraph and tabulated in a Stamp Register.

Design note: dev-doc-diff-pipeline in ike-lab-documents/topics/; epic ike-issues#648[5].

Topic registry (idoc:topic-registry)

idoc:topic-registry is the topic registry’s build-time revision: the registry keeps the shape IKE-TOPIC-REGISTRY.md gives it and is now generated from the files on every run instead of typed by hand. The goal reads the :topic-*: attribute block, the anchor and the level-1 heading of every .adoc file under the module’s src/docs/asciidoc — plain line parsing, no AsciidoctorJ — and writes target/topic-registry.yaml in the shape IKE-TOPIC-REGISTRY.md gives the registry: registry-version, generated, topic-count, then domains, one per id prefix, each with its topics in id order (id, file, title, type, keywords, status, char-count, related, summary, and what the header adds: provenance, anchor, header, …​). After the domains come assemblies (files with include:: lines, with their counts), other-files, and a findings list. The file that was kept by hand at src/docs/asciidoc/topic-registry.yaml is no longer maintained; neither this goal nor idoc:diff reads it, so it can be deleted once its values are moved into topic headers. What a header cannot say is not generated: domain titles and descriptions, assembly sections and topic-refs, and dependencies unless a header declares them. The same structure is printed to the build log as a directory tree. Symbolic links are never followed (a linked .adoc is a finding), files are parsed in parallel, and the YAML is written directly, so a 20,000-file module rebuilds in well under a second.

mvn idoc:topic-registry                                          # the module's src/docs/asciidoc
mvn idoc:topic-registry -Dike.topic-registry.roots=a,b           # other roots, comma-separated
mvn idoc:topic-registry -Dike.topic-registry.output=/tmp/r.yaml  # write elsewhere
mvn idoc:topic-registry -Dike.topic-registry.add=topics/x/new.adoc   # add an ingested file, no rescan

With -Dike.topic-registry.add= (comma-separated files, relative to the module or absolute) the named files are parsed alone and merged into the existing registry: placed in their domain in id order, counted, and checked for a duplicate id against the ids the registry already holds. An entry for the same file is replaced, so re-ingesting a document is safe. Files that were deleted are not noticed this way; a run without add re-derives everything, and runs when no generated registry exists yet.

Header findings — a missing required attribute, an anchor that does not match the id, an unknown type or status, the same id in two files — are reported in the registry and the log and do not fail the build. A module without src/docs/asciidoc is skipped with one line, so the goal can run from a reactor root. -Dike.skip.topic-registry=true skips it.

The goal’s default phase is validate, so a POM that declares an execution of it gets a fresh registry on every build, mvn clean install included, and findings still do not fail that build:

<plugin>
  <groupId>network.ike.docs</groupId>
  <artifactId>ike-doc-maven-plugin</artifactId>
  <executions>
    <execution>
      <id>topic-registry</id>
      <goals><goal>topic-registry</goal></goals>
    </execution>
  </executions>
</plugin>

AsciiDoc packages (ike.adoc.layout=packages)

A topic library may lay its AsciiDoc root out as packages (dev-adoc-packages in ike-lab-documents/topics/, epic ike-issues#1340[6]; this plugin’s part is ike-issues#1341[7]): the first directory under the root is the owning group written as one dotted segment, the directory under that is the topic domain, and a topic’s directory equals the domain prefix of its :topic-id:, so dev-gitflow-overview lives at network.ike.lab/dev/gitflow-overview.adoc and is included as include::{adoc}/network.ike.lab/dev/gitflow-overview.adoc[]. A library whose group ends in its only domain may use the group directory itself as the domain package (network.ike.kompendium.anf/determine-topic.adoc). Images are in an images directory inside the package that uses them. Artifact metadata goes under META-INF/ike/<groupId>/<artifactId>/, keyed by coordinates so that any number of libraries unpack into one tree without colliding. The preview index and shared images are rendered content, so they are in a package the library owns for itself, of kind library.

Everything below is gated by the POM property ike.adoc.layout=packages. A library that has not declared it keeps building exactly as before, through the migration.

<properties>
  <ike.adoc.layout>packages</ike.adoc.layout>
  <ike.adoc.library-package>network.ike.lab/lab</ike.adoc.library-package>  <!-- optional -->
  <ike.adoc.packages>network.ike.examples</ike.adoc.packages>               <!-- optional -->
</properties>

The registry stays incremental

With the packages layout idoc:topic-registry keys every entry by the git blob id of the content it was parsed from. One call, git ls-files -s, lists every path with its blob without opening a file; git status names what moved since, and those files are hashed on the spot with git hash-object. The rule is then exact: same path and same blob, the entry is kept; same blob at a new path, the entry is re-keyed; a new or changed blob is parsed; a path that is gone is dropped. Files that are not topics get an entry too, with their blob, so they are not opened again either. A tree without git hashes every file in Java, the full scan’s cost, and gets the same ids. -Dike.topic-registry.add is a special case of the rule and needs no separate path; -Dike.topic-registry.rootFile is not supported with packages.

The registry and the term index (IKE-INDEX.md: every indexterm:[] and term a topic marks, collected once at parse time and kept on the entry as index-terms) are written to target/adoc-meta/META-INF/ike/<groupId>/<artifactId>/topic-registry.yaml and term-index.yaml; ike-parent adds target/adoc-meta to the adoc zip. Every file: is relative to the AsciiDoc root, as the include line names it. -Dike.topic-registry.output still wins when set.

The manifest (idoc:manifest)

idoc:manifest (default phase generate-resources) writes manifest.yaml beside the registry, from the POM and the tree, never kept by hand:

coordinates: network.ike.lab:unlv-topics
packages:
  - name: network.ike.lab/aip
    kind: topics
  - name: network.ike.lab/unlv
    kind: library
registry: META-INF/ike/network.ike.lab/unlv-topics/topic-registry.yaml

A package’s kind is library when ike.adoc.library-package names it or when it holds an index.adoc and no topic; otherwise topics. The goal that unpacks the union reads every manifest and refuses two libraries that ship one package, naming both. -Dike.skip.manifest=true skips it.

The lint (idoc:lint-packages)

idoc:lint-packages (default phase validate) fails the build with every finding listed: the root holds only dotted-group directories and META-INF (hidden entries such as .asciidoctorconfig are the editor’s and pass); every package begins with the module’s own group unless ike.adoc.packages declares another package name or group prefix on purpose, comma-separated; a topic’s directory equals the domain prefix of its :topic-id:; images are inside packages, not at the root or directly under a group. An include or image line that still uses the {topics} alias is a warning naming the file and line, so the alias can be retired once the last one is gone. -Dike.skip.lint-packages=true skips it.

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[4] 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[8] — 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:

  1. The custom packaging produced a primary artifact nobody used. Across 43 <packaging>ike-doc</packaging> modules in ike-lab-documents, zero dependencies referenced <type>ike-doc</type>. Consumers exclusively used a parallel <classifier>asciidoc</classifier><type>zip</type> attachment (built by maven-assembly-plugin from the same source directory). Same content, two coordinates, redundant.
  2. Custom packaging cannot serve hybrid modules. <packaging> is single-valued: a Java module that ships reference docs cannot be both jar and ike-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[4] — primary tracking issue (umbrella); subsumes #220, #236, #320.
  • ike-issues#216[9] — repo split that established the cross-repo boundary the extension realm was working around.
  • Design note: dev-classifier-canonical-doc-shape in ike-lab-documents/topics/ (full Socratic discovery captured for posterity).

See also

Searching...
No results.