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 — do not modify; uses the Red Hat theme and extension settings managed by the template.
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. See the Attribute Injection Example page for a live demonstration of attribute injection.

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.

Do not modify site.yml. It contains settings that must not change — the UI theme, extensions, and output path are managed by the template. All content-specific configuration (AsciiDoc attributes, navigation, component metadata) belongs in content/antora.yml.

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.
\....

The diagram above renders as:

sequenceDiagram autonumber participant a as Alice participant b as Bob a ->>+ b : Hello. b -->>- a : Hi, there.

AsciiDoc Experimental Features (UI Macros)

The experimental AsciiDoc attribute unlocks three UI macros for documenting user interactions: buttons, keyboard shortcuts, and menu selections. These render with distinct styling so readers can instantly recognise interactive elements.

Enabling experimental

Add experimental: true to the asciidoc.attributes section of your content/antora.yml:

asciidoc:
  attributes:
    experimental: true
The template already includes experimental: true in the default content/antora.yml. In AsciiDoc, setting an attribute to an empty string ('') is equivalent to true — both forms activate the experimental macros.

Button Macro — btn:[]

Use the button macro to represent a clickable UI button.

AsciiDoc source Rendered output 
Press btn:[Save] to commit your changes.

Press Save to commit your changes.

 
Click btn:[OK] or btn:[Cancel].

Click OK or Cancel.

Keyboard Macro — kbd:[]

Use the keyboard macro to display key presses and shortcuts. Separate individual keys with +.

AsciiDoc source Rendered output 
Press kbd:[Enter] to confirm.

Press Enter to confirm.

 
Copy text with kbd:[Ctrl+C] and paste
with kbd:[Ctrl+V].

Copy text with Ctrl+C and paste with Ctrl+V.

 
On macOS, use kbd:[⌘+Shift+P] to open
the command palette.

On macOS, use ⌘+Shift+P to open the command palette.

 
Press kbd:[Ctrl+Alt+Delete] to open
the security screen.

Press Ctrl+Alt+Delete to open the security screen.

Menu Macro — menu:[]

Use the menu macro to describe a sequence of menu selections. The top-level menu goes before the colon; submenus and the final item go inside the square brackets, separated by >.

AsciiDoc source Rendered output 
Select menu:File[Save].

Select File  Save.

 
Navigate to menu:File[New > Project]
to create a new project.

Navigate to File  New  Project to create a new project.

 
Open menu:Edit[Preferences > Plugins]
to manage extensions.

Open Edit  Preferences  Plugins to manage extensions.

 
Go to menu:View[Appearance > Color Theme]
to change the editor theme.

Go to View  Appearance  Color Theme to change the editor theme.

Quick Reference

Macro Syntax Example output

Button

btn:[Label]

Save

Keyboard (single key)

kbd:[Key]

Esc

Keyboard (combo)

kbd:[Key1+Key2]

Ctrl+S

Keyboard (three keys)

kbd:[Key1+Key2+Key3]

Ctrl+Shift+T

Menu (one level)

menu:Top[Item]

File  Save

Menu (nested)

menu:Top[Sub > Item]

File  Export  PDF

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