Prerequisites

In order to use the WTC Curriculum Toolchain, you need to install the following:

• Docker

• Docker Compose

• Make. For Windows OS, WSL is recommended.

• jq

Contributor’s Guide

All content is authored using AsciiDoc and published using Antora.

In Antora, a component consists of one or more modules. Each module consists of pages, images, examples, etc.

Important

A breakdown of the contribution process and helpful links are given on the curriculum site.

Installing dependencies

Run make install to install supported AsciiDoc extensions.

Build and preview the content

Run make preview and open http://localhost:8051/ to view the component on your local machine.

This first runs make clean, then make build then make preview. The clean target deletes the build/site and build/cache directories for a clean build. The build target builds a local copy of the component. The output is placed in the build/site directory. The preview target serves build/site on http://localhost:8051/

Watching for file changes

In a terminal, run make preview to start up the local HTTP server for the component. Then, in another terminal, run make watch. This will watch for local file changes in the content directories and rebuild the local site. Refresh the page in the browser to see the changes.

Updating the UI

Run make ui to pull the latest UI package.

Updating the tools

Run make tools to pull the latest changes from the curriculum-tools repository.

If you come across any merge conflicts, resolve them in VS Code and commit when you are done.

Content Tips

Font-Awesome

Support for inline icons using Font-Awesome is enabled. See https://asciidoctor.org/docs/user-manual/#inline-icons

Diagram Markup

Support via https://kroki.io/ is enabled. Also see https://github.com/Mogztter/asciidoctor-kroki.

For example:

[plantuml]
----
alice -> bob
bob -> alice
----

Release Manager Guide

Installing dependencies

Run make install to install supported AsciiDoc extensions.

Creating the release outline

In the release-outline folder, create two documents using the release number:

• nav-1.adoc

• release-1.txt

In release.txt, list the paths to the pages or modules you wish to release from the modules directory under the content directory (make sure there is an empty line at the end of the file):

ROOT
001-fizzbuzz
002-hangman

In nav.adoc, create the full navigation as you would like it to appear for that release:

* xref:release-notes.adoc[Release Notes]
* xref:index.adoc[Overview]
* xref:setup.adoc[Development Setup]
* xref:intro-to-java.adoc[Introduction to Java]
* xref:unit-testing-with-java.adoc[Unit Testing with Java]
** xref:exercise-fizzbuzz.adoc[Exercise: FizzBuzz icon:code[] ]

Releasing content

Run make release with the release number to clean the release folder and copy over the appropriate navigation and content (e.g. make release 5).

Build and preview the content

Run make preview PLAYBOOK=release and open http://localhost:8051/ to view the component on your local machine.

This first runs make clean, then make build then make preview. The clean target deletes the build/site and build/cache directories for a clean build. The build target builds a local copy of the component. The output is placed in the build/site directory. The preview target serves build/site on http://localhost:8051/

Updating the UI

Run make ui to pull the latest UI package.

Updating the tools

Run make tools to pull the latest changes from the curriculum-tools repository.

If you come across any merge conflicts, resolve them in VS Code and commit when you are done.