Building the courseware

This site serves a get started guide for the courseware development. The course and site are built using ASCIIDoc and Antora. Though this guide provides some quick starts for any detailed information, its better to refer to official docs.

Glossary

component

The site is referred to as component. Each component is dentified by an antora.yml.

module

Logicial grouping site docs. The component can have one more modules under modules directory. It should have atleast one module called ROOT, which is default module.

site

A site i.e. that site that will be published is combination of one or more components via content  sources of the site playbook. The following listing shows the aggrgated site example:

runtime:
  cache_dir: ./.cache/antora

site:
  url: http://localhost:3000/rhs-build-course/index.html
  start_page: demo-tutorial::index.adoc

content:
  sources:
    - url: . (1)
      branches: HEAD (2)
      start_path: documentation (3)
    - url: https://github.com/redhat-developer-demos/tekton-tutorial (4)
      branches: scholars-demo
      start_path: documentation
asciidoc:
  attributes:
    tutorial-namespace: demo
  extensions:
    - ./lib/remote-include-processor.js
    - ./lib/tab-block.js

ui:
  bundle:
    url: https://github.com/redhat-scholars/course-ui/releases/download/v0.1.3/ui-bundle.zip
    snapshot: true
  supplemental_files:
    - path: ./supplemental-ui
    - path: .nojekyll
    - path: ui.yml
      contents: 'static_files: [ .nojekyll ]'

output:
  clean: true
  dir: ./gh-pages
1 The site aggregates sources from the current path .
2 The branch to be used
3 The path where to start scanning for site modules.
4 Another remote site content from https://github.com/redhat-developer-demos/tekton-tutorial. The content aggregation will be done from branch scholars-demo of remote GitHub repo.

For this course, each project has two site files:

  • site.yml: This is the main site playbook that will be used to generate the site-pages.

  • dev-site.yml: This is the development site playbook that will be used to do local site development.