Tutorial Platform Feature Cookbook

When a step’s variants are about the operating system, the platform auto-detects this and wires every OS block on the page to a single global picker at the top of the tutorial. The reader picks their OS once, and that choice persists across tutorials.

The body of this step uses the syntax — change the OS picker at the top of the tutorial and the visible block below changes too:

The platform recognizes Windows, macOS / Mac OS / Mac / OS X / Darwin, Linux / Ubuntu / Debian / Fedora / Unix, and BAS / Business Application Studio / SAP BAS as OS labels. Combined labels like Mac and Linux or Mac & Linux match both. For the full taxonomy and override syntax, see writing-tutorials.md §3.5.2.

When the variants are not about the OS — JSON vs XML, Java vs Node, Cloud vs On-premise — the platform renders them as per-step tabs that don’t wire into the global picker. Each step’s tabs are independent of every other step’s tabs.

The block source looks identical to the OS form; the only difference is the labels. The platform’s auto-detection differentiates OS vs generic blocks by label content — labels matching the OS taxonomy auto-wire to the global picker, any other labels render as per-step tabs.

{ "type": "object", "properties": { "id": { "type": "integer" } } }

<object><id type="integer"/></object>

If you have a tab that’s named like an OS but isn’t actually OS-conditional (e.g. a “Linux” tab that’s about a Linux container product, not the operating system), use the osOverrides frontmatter key documented in writing-tutorials.md §3.5.2 to force a step’s group back to per-step tabs.

When a tutorial has a fork that the reader picks — HANA vs PostgreSQL, Java vs Node, on-prem vs cloud — use BRANCH markers to define alternative step-runs. Unlike OPTION blocks (which split a single step into per-tab variants), BRANCH blocks split a run of subsequent content into pickable paths. See the full syntax reference at https://github.com/sap-tutorials/tutorials-ims/blob/main/docs/authors/branched-tutorials.md.

You’ll deploy to either HANA Cloud or PostgreSQL. Pick the runtime your team uses.

Each branch starts a fresh sub-step; consecutive sibling BRANCH blocks with matching group= form one pickable group. The reader picks once per group, and their pick persists across page loads via local storage.

When the learner has already completed prerequisite content elsewhere — finished a Node Getting Started tutorial earlier in the mission, say — you can mark a step as auto-skippable. The reader sees a Skip this step button and an explanation of why, but always has the option to read through anyway.

The syntax is a per-step HTML-comment frontmatter block:

### Install Node.js

<!--
skipIf: "completed:node-getting-started"
skipLabel: "Already installed"
skipReason: "You completed the Node Getting Started tutorial earlier."
-->

Step body...

skipIf is a predicate against completion state; skipLabel is the text on the button; skipReason is the explanation text. Within a single tutorial there’s no other step to refer to, so this cookbook can only show the syntax — full skip-run behavior requires multiple tutorials in a mission, where one tutorial’s completion state can satisfy another’s skipIf.

Use the mermaid shortcode to embed flowcharts, sequence diagrams, ER diagrams, and so on. The platform renders them inline using the Horizon palette so they match the rest of your tutorial visually.

flowchart LR
  Author -->|writes markdown| GitHub
  GitHub -->|repo dispatch| CI
  CI -->|fetch + build + publish| HANA
  HANA -->|serves HTML| Reader

The shortcode renders the diagram lazily — it’s not loaded on first paint, so a tutorial without diagrams pays no cost. Tutorials with diagrams load the mermaid library only when the diagram scrolls into view.

The platform syncs language selection across consecutive code fences with different language tags. Pick js once and the next code block in the same step also defaults to js; the reader’s choice persists across the tutorial via local storage.

// Define a CDS service handler in JavaScript
module.exports = (srv) => {
  srv.before('CREATE', 'Books', (req) => {
    if (!req.data.title) req.reject(400, 'Title required');
  });
};

// The same handler in TypeScript — picking 'js' above defaults this block to 'ts'
import cds from '@sap/cds';
export default (srv: cds.Service) => {
  srv.before('CREATE', 'Books', (req) => {
    if (!req.data.title) req.reject(400, 'Title required');
  });
};

// And the CDS model the handler operates on
entity Books : managed {
  key ID : Integer;
  title  : localized String(111);
}