What This Project Produces

Every release of doc-example ships the rendered outputs alongside the AsciiDoc source. To see them without a local checkout, follow the links below; each release tag publishes the corresponding artifact set on GitHub Releases and to Nexus.

The renderer matrix is intentionally redundant — each pipeline has trade-offs (footnote behavior, page break heuristics, CSS support for Paged Media, font handling) and doc-example is the regression fixture that catches when one of them drifts. New consumers can pick whichever single renderer fits their needs; the workspace exercises all of them.

How the Pipeline Works

1. src/docs/asciidoc/*.adoc is the documentation source. The master file is index.adoc; chapters under chapters/ are pulled in via include:: directives.
2. ike-parent’s `doc-pipeline profile is path-conditional on the existence of src/docs/asciidoc/. Any project (regardless of <packaging>) that has that directory gets the full toolchain activated, no extra POM config required.
3. During mvn verify, three things happen:
   1. AsciiDoc → HTML5 rendering via asciidoctor-maven-plugin (output: target/generated-docs/html/).
   2. AsciiDoc → PDF via the configured renderers. Each renderer is opt-in via a -Dike.pdf.<name> flag; default is HTML only.
   3. maven-assembly-plugin packages the AsciiDoc source as <classifier>adoc</classifier><type>zip</type> so downstream consumers can re-render with their own toolchain.
4. During mvn deploy, all attached classifiers (the adoc source zip, plus one PDF per active renderer) deploy to Nexus alongside the primary POM. A GitHub Release is created with the same artifact set.

The pattern decouples the source (which is what gets versioned and reused) from the rendered outputs (which are build artifacts pinned to a release). New consumers inherit ike-parent, drop their AsciiDoc into src/docs/asciidoc/, and get this whole pipeline for free.

Coordinates

Role in the IKE Ecosystem

This project is the canonical template for an IKE deliverable that is itself a published document. The companion project example-project^[4] is the template for a JAR + docs deliverable. Together they cover the two common shapes of IKE consumer:

For the workspace-aggregator template, see ike-example-ws^[5].

Why <packaging>pom</packaging> for doc-only

The doc-pipeline activation in ike-parent is path-conditional on <file><exists>src/docs/asciidoc</exists></file>, not packaging- conditional. Any inheritor with that source directory gets:

• Asciidoctor rendering via idoc:asciidoc (HTML5, Prawn PDF, DocBook → XSL-FO chains).
• Multi-renderer PDF wrappers via idoc:render-pdf (Prince, Apache FOP, RenderX XEP, Antenna House, WeasyPrint).
• Source-payload attachment as <classifier>adoc</classifier><type>zip</type> by maven-assembly-plugin.
• Renderer-output attachments as additional classifiers (prince, fop, xep, pdf-default, html-single, …​).

For a doc-only module like doc-example, <packaging>pom</packaging> gives exactly what the project ships — no compile/test/jar phases, no empty primary jar, just the classifier attachments. This is the post-IKE-Network/ike-issues#321 shape; earlier revisions used a custom <packaging>ike-doc</packaging> type with extension-realm machinery, which was retired in favor of the classifier-canonical shape. See the ike-parent module page^[6] for the full design rationale.

Release Cascade Position

ike-tooling -> ike-docs -> ike-platform -> [doc-example, example-project] -> ike-example-ws

doc-example releases after ike-platform (whose ike-parent this project inherits) and after ike-docs (whose ike-doc-maven-plugin provides the idoc:* render goals declared at 47 in ike-parent’s `<pluginManagement>). The workspace-orchestrated release flow is ws:release-publish from ike-example-ws, which detects source-changed subprojects and releases them in topological order — see ike-example-ws^[5].

Renderer Pipelines

doc-example exercises the full set of PDF renderers IKE supports. All start from the same AsciiDoc source under src/docs/asciidoc/.

For a deeper tour of each pipeline, see the renderer documentation on the IKE Docs site^[7].

Project Structure

doc-example/
├── pom.xml                              (1)
├── src/
│   ├── docs/asciidoc/                   (2)
│   │   ├── index.adoc                   (3)
│   │   └── chapters/
│   └── site/                            (4)
│       ├── asciidoc/index.adoc
│       ├── resources/css/site.css
│       └── site.xml
└── target/
    ├── doc-example-1-adoc.zip           (5)
    └── generated-docs/
        ├── html/                        (6)
        ├── pdf-prawn/
        └── pdf-fop/

Build Commands

# HTML only (default):
mvn clean verify

# With Prawn PDF:
mvn clean verify -Dike.pdf.prawn

# With FOP PDF:
mvn clean verify -Dike.pdf.fop

# All free renderers at once:
mvn clean verify -Dike.pdf.prawn -Dike.pdf.fop -Dike.pdf.weasyprint

# Generate this site (Maven Site Plugin):
mvn site

Inheritance Pattern

<parent>
    <groupId>network.ike.platform</groupId>
    <artifactId>ike-parent</artifactId>
    <version>27</version>
    <relativePath/>             <!-- force repo lookup; see ike-issues#323 -->
</parent>

<groupId>network.ike.examples</groupId>
<artifactId>doc-example</artifactId>
<version>1-SNAPSHOT</version>
<packaging>pom</packaging>

After inheriting, the project gets — for free — Java toolchain defaults (harmlessly inherited; no compile happens for pom-packaged modules), GPG signing via Bouncy Castle, the AsciiDoc documentation pipeline, and dependency-version management for the IKE ecosystem.

What to Copy When Starting a New Project

When creating a new IKE document project, copy the following:

Not published to Maven Central

doc-example is a reference template, not a library. Its releases are tagged on GitHub and deployed to the IKE Nexus, but it is deliberately not published to Maven Central — nothing should ever declare a dependency on it. You consume this project by reading it and copying its structure into a document project of your own. The IKE foundation (ike-base-parent, ike-tooling, ike-docs, ike-platform) is the part published to Central and meant to be inherited; see the IKE Network landing page^[8] for the foundation/examples split.

Resources