Overview
You will learn
- Which alert designators the platform recognizes and when to reach for each
- How to use collapsible DETAILS, TROUBLESHOOT, HINT, SOLUTION, and RESULT callouts
- How to blur an answer inline with
:spoiler[...] - How the
:::type[Title]directive form maps to the blockquote form
Prerequisites
- Familiarity with the basic tutorial markdown structure (see v2-example-tutorial)
Steps
The five standard alert types (NOTE, TIP, IMPORTANT, WARNING, CAUTION) are non-collapsible and render with an icon. Use them for emphasis, not decoration.
Any alert type accepts an optional title after the designator:
DETAILS is a collapsible section. A title is required. By default the section starts
closed; append + to start it open.
Details: Closed by default — click to expand
This content is hidden until the reader clicks the heading.
It can contain multiple paragraphs, lists, and code blocks.
key: value[!DETAILS+] Open by default — click to collapse This content is visible immediately. Use
+when the reader is likely to need the content on a first pass but it would clutter the step if always-visible.
TROUBLESHOOT callouts are collapsible and contribute to the auto-generated troubleshooting index at the bottom of the tutorial. A title is optional but recommended.
Troubleshoot: cds watch exits immediately with “No service definition found”
Ensure at least one .cds file in srv/ contains a service definition. Check that
package.json lists the correct cds.roots paths.
ls srv/*.cdsIf the folder is empty, you may have cloned the wrong branch.
Troubleshoot: Port 4004 is already in use
Another cds watch process is running. Kill it first:
npx kill-port 4004RESULT marks the expected outcome after completing an action. It has a default title of “You should see” and a checkmark icon. Place it immediately after the action step.
Run the build:
npm run buildYou can also provide a custom title:
Note: Automatic verification links (assert-link) for RESULT callouts are deferred to a follow-up feature.
Multiple HINT callouts in the same step unlock one at a time — the reader must open the first before the second becomes visible. Place SOLUTION at the end of the exercise.
Exercise: What CAP annotation marks a service endpoint as read-only?
Hint:
Look at the service definition in srv/cat-service.cds.
Hint:
The annotation starts with @readonly.
Hint:
It is placed before the entity projection inside the service block.
Solution:
Add @readonly before the entity projection:
service CatalogService {
@readonly entity Books as SELECT from my.Books;
}Use :spoiler[text] to blur an answer inline — useful for quiz-style prompts:
Which SAP framework is used to build cloud-native business applications? CAP (Cloud Application Programming Model)
In plain-text contexts (MCP tool, email) the spoiler renders as ||CAP (Cloud Application Programming Model)||.
The :::details[Title] directive syntax is equivalent to > [!DETAILS] Title and is
useful when the body contains content that is awkward inside a > blockquote:
Details: Full configuration file
cds:
requires:
db:
kind: hana
features:
ieee754compatible: trueAll collapsible callout types have a :::type[Title] directive equivalent. This form is
interchangeable with the blockquote form.
Hint: Need a hint?
cds.ql query examples.Solution: Full solution
const books = await SELECT.from('my.Books').where({ author_ID: authorId })Troubleshoot: Module not found: @sap/cds
npm install to restore node_modules, then verify @sap/cds is listed in
dependencies (not devDependencies) in package.json.Resources
Discussion
Share feedback on this tutorial or join the conversation in SAP Community.