feat: uniform layout and naming of hints, remarks, exceptions (#660) by SmilyOrg · Pull Request #860 · zalando/restful-api-guidelines

SmilyOrg · 2026-03-17T16:48:12Z

Summary

Converts ~119 inline bold labels (*Note:*, *Hint:*, *Exception:*, etc.) across 17 chapter files to native AsciiDoc admonition blocks (NOTE:, TIP:, [IMPORTANT], [WARNING], [EXCEPTION], [EXAMPLE])
Adds a Ruby extension (extensions/custom-admonitions.rb) for two new custom admonition types: EXCEPTION and EXAMPLE
Updates Makefile to load the extension during HTML build
Adds CSS for custom admonition icons and text labels beneath all admonition icons

Closes #660

Label mapping

Old label(s)	New admonition
`Note`, `Hint`, `Remark`, `Reasoning`	`NOTE`
`Important`	`IMPORTANT`
`Warning`	`WARNING`
`Exception`	`EXCEPTION` (new custom type)
`Example`, `Examples`	`EXAMPLE` (new custom type)

Test plan

Run make html — builds without errors
Open output/index.html and verify admonition blocks render with icons and labels
Verify EXCEPTION and EXAMPLE blocks render distinctly from NOTE/IMPORTANT
Spot-check mid-sentence label conversions read naturally
Check table cells for any rendering issues

🤖 Generated with Claude Code

Implements uniform layout and naming for hints, remarks, exceptions, and other call-out elements across all 17 chapter files. Replaces the mix of *Note:*, *Hint:*, **Important:**, etc. inline labels with proper AsciiDoc admonition blocks. Changes: - Add extensions/custom-admonitions.rb implementing EXCEPTION and EXAMPLE as custom Asciidoctor admonition block types - Update Makefile html target to load the custom extension via -r flag - Add CSS for custom admonition icons (.icon-exception, .icon-example) to zalando.css - Convert ~128 inline labels across 17 chapter files: * *Note:*, **Note:**, *Remark:* → NOTE: * *Hint:*, **Hint:**, Hint: → TIP: * *Important:*, **Important:** → IMPORTANT: * *Exception:*, **Exception:** → [EXCEPTION] delimited blocks * Example:, Examples: → [EXAMPLE] delimited blocks (where standalone) - Inline labels inside list items and table cells kept as-is (Pattern C) - Multi-paragraph notes use delimited [NOTE]==== blocks - Mid-sentence labels split into separate admonition paragraphs Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Reduce label font size from 0.6em to 0.38em and add 4px top margin to improve visual balance of text labels beneath admonition icons. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

SmilyOrg · 2026-03-17T16:52:43Z

I checked most instances and they look ok. I decided to add text under the icons to make it more obvious what each type means (especially exception & example are not very clear otherwise). The alternative I considered was having a legend on top in the "Conventions used in these guidelines" section, which we could use instead if this is considered too noisy.

tkrop · 2026-03-18T09:13:57Z

@SmilyOrg Thank you very much. This is a great progress and shows where we may going to. Still I would like us to improve on the design details.

In my opinion, the icons are too big and the text capital letter description is obtrusive. In addition the icon/description is not well positioned with respect to the warning/info/... text provided. Last the symbols and their colors does not fit to our general design.

@ALL Please state your opinions.

Co-authored-by: Tronje Krop <18184975+tkrop@users.noreply.github.com>

SmilyOrg · 2026-03-23T14:21:22Z

In my opinion, the icons are too big and the text capital letter description is obtrusive. In addition the icon/description is not well positioned with respect to the warning/info/... text provided. Last the symbols and their colors does not fit to our general design.

@tkrop I agree that it's not a great design. Note that the core styles have already been there, I guess they were just unused until now. What this PR adds is EXCEPTION and EXAMPLE styles, as well as the names below the icons.

Maybe we can gather example screenshots of what we think could look / work better and then give it another shot.

SmilyOrg · 2026-03-23T14:23:45Z

mkdocs examples

ePaul · 2026-04-14T13:28:52Z

Just so it's clear what we are talking about, here is what I see after building the branch locally:

I agree with Tronje that these icons are a bit large. I wonder whether it would be possible to move them somewhat into the margin, too?

tkrop · 2026-04-14T13:38:28Z

@SmilyOrg thanks for picking this up again.

Yes, I think starting with an mkdocs-like colored icons would fit our stile. I think, we will not be able to make the full boxes work like in mkdocs, because we have no headings for all the notes etc. However, what we should do is adding boxes around the text in the color oft icon and remove the small grey line between icon and text.

Whet is also important is the relation between the text sizes used inside and outside the boxes and the spaces. The current box character size is to close to the normal text size. It either needs to match the text size or be significantly smaller. In addition, the spacing needs to change/be proportional to the text size. In the current version neither the text size nor the spacing of the box is using a sensible working relation. For me it is currently looking disturbing.

tfrauenstein

Thank you for this big PR!
I proposed a longer list of changes (due to different reasons).

I think we should use EXAMPLE -- examples are already high-lighted by code-blocks and be have tons of examples that need to be changed consistently without readability value add.

tfrauenstein · 2026-04-14T15:19:19Z

  for details).

-*Hint:* The formerly used remote references to the `Problem` API fragment
+TIP: The formerly used remote references to the `Problem` API fragment


This NOTE should be moved to the end of this rule.

tfrauenstein · 2026-04-14T19:30:23Z

+transactional data copy or curated data products, for instance
+https://curated-product-data.docs.zalando.net/[curated product data [internal link]] or
+https://curated-sales-data.docs.zalando.net/[curated sales data [internal link]].
+====


Suggested change

====

tfrauenstein · 2026-04-14T19:36:25Z

 `query_hash`.

-*Note:* The efficiency of cursor-based pagination depends on the efficiency
+NOTE: The efficiency of cursor-based pagination depends on the efficiency


Suggested change

NOTE: The efficiency of cursor-based pagination depends on the efficiency

TIP: The efficiency of cursor-based pagination depends on the efficiency

tfrauenstein · 2026-04-14T19:37:52Z

 |=========================================

-*Remark:* In case of complex and long search requests, e.g. when
+NOTE: In case of complex and long search requests, e.g. when


Suggested change

NOTE: In case of complex and long search requests, e.g. when

*Remark:* In case of complex and long search requests, e.g. when

tfrauenstein · 2026-04-14T19:38:50Z

 Major changes are listed as "Rule Changes" below.

-*Hint:* Most recent major changes might be missing in the list since we update it 
+TIP: Most recent major changes might be missing in the list since we update it


Suggested change

TIP: Most recent major changes might be missing in the list since we update it

NOTE: Most recent major changes might be missing in the list since we update it

tfrauenstein · 2026-04-14T19:43:57Z

@@ -0,0 +1,22 @@
+# Registers EXCEPTION and EXAMPLE as custom admonition block types.
+# Reference: https://github.com/asciidoctor/asciidoctor-extensions-lab/issues/9


Suggested change

# Reference: https://github.com/asciidoctor/asciidoctor-extensions-lab/issues/9

# Reference: https://github.com/asciidoctor/asciidoctor-extensions-lab/issues/9

# we use the following admonitions in the guidelines: TIP NOTE IMPORTANT WARNING EXCEPTION

tfrauenstein

Thank you for this big PR!
I proposed a longer list of changes (due to different reasons).

I think we should use EXAMPLE -- examples are already high-lighted by code-blocks and be have tons of examples that need to be changed consistently without readability value add.

Co-authored-by: Thomas Frauenstein <thomas.frauenstein@zalando.de>

ePaul · 2026-06-09T12:51:01Z

From the meeting:

@tkrop doesn't like the style, feels that this is needed:

revert the font size change
improve icons
remove the line between icons and text

@tfrauenstein will change the font size, but will not touch the icons. That can be done later, if needed.
Thomas will focus on content changes.

SmilyOrg and others added 2 commits March 17, 2026 17:30

style: fine-tune admonition icon label size and spacing

c6a67dc

Reduce label font size from 0.6em to 0.38em and add 4px top margin to improve visual balance of text labels beneath admonition icons. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

SmilyOrg added the major Major feature changes or updates, e.g. feature rollout to a new country, new API calls. label Mar 17, 2026

SmilyOrg marked this pull request as ready for review March 17, 2026 16:49

SmilyOrg added the editorial label Mar 17, 2026

tkrop reviewed Mar 18, 2026

View reviewed changes

Comment thread chapters/http-requests.adoc Outdated

Update chapters/http-requests.adoc

78bcf3e

Co-authored-by: Tronje Krop <18184975+tkrop@users.noreply.github.com>

tfrauenstein reviewed Apr 14, 2026

View reviewed changes

Apply suggestions from code review

a3e6681

Co-authored-by: Thomas Frauenstein <thomas.frauenstein@zalando.de>

ePaul assigned tfrauenstein Jun 9, 2026

	NOTE: The efficiency of cursor-based pagination depends on the efficiency
	TIP: The efficiency of cursor-based pagination depends on the efficiency

	NOTE: In case of complex and long search requests, e.g. when
	Remark: In case of complex and long search requests, e.g. when

	TIP: Most recent major changes might be missing in the list since we update it
	NOTE: Most recent major changes might be missing in the list since we update it

		@@ -0,0 +1,22 @@
		# Registers EXCEPTION and EXAMPLE as custom admonition block types.
		# Reference: https://github.com/asciidoctor/asciidoctor-extensions-lab/issues/9

	# Reference: https://github.com/asciidoctor/asciidoctor-extensions-lab/issues/9
	# Reference: https://github.com/asciidoctor/asciidoctor-extensions-lab/issues/9
	# we use the following admonitions in the guidelines: TIP NOTE IMPORTANT WARNING EXCEPTION

Uh oh!

Conversation

SmilyOrg commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Label mapping

Test plan

Uh oh!

SmilyOrg commented Mar 17, 2026

Uh oh!

Uh oh!

tkrop commented Mar 18, 2026

Uh oh!

SmilyOrg commented Mar 23, 2026

Uh oh!

SmilyOrg commented Mar 23, 2026

Uh oh!

ePaul commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tkrop commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tfrauenstein left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tfrauenstein Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tfrauenstein Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

tfrauenstein Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

tfrauenstein Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

tfrauenstein Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

tfrauenstein Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

tfrauenstein left a comment

Choose a reason for hiding this comment

Uh oh!

ePaul commented Jun 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

SmilyOrg commented Mar 17, 2026 •

edited

Loading

ePaul commented Apr 14, 2026 •

edited

Loading

tkrop commented Apr 14, 2026 •

edited

Loading