Module 1: Showroom in action

Learning objectives

By the end of this module, you will:

  • Describe what a Showroom is and the two delivery models (RHDP and GitHub Pages)

  • Identify the two content types: hands-on labs and presenter-led demos

  • View the AsciiDoc source behind a rendered Showroom page

  • Understand how content maps from source files to what learners see

What is Showroom?

Red Hat Showroom is a platform for delivering interactive, hands-on workshops in the browser. Content is written in AsciiDoc, stored in a Git repository, and rendered by Antora (a documentation site generator).

Showroom supports two delivery models:

Model What the learner gets When to use

RHDP deployment

Split-pane UI with embedded terminals, OpenShift consoles, and clickable execute blocks that send commands directly to a terminal

Production workshops on the Red Hat Demo Platform

GitHub Pages

Rendered AsciiDoc content with navigation, pagination, and copy-to-clipboard code blocks

Sharing content, previewing, standalone tutorials like this one

This lab uses the GitHub Pages model. You are reading it right now.

Exercise 1: Explore this Showroom

You are inside a working Showroom. Take a moment to explore the interface:

  1. Navigation sidebar (left): Click through the module titles to see how the lab is organized

  2. Pagination (bottom): Scroll to the bottom and notice the "Next" and "Previous" links

  3. Content formatting: Notice the headings, numbered steps, code blocks, tables, and admonition boxes like the NOTE on the index page

All of this is generated from AsciiDoc files in a Git repository.

Verify

Confirm you can navigate between pages using the sidebar and pagination links. You should be able to reach every module from the navigation.

Exercise 2: View the source

Let’s look at the AsciiDoc source behind this page.

  1. Open the repository for this lab in a new browser tab:

    github.com/rhpds/showroom-getting-started-showroom

  2. Navigate to content/modules/ROOT/pages/03-module-01-showroom-in-action.adoc

  3. Compare what you see rendered here (in the browser) with the AsciiDoc source on GitHub. Notice how:

    • = Module 1: Showroom in action becomes the page title

    • == Exercise 1: becomes a section heading

    • Numbered steps use the . prefix

    • Bullet points use the * prefix

    • Code blocks are wrapped in ---- fences

    • Links use the text syntax (the ^ opens in a new tab)

  4. Now look at content/modules/ROOT/nav.adoc — this file controls the sidebar navigation you see on the left

  5. Look at site.yml — this sets the site title and theme

  6. Look at ui-config.yml — this configures the right-side tabs (in RHDP deployments, this would include a Terminal tab)

Verify

You can now identify:

  • Where the content lives (content/modules/ROOT/pages/)

  • How navigation is defined (nav.adoc)

  • How the site is configured (site.yml, ui-config.yml)

Exercise 3: Understand the content structure

Every Showroom repository follows the same directory layout:

your-showroom/
├── site.yml                           # Antora playbook: title, theme, extensions
├── ui-config.yml                      # Showroom UI: tabs, split view, width
├── content/
│   ├── antora.yml                     # Component descriptor: title, attributes
│   └── modules/
│       └── ROOT/
│           ├── nav.adoc               # Sidebar navigation
│           ├── pages/                 # Your AsciiDoc content files
│           ├── assets/images/         # Screenshots and diagrams
│           └── partials/              # Reusable snippets and shared attributes
└── examples/                          # Templates and examples (reference material)

The four key configuration files:

  1. site.yml — Sets the site title, Antora theme, and extensions. You rarely change anything beyond the title.

  2. content/antora.yml — Defines the component title and AsciiDoc attributes (variables like {openshift_console_url} that get replaced at deploy time).

  3. ui-config.yml — Configures the Showroom split-pane UI: which tabs appear, default width, and view mode. On GitHub Pages this has limited effect, but it is critical for RHDP deployments.

  4. content/modules/ROOT/nav.adoc — Controls the sidebar navigation. Without an entry here, a page is invisible to learners.

Verify

You understand the four configuration files and their roles. In the next module, you will create and configure all of them for your own Showroom.

Two types of Showroom content

Before you start building, it helps to know that Showroom supports two content types:

Labs (created with /showroom:create-lab):

  • Self-paced, hands-on exercises

  • Learners follow step-by-step instructions and run commands

  • Each exercise has verification steps so learners confirm success

  • Best for: workshops, training, enablement

Demos (created with /showroom:create-demo):

  • Presenter-led walkthroughs

  • Follow a Know/Show structure: brief concept explanation, then live demonstration

  • Include presenter notes and timing guidance

  • Best for: customer demos, technical briefings, sales engineering

You will create a lab in Module 3. If you want to also create a demo, continue to the optional Module 4.

Learning outcomes

By completing this module, you should now understand:

  • Showroom delivers AsciiDoc content from a Git repository, rendered by Antora

  • Two delivery models exist: RHDP deployment (split-pane with terminals) and GitHub Pages (standalone content site)

  • Two content types exist: hands-on labs and presenter-led demos

  • The content repository has a standard directory layout with four key configuration files

  • What you see rendered in the browser maps directly to AsciiDoc source files on GitHub

What’s next

Now that you understand how Showroom works, it’s time to build your own. Open your terminal — the next module is all hands-on.