Getting Started

This template is designed to be used as a base for your showroom lab guides.

The content is built using Antora, a static site generator for creating documentation sites from AsciiDoc documents.

This git repo template was created to make it easy for you to start developing your lab instructions.

Features:

1. 0% cruft

2. Red Hat Demo Platform UI Bundle default

3. Dev Mode extension that displays the asciidoc attributes you have to work with

4. Content is generated using Antora, a static site generator for creating documentation sites from AsciiDoc documents.

Getting Started

Using Containers (Recommended)

In order to test and develop on your local machine, you can use a specially built container with Podman or Docker as follows.

1. Create a git repo from this template

   1. Suggested naming: showroom_<lab-name>

2. Clone your new repo and cd into it

3. When you make changes to the content, all you need is to kill the container and run it again.

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

For SELinux environments, :z may need to be appended to the volume mount:

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

Live-reload is not supported.

Using Local Files (Less Recommended)

1. Create a git repo from this template

2. Clone the repo and cd into it

3. Run ./utilities/lab-serve

4. Open http://localhost:8080 in your browser

5. Run ./utilities/lab-build to build your html

To rebuild your html, run ./utilites/build.

Using Podman Compose (live reload supported)

1. Run podman-compose up --build to start the container

2. Open http://localhost:8080 in your browser

3. Live reload is supported, edit the content and refresh the page to see the changes

Editing Files

Now you are ready to go! You can start editing the files in the content/modules/ROOT/pages/ directory.

Many modern editors such as Visual Studio Code offer live Asciidoc Preview extensions.

Understanding the Basic Template Directory Structure

./content/modules/ROOT/
├── assets
│   └── images                       # Images used in your content
│       └── example-image.png
├── examples                         # You can add downloadable assets here
│   └── example-bash-script.sh       # e.g. an example bash script
├── nav.adoc                         # Navigation for your lab
├── pages                            # Your content goes here
│   ├── index.adoc                   # First page of your lab, e.g. overview etc
│   ├── module-01.adoc
│   └── module-02.adoc               # Sample lab has 2 modules including index.adoc
└── partials                         # You can add partials here, reusable content inserted inline into your modules
    └── example_partial.adoc

Adding Additional Links

You can add links to external content in the convenient "Links" drop-down on the upper-right of the Showroom Summit 2024 UI.

./content/antora.yml

asciidoc:
  attributes:
    page-links:
    - url: https://redhat.com
      text: Red Hat

Dev Mode

As a convenience to developers, the Dev Mode Extention (disabled by default) displays the asciidoc attributes you have to work with while writing your lab instructions.

1. Disable/Enable Dev Mode by changing enabled: true or enabled: false

   default-site.yml

   extensions:
     - id: dev-mode
       require: ./content/lib/dev-mode.js
       enabled: false

2. Produces

   

Using Claude Skills for Content Generation

This repository includes Claude skills to help you create professional Red Hat workshop and demo content.

Option 1: Using Cursor IDE (Recommended for Teams)

If you have Cursor with Claude access:

1. Clone this repository and open in Cursor

2. Open Cursor chat (Cmd+L or Ctrl+L)

3. Say simple commands:

   1. create lab - Create workshop modules

   2. create demo - Create demo content

   3. verify content - Verify content quality

   4. generate agv description - Generate AgnosticV catalog descriptions

For detailed Cursor setup, see CURSOR-SKILLS-README.adoc.

Option 2: Using Claude Code CLI

If you have Claude Code CLI installed:

1. Clone this repository and start a Claude Code session within the directory

2. Run /skills to list available skills

3. Run a skill by name: /create-lab, /create-demo, /verify-content, or /generate-agv-description

For detailed documentation on using Claude skills, see CLAUDE-SKILLS-GUIDE.adoc.