Initial commit

.github/workflows/gh-pages.yml

@@ -0,0 +1,48 @@
+name: github pages
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths-ignore:
+      - "README.adoc"
+      - ".gitignore"
+
+permissions:
+  pages: write
+  id-token: write
+
+concurrency:
+  group: gh-pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+      - name: configure pages
+        uses: actions/configure-pages@v5
+      - name: setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.13.1
+      - name: install antora
+        run: npm install --global @antora/[email protected] @antora/[email protected]
+      - name: antora generate
+        run: antora generate default-site.yml --stacktrace
+      - name: upload pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: www
+  deploy:
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+    - name: deploy github pages
+      id: deployment
+      uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,38 @@
+# Ignore macOS system files
+.DS_Store
+
+# Ignore node_modules directory
+node_modules/
+
+# Ignore build output
+www/
+.cache/
+
+# Ignore IDE and editor files
+.vscode/
+.idea/
+
+# Ignore logs and temporary files
+*.log
+*.tmp
+
+# Ignore environment-specific files
+.env
+.env.local
+.env.*.local
+
+# Ignore sensitive or private information
+secrets.json
+
+# Ignore compiled binaries or executables
+*.exe
+*.dll
+*.so
+*.dylib
+*.core
+
+# Ignore package-lock.json for npm
+package-lock.json
+
+# Ignore yarn.lock for Yarn
+yarn.lock

README.adoc

@@ -0,0 +1,109 @@
+=== 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:
+
+. 0% cruft
+. Red Hat Demo Platform UI Bundle default
+. Dev Mode extension that displays the asciidoc attributes you have to work with
+. 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.
+
+. Create a git repo from this template
+.. Suggested naming: `showroom_<lab-name>`
+. Clone your new repo and `cd` into it
+. When you make changes to the content, all you need is to kill the container and run it again.
++
+[source,sh]
+----
+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)
+
+. Create a git repo from this template
+. Clone the repo and `cd` into it
+. Run ./utilities/lab-serve
+. Open http://localhost:8080 in your browser
+. Run ./utilities/lab-build to build your html
+
+To rebuild your html, run `./utilites/build`.
+
+== 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
+
+[source,sh]
+----
+./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
+[source,yaml]
+----
+asciidoc:
+  attributes:
+    page-links:
+    - url: https://redhat.com
+      text: Red Hat
+----
+
+image::ui-links.png[]
+
+== 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.
+
+. Disable/Enable Dev Mode by changing `enabled: true` or `enabled: false`
++
+.default-site.yml
+[source,yaml]
+----
+extensions:
+  - id: dev-mode
+    require: ./content/lib/dev-mode.js
+    enabled: false
+----
+
+. Produces
++
+image::dev-mode.png[]

content/antora.yml

@@ -0,0 +1,19 @@
+name: modules
+title: Default Title
+version: master
+nav:
+  - modules/ROOT/nav.adoc
+
+asciidoc:
+  attributes:
+    lab_name: "I'm the lab_name var"
+    release-version: master
+    page-pagination: true
+    my_var: "foo"
+    guid: my-guid
+    ssh_user: devops
+    ssh_password: devops
+    ssh_command: ssh [email protected]
+    page-links:
+    - url: https://redhat.com
+      text: Red Hat

content/lib/all-attributes-console-extension.js

@@ -0,0 +1,35 @@
+module.exports.register = function () {
+  this.once('contentClassified', ({ playbook, contentCatalog }) => {
+    const newPage = contentCatalog.addFile({
+      contents: Buffer.from('= New Page\n\nThis is the contents of a generated page.'),
+      path: 'content/modules/ROOT/pages/new-page.adoc',
+      version: '3.1',
+      src: {
+        path: 'content/modules/ROOT/pages/new-page.adoc',
+        component: 'antora',
+        version: '3.1',
+        module: 'ROOT',
+        family: 'page',
+        relative: 'new-page.adoc',
+      },})
+    console.log('site-wide attributes (as defined in playbook)')
+    console.log(playbook.asciidoc.attributes)
+    contentCatalog.getComponents().forEach((component) => {
+      component.versions.forEach((componentVersion) => {
+        getUniqueOrigins(contentCatalog, componentVersion).forEach((origin) => {
+          console.log(`${componentVersion.version}@${componentVersion.name} attributes (as defined in antora.yml)`)
+          console.log(origin.descriptor.asciidoc?.attributes || {})
+        })
+      })
+    })
+  })
+}
+
+function getUniqueOrigins (contentCatalog, componentVersion) {
+  return contentCatalog.findBy({ component: componentVersion.name, version: componentVersion.version })
+    .reduce((origins, file) => {
+      const origin = file.src.origin
+      if (origin && !origins.includes(origin)) origins.push(origin)
+      return origins
+    }, [])
+}

content/lib/attributes-page-extension.js

@@ -0,0 +1,16 @@
+module.exports.register = function ({ config }) {
+  this.once('contentClassified', ({ contentCatalog }) => {
+    const newPage = contentCatalog.addFile({
+      contents: Buffer.from('= New Page\n\nThis is the contents of a generated page.'),
+      path: 'content/modules/ROOT/pages/new-page.adoc',
+      src: {
+        path: 'content/modules/ROOT/pages/new-page.adoc',
+        component: 'antora',
+        version: '3.1',
+        module: 'ROOT',
+        family: 'page',
+        relative: 'new-page.adoc',
+      },
+    })
+  })
+}

content/lib/dev-mode.js

@@ -0,0 +1,85 @@
+'use strict'
+
+module.exports.register = function ({ config }) {
+  this.once('contentClassified', ({ playbook, contentCatalog }) => {
+    var pageDetails = {}
+    console.log('site-wide attributes (as defined in playbook)')
+    console.log(playbook.asciidoc.attributes)
+    let fileContents = "== Site Wide Attributes\n\n"
+    fileContents += `${playbook.asciidoc.attributes || {}}\n`
+    contentCatalog.getComponents().forEach((component) => {
+      component.versions.forEach((componentVersion) => {
+        getUniqueOrigins(contentCatalog, componentVersion).forEach((origin) => {
+          console.log(`${componentVersion.version}@${componentVersion.name} attributes (as defined in antora.yml)`)
+          pageDetails = { version: `${componentVersion.version}`, name: `${componentVersion.name}` }
+          console.log(origin.descriptor.asciidoc?.attributes || {})
+          fileContents += `== Component Wide Attributes\n\n`
+          fileContents += `Antora component version@name: \`${componentVersion.version}@${componentVersion.name}\`\n\n`
+          fileContents += `[source,json]\n----\n`
+          fileContents += JSON.stringify(origin.descriptor.asciidoc?.attributes || {}, null, 2)
+          fileContents += `\n----\n`
+        })
+      })
+    })
+    const newPage = contentCatalog.addFile({
+      contents: Buffer.from('= Attributes Page\n\nTo disable Dev Mode (this page) comment out the dev-mode.js extenion in the playbook (usually default-site.yml)\n\n' + fileContents),
+      path: 'modules/ROOT/pages/attrs-page.adoc',
+      src: {
+        path: 'modules/ROOT/pages/attrs-page.adoc',
+        component: pageDetails.name,
+        version: pageDetails.version,
+        // component: pageDetails.name || 'modules',
+        // version: pageDetails.version || 'master',
+        module: 'ROOT',
+        family: 'page',
+        relative: 'attrs-page.adoc',
+      },
+    })
+  })
+  // add new page to navigation
+  this.on('navigationBuilt', ({ contentCatalog }) => {
+    const { addToNavigation = true, devPagesHeading = 'Dev Mode' } = config
+    const logger = this.getLogger('dev-pages-extension')
+      contentCatalog.getComponents().forEach(({ versions }) => {
+        versions.forEach(({ name: component, version, navigation: nav, url: defaultUrl }) => {
+          const navEntriesByUrl = getNavEntriesByUrl(nav)
+          const unlistedPages = contentCatalog
+            .findBy({ component, version, family: 'page' })
+            .filter((page) => page.out)
+            .reduce((collector, page) => {
+              if ((page.pub.url in navEntriesByUrl) || page.pub.url === defaultUrl) return collector
+              // logger.warn({ file: page.src, source: page.src.origin }, 'detected unlisted dev page')
+              return collector.concat(page)
+            }, [])
+          if (unlistedPages.length && addToNavigation) {
+            nav.push({
+              content: devPagesHeading,
+              items: unlistedPages.map((page) => {
+                // logger.warn({ content: page, url: page.pub.url }, 'unlisted dev page details')
+                const navtitle = page.asciidoc.navtitle || page.src.stem
+                return { content: navtitle, url: page.pub.url, urlType: 'internal' }
+              }),
+              root: true,
+          })
+        }
+      })
+    })
+  })
+}
+
+function getUniqueOrigins (contentCatalog, componentVersion) {
+  return contentCatalog.findBy({ component: componentVersion.name, version: componentVersion.version })
+    .reduce((origins, file) => {
+      const origin = file.src.origin
+      if (origin && !origins.includes(origin)) origins.push(origin)
+      return origins
+    }, [])
+}
+
+function getNavEntriesByUrl (items = [], accum = {}) {
+  items.forEach((item) => {
+    if (item.urlType === 'internal') accum[item.url.split('#')[0]] = item
+    getNavEntriesByUrl(item.items, accum)
+  })
+  return accum
+}

content/lib/unlisted-pages-extension.js

@@ -0,0 +1,39 @@
+module.exports.register = function ({ config }) {
+  const { addToNavigation, unlistedPagesHeading = 'Unlisted Pages' } = config
+  const logger = this.getLogger('unlisted-pages-extension')
+  this
+    .on('navigationBuilt', ({ contentCatalog }) => {
+      contentCatalog.getComponents().forEach(({ versions }) => {
+        versions.forEach(({ name: component, version, navigation: nav, url: defaultUrl }) => {
+          const navEntriesByUrl = getNavEntriesByUrl(nav)
+          const unlistedPages = contentCatalog
+            .findBy({ component, version, family: 'page' })
+            .filter((page) => page.out)
+            .reduce((collector, page) => {
+              if ((page.pub.url in navEntriesByUrl) || page.pub.url === defaultUrl) return collector
+              logger.warn({ file: page.src, source: page.src.origin }, 'detected unlisted page')
+              return collector.concat(page)
+            }, [])
+          if (unlistedPages.length && addToNavigation) {
+            nav.push({
+              content: unlistedPagesHeading,
+              items: unlistedPages.map((page) => {
+                logger.warn({ content: page, url: page.pub.url }, 'unlisted page details')
+                const navtitle = page.asciidoc.navtitle || page.src.stem
+                return { content: navtitle, url: page.pub.url, urlType: 'internal' }
+              }),
+              root: true,
+            })
+          }
+        })
+      })
+    })
+}
+
+function getNavEntriesByUrl (items = [], accum = {}) {
+  items.forEach((item) => {
+    if (item.urlType === 'internal') accum[item.url.split('#')[0]] = item
+    getNavEntriesByUrl(item.items, accum)
+  })
+  return accum
+}