Source documentation for Payara Qube (self-hosted) and Payara Qube (Managed) (cloud service), built with Antora.

This repository uses conditional attributes to generate edition-specific documentation from a single codebase. The page-site-edition attribute (set to qube or cloud in playbook files) is evaluated in _attributes.adoc to determine which product name appears in the generated documentation.

.
├── docs/
│   ├── antora.yml                  # Component descriptor
│   └── modules/                    # Documentation modules
│       ├── ROOT/                   # Core documentation
│       │   └── partials/_attributes.adoc  # Product name definitions (source of truth)
│       ├── reference/              # API reference
│       ├── cli/                    # CLI documentation
│       ├── maven-plugin/           # Maven plugin
│       └── intellij-idea-plugin/   # IntelliJ plugin
│
├── qube.yml                        # Build config for Qube edition
├── cloud.yml                       # Build config for Cloud edition
│
├── validate-*.sh                   # Validation scripts
├── validate-docs.sh                # Master validator (runs all)
│
└── scripts/
    ├── install-hooks.sh            # Install git hooks
    └── pre-commit                  # Pre-commit validation

Prerequisites:

• Node.js
• Antora CLI: npm install -g @antora/cli @antora/site-generator

For Contributors:

1. Install git hooks (runs validators on commit):

   ./scripts/install-hooks.sh

2. Verify setup:

   ./validate-docs.sh

Build specific editions:

# Qube edition
antora qube.yml

# Cloud edition
antora cloud.yml

Output generates to build/html/ (or configured output directory).

Run all validators before submitting PRs:

./validate-docs.sh

Test the validators:

./test-product-names.sh

Product names are defined once in docs/modules/ROOT/partials/_attributes.adoc:

ifeval::["{page-site-edition}" == "qube"]
:productName: Payara Qube
:productEditionSlug: qube
endif::[]

ifeval::["{page-site-edition}" == "cloud"]
:productName: Payara Qube (Managed)
:productEditionSlug: cloud
endif::[]

Reference in content using {productName} instead of hard-coding product names.

Important: The reference module's _attributes.adoc is a symlink to ROOT's version. This ensures consistency across all modules.

1. Never hard-code product names - always use {productName} attribute
2. Run validation before committing - ./validate-docs.sh
3. Use edition-specific content blocks when content differs:

   ifeval::["{page-site-edition}" == "qube"]
   Self-hosted specific content here
   endif::[]
   
   ifeval::["{page-site-edition}" == "cloud"]
   Managed service specific content here
   endif::[]

4. Test both editions when making structural changes:

   antora qube.yml && antora cloud.yml

The GitHub Actions workflow (.github/workflows/validate-docs.yml) runs all validators on:

• Pull requests
• Pushes to main branches

Failed validation blocks merging.

Check docs/modules/ROOT/partials/_attributes.adoc has correct product names:

• Qube edition: Payara Qube
• Cloud edition: Payara Qube (Managed)

The reference module should symlink to ROOT:

cd docs/modules/reference/partials
rm _attributes.adoc
ln -s ../../ROOT/partials/_attributes.adoc _attributes.adoc

Ensure all xref: paths in nav.adoc files:

• Point to existing .adoc files
• Use correct relative paths from the pages/ directory
• Don't reference inter-module links without proper format (module:page.adoc)

Every ifdef, ifndef, or ifeval needs a matching endif::[]. Run:

./validate-conditionals.sh

1. Check the page exists in docs/modules/MODULE/pages/
2. Verify xref: syntax is correct
3. Ensure cross-module references use module:page.adoc format

[Add license information here]