Creating a Content Repository

A Showroom content repository is an Antora project that contains your lab instructions written in AsciiDoc. The Showroom platform clones, builds, and serves this content at runtime.

Start from the Template

The recommended starting point is showroom_template_nookbag.

  1. In GitHub, click Use this template to create a new repository. Suggested naming: showroom_<lab-name> (for example showroom_my-ansible-workshop).

  2. Clone your new repo locally.

  3. Replace the sample pages in content/modules/ROOT/pages/ with your own content.

The template gives you a clean structure with zero boilerplate and the Red Hat Demo Platform UI theme.

Directory Layout

your-content-repo/
├── content/
│   ├── antora.yml              (1)
│   ├── supplemental-ui/        (2)
│   │   └── partials/
│   └── modules/ROOT/
│       ├── nav.adoc            (3)
│       ├── assets/images/      (4)
│       ├── examples/           (5)
│       ├── pages/              (6)
│       │   ├── index.adoc
│       │   ├── module-01.adoc
│       │   └── module-02.adoc
│       └── partials/           (7)
├── site.yml                    (8)
└── ui-config.yml               (9)
1 Antora component descriptor — defines the component name, version, navigation, and default AsciiDoc attributes.
2 Custom CSS or HTML partials that override the UI theme.
3 Navigation file — controls the sidebar table of contents.
4 Images referenced from your AsciiDoc pages.
5 Downloadable files (scripts, configs) that readers can copy.
6 Your lab pages — one AsciiDoc file per module or section.
7 Reusable AsciiDoc snippets you can include inline.
8 Antora playbook — uses the Red Hat theme.
9 Showroom UI configuration — defines tabs, layout width, and dynamic URLs. See UI Configuration.

The Antora Component Descriptor (antora.yml)

The content/antora.yml file is the heart of your Antora component. Here is a minimal example:

name: modules
title: My Workshop Title
version: master
nav:
  - modules/ROOT/nav.adoc

asciidoc:
  attributes:
    lab_name: My Workshop
    guid: '%GUID%'
    ssh_user: lab-user
    ssh_password: changeme
    page-pagination: true

AsciiDoc Attributes and Variable Injection

At deploy time, Showroom replaces attribute placeholders with real runtime values from user_data. This means you can write:

SSH to the bastion:

[source,bash,subs="attributes"]
 ssh {ssh_user}@{bastion_public_hostname}

And the rendered page will show the actual username and hostname for each lab participant.

The full list of available attributes depends on what your infrastructure roles write into user_data. See User Data and Variables for the complete flow.

Provide sensible defaults in antora.yml so the content renders correctly during local development and in CI previews.

Antora Playbook (site.yml)

Your content repo needs an Antora playbook file — typically site.yml. This file tells Antora where to find your content, which UI theme to use, and where to write the output.

The Showroom Antora container image auto-detects the playbook at build time, preferring site.yml and falling back to default-site.yml. You can override the filename in your AgnosticV config:

ocp4_workload_showroom_content_antora_playbook: site.yml

Navigation (nav.adoc)

The content/modules/ROOT/nav.adoc file defines the sidebar navigation:

* xref:index.adoc[Lab Overview]

* xref:module-01.adoc[1. Getting Started]
* xref:module-02.adoc[2. Deploy the Application]

Pages not listed in nav.adoc are still accessible by URL but will not appear in the sidebar (unless dev-mode is enabled).

Dev Mode

Dev mode is a built-in diagnostic tool that every content developer should enable during development. When active, it:

  • Adds an Attributes reference page listing every AsciiDoc attribute and its current value — invaluable for verifying that variable injection works correctly.

  • Shows unlisted pages (pages not in nav.adoc) in the sidebar under a Dev Mode section, so you can navigate to work-in-progress pages without adding them to the navigation yet.

Enabling dev mode

Add a single line to your catalog item’s dev.yaml:

OCP4 workload VM workload 
ocp4_workload_showroom_enable_dev_mode: true
 
showroom_enable_dev_mode: true
Always enable dev mode in dev.yaml, never in common.yaml or prod.yaml. It is a development-time aid and must not be visible to end users in production.
The working examples in tests/showroom-ocp4/dev.yaml and tests/showroom-vm/dev.yaml in agnosticv both enable dev mode — use them as a reference.

You can also expose dev mode as a catalog parameter so it can be toggled from the demo.redhat.com order form. See OCP4 Dev Mode or VM Dev Mode for the full variable reference and catalog parameter examples.

In local development

Dev mode is not available when running Antora locally. The dev-mode.js extension is bundled inside the Showroom Antora container image and injected at build time — it is not part of the content repository.

To verify your AsciiDoc attributes locally, inspect content/antora.yml directly or deploy to RHDP with dev mode enabled.

Local Development

Option 1: Podman / Docker (recommended)

cd your-content-repo
podman run --rm --name antora -v $PWD:/antora -p 8080:8080 -i -t ghcr.io/juliaaano/antora-viewer

On SELinux-enabled systems, append :z to the volume mount:

podman run --rm --name antora -v $PWD:/antora:z -p 8080:8080 -i -t ghcr.io/juliaaano/antora-viewer

Open http://localhost:8080 in your browser. Live reload is not supported — stop and restart the container after making changes.

Option 2: Podman Compose (live reload)

If your template includes a podman-compose.yaml:

podman-compose up --build

Open http://localhost:8080. Edit content files and refresh the browser to see changes.

Option 3: Local Antora CLI

If you have Node.js and Antora installed:

./utilities/lab-build      # build HTML
./utilities/lab-serve      # serve on http://localhost:8080

Adding External Links

You can add links to external resources (documentation, product pages, etc.) in the Showroom UI links dropdown. Add them to content/antora.yml:

asciidoc:
  attributes:
    page-links:
      - url: https://docs.redhat.com
        text: Red Hat Documentation
      - url: https://access.redhat.com
        text: Red Hat Customer Portal

Extensions

Showroom content images include the Mermaid extension for Antora, which lets you embed diagrams and visualizations written in text directly in your AsciiDoc pages.

Add the extension to your site.yml playbook:

antora:
  extensions:
    - require: '@sntke/antora-mermaid-extension' (1)
      mermaid_library_url: https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs (2)
      script_stem: header-scripts (3)
      mermaid_initialize_options: (4)
        start_on_load: true
1 The Antora extension package (pre-installed in the Showroom Antora image).
2 The Mermaid JS library loaded by the browser.
3 Injects the script tag into the HTML <head>.
4 Mermaid initialisation options — start_on_load renders diagrams automatically.

Then use a [mermaid] block in your AsciiDoc pages:

[mermaid]
\....
sequenceDiagram
autonumber

participant a as Alice
participant b as Bob

a ->>+ b : Hello.
b -->>- a : Hi, there.
\....

Creating Content with AI Tools

The RHDP Skills Marketplace provides skills for generating and validating Showroom content using Claude Code or Cursor IDE.

Install the marketplace skills, then use:

Skill What it does

/showroom:create-lab

Generate workshop modules from reference materials with AsciiDoc formatting.

/showroom:create-demo

Generate presenter-led demo content with Know/Show structure.

/showroom:verify-content

Validate content against Red Hat standards (style, AsciiDoc, scaffold files).

/showroom:blog-generate

Convert completed modules into blog posts.

See the RHDP Skills Marketplace README for setup instructions.

Next Steps