---
date_published: 2026-05-19
date_modified: 2026-05-19
canonical_url: https://github.com/IKE-Network/doc-example/index.html
---

# doc-example

A standalone reference project demonstrating an IKE consumer whose **primary deliverable is a published document** rather than a JAR. Inherits `network.ike.platform:ike-parent` and exercises the full multi-renderer pipeline (HTML, Prawn PDF, FOP PDF, plus Prince/AH/ WeasyPrint/XEP toggleable on demand).

## [#what-this-project-produces](#what-this-project-produces)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.

| Artifact | What it is |
| --- | --- |
| [doc-example-<v>-adoc.zip](https://github.com/IKE-Network/doc-example/releases/latest)[1] | AsciiDoc source bundle (`classifier=adoc`, `type=zip`). The canonical "what the project ships" payload — every consumer who wants to re-render gets this. |
| [doc-example-<v>-pdf-prawn.pdf](https://github.com/IKE-Network/doc-example/releases/latest)[1] | Prawn-rendered PDF. Ruby-based renderer with sensible publication defaults. Fast feedback loop during authoring. |
| [doc-example-<v>-pdf-fop.pdf](https://github.com/IKE-Network/doc-example/releases/latest)[1] | Apache FOP PDF via DocBook intermediate. Java-only renderer; no external binary required. Used by reproducible-builds pipelines. |
| [doc-example-<v>-html-single.zip](https://github.com/IKE-Network/doc-example/releases/latest)[1] | Single-file HTML rendering. Ships the master document as one long page for offline browsing. |
| [This project site](https://ike.network/doc-example/)[2] | The page you’re on now. Generated by `mvn site` from `src/site/asciidoc/index.adoc` (separate source tree from the document deliverable in `src/docs/asciidoc/`). |

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](#how-the-pipeline-works)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](#coordinates)Coordinates

| Coordinate | Value |
| --- | --- |
| Group ID | `network.ike.examples` |
| Artifact | `doc-example` |
| Packaging | `pom` (post-`IKE-Network/ike-issues#321`) |
| Parent | `network.ike.platform:ike-parent` (current — see [ike-platform site](https://ike.network/ike-platform/)[3] for the released version) |
| Source classifier | `<classifier>adoc</classifier><type>zip</type>` |
| Render classifiers | `prince`, `fop`, `xep`, `pdf-default`, `html-single`, etc. |

## [#role-in-the-ike-ecosystem](#role-in-the-ike-ecosystem)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](https://ike.network/example-project/)[4] is the template for a **JAR + docs** deliverable. Together they cover the two common shapes of IKE consumer:

| Template | When to copy from it |
| --- | --- |
| `doc-example` | You’re shipping a published document as the primary deliverable — a guide, specification, manual, or reference. No Java compile path. Uses `<packaging>pom</packaging>` and ships the source as the `adoc` classifier. |
| [example-project](https://ike.network/example-project/)[4] | You’re shipping a JAR (a library, a CLI, a service) AND want rendered docs alongside it. |

For the workspace-aggregator template, see [ike-example-ws](https://ike.network/ike-example-ws/)[5].

## [#why-packagingpom-packaging-for-doc-only](#why-packagingpom-packaging-for-doc-only)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](https://ike.network/ike-platform/ike-parent/)[6] for the full design rationale.

## [#release-cascade-position](#release-cascade-position)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](https://ike.network/ike-example-ws/)[5].

## [#renderer-pipelines](#renderer-pipelines)Renderer Pipelines

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

| Renderer | Path | Activation |
| --- | --- | --- |
| HTML | `target/generated-docs/html/` | Default; always built. |
| Prawn PDF | `target/generated-docs/pdf-prawn/doc-example.pdf` | `-Dike.pdf.prawn`. Ruby-based, fast, sensible defaults. |
| FOP PDF | `target/generated-docs/pdf-fop/doc-example.pdf` | `-Dike.pdf.fop`. Java-based, XSL-FO via DocBook intermediate. |
| Prince PDF | `target/generated-docs/pdf-prince/doc-example.pdf` | `-Dike.pdf.prince`. Commercial; CSS Paged Media. |
| Antenna House PDF | `target/generated-docs/pdf-ah/doc-example.pdf` | `-Dike.pdf.ah`. Commercial; CSS Paged Media. |
| WeasyPrint PDF | `target/generated-docs/pdf-weasyprint/doc-example.pdf` | `-Dike.pdf.weasyprint`. Open source; Python-based. |
| RenderX XEP PDF | `target/generated-docs/pdf-xep/doc-example.pdf` | `-Dike.pdf.xep`. Free personal license; XSL-FO via DocBook. |

For a deeper tour of each pipeline, see the renderer documentation on [the IKE Docs site](https://ike.network/ike-docs/)[7].

## [#project-structure](#project-structure)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/
```

Inherits `network.ike.platform:ike-parent` with `<relativePath/>` (per `IKE-Network/ike-issues#323`). Declares `<packaging>pom</packaging>`. The IKE doc-pipeline source. The path-conditional `doc-pipeline` profile in `ike-parent` activates on this directory’s existence. Master document. Includes are conventionally under `chapters/`. The Maven Site Plugin source — what generates this site you’re reading. Distinct from `src/docs/asciidoc/` (the deliverable). `adoc`-classified source ZIP, attached by `maven-assembly-plugin` and deployed to Nexus. Rendered outputs; renderer-specific classifiers attach additional ZIPs to the published artifact set.  

## [#build-commands](#build-commands)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](#inheritance-pattern)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](#what-to-copy-when-starting-a-new-project)What to Copy When Starting a New Project

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

| File / Directory | Purpose |
| --- | --- |
| `pom.xml` | Parent declaration (with `<relativePath/>`), `<packaging>pom</packaging>`, group/artifact coordinates. Adjust group ID and artifact name only. |
| `src/docs/asciidoc/` | Documentation source. Edit `index.adoc` and add `chapters/` includes as needed. This is the deliverable. |
| `src/site/` | Maven Site Plugin source. Update `site.xml` (project name, repo URL) and `asciidoc/index.adoc` for your project. The Forest-theme `site.css` and `ike-logo.svg` come from `ike-build-standards` — inherited automatically; only override locally if you need per-project branding. |

## [#not-published-to-maven-central](#not-published-to-maven-central)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](https://ike.network/)[8] for the foundation/examples split.

## [#resources](#resources)Resources

| Resource | URL |
| --- | --- |
| Source repository | [https://github.com/IKE-Network/doc-example](https://github.com/IKE-Network/doc-example)[9] |
| Cross-project issue tracker | [https://github.com/IKE-Network/ike-issues](https://github.com/IKE-Network/ike-issues)[10] |
| IKE Network landing page | [https://ike.network/](https://ike.network/)[8] |
| IKE Docs (renderer pipelines, `idoc:*` plugin) | [https://ike.network/ike-docs/](https://ike.network/ike-docs/)[7] |
| IKE Platform (parent POM, BOM, workspace plugin) | [https://ike.network/ike-platform/](https://ike.network/ike-platform/)[3] |
| Sibling: code+docs template | [https://ike.network/example-project/](https://ike.network/example-project/)[4] |
| Sibling: workspace-aggregator template | [https://ike.network/ike-example-ws/](https://ike.network/ike-example-ws/)[5] |