= Template for https://isaqb.org[iSAQB] Advanced Level Curricula

== Status
image:https://github.com/isaqb-org/advanced-template/actions/workflows/build_main.yml/badge.svg?branch=main["CI – Releases and Main"]
image:https://img.shields.io/github/last-commit/isaqb-org/advanced-template/main.svg["Last commit"]
image:https://img.shields.io/github/contributors/isaqb-org/advanced-template.svg["Contributors",link="https://github.com/isaqb-org/advanced-template/graphs/contributors"]
image:https://img.shields.io/github/issues/isaqb-org/advanced-template.svg["Issues",link="https://github.com/isaqb-org/advanced-template/issues"]
image:https://img.shields.io/github/issues-closed/isaqb-org/advanced-template.svg["Issues closed",link="https://github.com/isaqb-org/advanced-template/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aclosed+"]

This is <<copyrighted,copyrighted work>>.

== What is this repository?

This is the *GitHub template repository* for authoring https://isaqb.org[iSAQB] Advanced Level *curricula* in AsciiDoc.

Each real curriculum (e.g. `curriculum-flex`, `curriculum-web`) is created from this
template and then customized. The build produces PDF and HTML output in German (DE) and English (EN),
based on a set of AsciiDoc files.

== Repository structure

[cols="1,3a",options="header"]
|===
|Path |Purpose

|`docs/`
|The curriculum content. `curriculum-template.adoc` is the root structure file;
content is organized into `00a-preamble/`, `00b-basics/`, one `NN-module-block-N/`
directory per learning module, `20-examples/` and `99-references/`. Per-curriculum
configuration lives in `docs/config/setup.adoc`.

`docs/index.adoc` and `docs/index_rc.adoc` are the sources for the published landing
page (`index.html`) that lists the curriculum and links to the rendered HTML/PDF
outputs: `index.adoc` is used for a released version, while `index_rc.adoc` is the
release-candidate variant (adds GitHub status badges and a changelog link).

|`curriculum-build.sh` / `curriculum-build.bat`
|The build launcher. It pulls the pinned builder image and renders the curriculum into
`build/`. `.sh` for Linux/macOS, `.bat` for Windows.

|`build.config`
|The few per-curriculum build settings: `CURRICULUM_FILE`, `LANGUAGES`, `SUFFIX_TAGS`,
`PREPRESS` (see <<build-configuration>>).

|`license-copyright/` (submodule)
|Shared license and copyright text included into every curriculum.

|`docs-ext/`
|[OPTIONAL] Pre-rendered PDF translations in languages other than DE/EN (see
`docs-ext/EXTERNAL_DOCUMENTS_README.adoc`).

|`.github/workflows/`
|CI workflows that build and publish the curriculum on push and on release.
|===

The whole toolchain — Asciidoctor, asciidoctor-pdf and the iSAQB PDF and HTML themes —
lives in a prebuilt Docker image
(https://github.com/isaqb-org/curriculum-builder[isaqb-org/curriculum-builder]). Nothing
needs to be installed or vendored per curriculum; the image is pinned by tag and digest in
`curriculum-build.sh` and kept current by Renovate.

== How to build

Prerequisite: https://docs.docker.com/get-docker/[Docker]. Nothing else — no JDK, no Ruby.

Clone the repository (with submodules, for the license text):

[source,shell]
----
git clone git@github.com:isaqb-org/advanced-template.git --recursive
----

If you already cloned without `--recursive`, run `git submodule update --init --recursive`.

Build all languages and formats:

[source,shell]
----
./curriculum-build.sh        # Linux / macOS
curriculum-build.bat         # Windows
----

Build a single output — pass the format and language (and optionally a variant):

[source,shell]
----
./curriculum-build.sh pdf DE          # Linux / macOS
./curriculum-build.sh html EN
./curriculum-build.sh pdf DE REMARKS
----

[source,bat]
----
curriculum-build.bat pdf DE           rem Windows
curriculum-build.bat html EN
curriculum-build.bat pdf DE REMARKS
----

Output is written to `build/`, named `<CURRICULUM_FILE>-<lang>.pdf` / `.html`, together
with an `index.html` overview page. The launcher pulls the builder image on first run and
reuses it afterwards. After a successful build, review `build/index.html`.

[[build-configuration]]
=== Build configuration

`build.config` in the repository root holds the per-curriculum settings:

[cols="1,3a",options="header"]
|===
|Key |Meaning

|`CURRICULUM_FILE` |AsciiDoc root in `docs/` (without `.adoc`); also the output file name.
|`LANGUAGES`       |Space-separated languages to build. Default `DE EN`; drop one for a single-language curriculum.
|`SUFFIX_TAGS`     |Space-separated extra build variants, exposed as the `{suffix}` attribute. Empty = single build.
|`PREPRESS`        |PDF print/book layout (recto chapter starts + binding margins). `true` / `false`.
|===

Any key can be overridden for a single run via an environment variable, e.g.
`LANGUAGES="DE" ./curriculum-build.sh`.

[[creating]]
== Creating a new curriculum from this template

. Click *Use this template* in the GitHub UI.
. Rename `docs/curriculum-template.adoc` to match your curriculum, e.g. `docs/curriculum-flex.adoc`.
. In `build.config`, set `CURRICULUM_FILE` to that name *without* the `.adoc` suffix, e.g.
`curriculum-flex`.
. In `docs/config/setup.adoc`, set the curriculum metadata:
.. `:curriculum-short:` – your module abbreviation, e.g. `FLEX`.
.. `:curriculum-name:` – the full module title (set separately for DE and EN).
. Replace the README: delete this file and rename `README-curriculum.adoc` to
`README.adoc`, then fill in the placeholders. (The README you are reading describes the
*template*; `README-curriculum.adoc` is the starting point for *your* curriculum.)
. Build with `./curriculum-build.sh` and review the result under `build/index.html`.

== How to contribute or participate

Create an issue, a merge- or pull-request.

== Maintainers

This repository is currently maintained by Benjamin Wolf.

[[copyrighted]]
== Licensing and Copyright

include::license-copyright/LICENSE.adoc[]