micronaut-projects / micronaut-guides

Guides and Tutorials on how to use Micronaut including sample code
https://guides.micronaut.io
Creative Commons Attribution 4.0 International
36 stars 31 forks source link

Use asciidoc include instead of custom macros #1556

Open AndreaLaGrotteria opened 1 day ago

AndreaLaGrotteria commented 1 day ago

In guides-core use asciidoc built-in include system instead of custom macros solution.

common

common:header-top.adoc[]

would become

include::{commonsDir}/common-header-top.adoc[]

external-template

external-template:micronaut-k8s-oci/k8s-microservice.adoc[arg0=users] would become

:arg0: users
include::{guidesDir}/micronaut-k8s-oci/k8s-microservice.adoc[]

for guides that were using the syntax {arg0:U} to make argument uppercase, the macro would become

:arg0: users
:arg0Upper: USERS
include::{guidesDir}/micronaut-k8s-oci/k8s-microservice.adoc[]

callout

callout:controller[number=1,arg0=/hello]
callout:get[number=2,arg0=index,arg1=/hello]
callout:text-plain[3]

would become

:arg0: hello
include::{calloutDir}/callout-controller[]
:arg0: index
:arg1: /hello
include::{calloutDir}/callout-get[]
include::{calloutDir}/callout-text-plain[]

the explicit numeration is not needed since asciidoc does that automatically.

We would need to update the guide asciidoc of the included files where {arg0:U} is present to replace it with {arg0Upper} and every callout, adding <.> at the begging of the line.

AndreaLaGrotteria commented 1 day ago

We can also keep the old macros and translate them before passing the file to asciidoctor. This would essentially be the same as what we do with the source:, which is just translated into an include (in contrast with common: which imports the file directly)

sdelamo commented 1 day ago

If you are willing to da PR which updates every guide to this, I am happy to accept it.