Use Authoring Aids to Annotate and Review Tutorials

Author notes let you leave comments for co-authors and reviewers directly in the tutorial markdown. They are stripped before the HTML reaches production readers.

An inline note sits on the same line as prose, delimited by %%:

Run the deployment command below %% @reviewer: confirm this works with SDK v4 — see issue #321 %% and wait for the output.

A block note spans multiple lines. A bare %% opens it and a bare %% closes it:

%%
@author: The screenshot below is from the old tenant. Replace once the
new BTP tenant is provisioned — tracked in https://github.com/sap-tutorials/…/issues/88.
%%

After you add a note, open the tutorial on the QA channel to verify it renders as a callout. When the content is finalized, remove the notes before promoting the tutorial to PROD.

Sometimes you want to leave instructions for your reviewer that are not part of the published content at all. Use a :::qa-only directive for this.

The block below is visible on the QA channel only. On PROD it is stripped entirely, including this sentence:

After reviewing the tutorial on QA, the block can stay in the source until the review is complete. Remove it (or leave it if it is permanently useful for future reviewers) before the final PROD push.

The tutorial platform runs lint-tutorial-markdown during npm run build:all. One of its rules, deprecated-cli, scans every shell code fence for known deprecated CLI commands.

The following example contains a deprecated cf push flag that the linter catches at build time:

cf push myapp --hostname myhost

The corrected command uses an application manifest instead:

# manifest.yml
applications:
  - name: myapp
    routes:
      - route: myhost.cfapps.eu10.hana.ondemand.com

cf push myapp

To run the linter locally against a single tutorial:

npx tsx scripts/lint-tutorial-markdown.ts directive-authoring-aids

Pass --strict if you want a non-zero exit code when findings are present (useful in CI pre-checks).