Consider if we want to add an additional asciidoctor block around source code for callouts

spring-projects / spring-boot

Spring Boot

https://spring.io/projects/spring-boot

Apache License 2.0

74.48k stars 40.53k forks source link

Consider if we want to add an additional asciidoctor block around source code for callouts #27806

Open philwebb opened 3 years ago

philwebb commented 3 years ago

See the discussion at https://github.com/spring-projects/spring-boot/pull/27759#discussion_r691636911

We currently don't have any callouts, but if we did we should consider how we want them styled. We will also need to consider how they'll work with tab switches if we have Kotlin versions of the samples.

Buzzardo commented 3 years ago

As we have discussed, I ultimately want to use the Spring Boot doc production backend for all the projects. Other projects do use callouts, so I definitely want the backend to handle them.

I encourage using callouts. They offer a way to say, "Exactly here within this code block," and then add a bit of detail. They are a good approach to describing blocks of code that have more than minimal complexity.