Add agnostic spec-level admonition syntax (spec:warning)

[dannywillems]

Summary

Currently, the markdown flavor feature (#4) transforms between third-party documentation platform syntaxes (mdBook's ```admonish warning ↔ Docusaurus's :::warning). This ties the spec language to specific platforms.

Proposal

Add an agnostic admonition syntax to the spec language itself, similar to the existing spec:startcode / spec:endcode directives:

//~ spec:warning
//~ Be careful with this implementation.
//~ spec:endwarning

Or in templates:

spec:warning
Be careful with this implementation.
spec:endwarning

Supported admonition types

• spec:warning / spec:endwarning
• spec:info / spec:endinfo
• spec:note / spec:endnote
• spec:tip / spec:endtip
• spec:danger / spec:enddanger

Output transformation

The agnostic syntax would then be transformed based on the output flavor:

Spec syntax	mdBook output	Docusaurus output
spec:warning	```admonish warning	:::warning
spec:endwarning	```	:::

Benefits

1. Platform agnostic: Spec authors don't need to know the target platform
2. Consistent with existing syntax: Follows the spec: prefix convention
3. Future-proof: Easy to add new output formats without changing specs
4. Single source of truth: One syntax that works everywhere

Related

• PR Add Docusaurus markdown flavor support #4: Add Docusaurus markdown flavor support