how to define own asciidoc macro

Question

How do I define a macro in asciidoc/asciidoctor?

I will use a repeating pattern in many parts of my document so I would like to make a parametrized substitution to avoid entering the same stuff many times.

In particular, I have the following asciidoc snippet:

{set:cellbgcolor:grey}
[grid=none, frame=none]
|===
| X >| Y
|===
{set:cellbgcolor!}

And I need to place it in several parts of the document with different text substitutions in place of X and Y. How do I achieve that?

Answer 1

In my opinion you do not get with Asciidoctor all the flexibility/simplicity you get in other documentation engines:

• command definition in LaTeX
• Templates in MediaWiki.

---

I think that you can work with the include macro and variables in Asciidoctor:

Create a file called snippet.adoc (my example is based on your example):

{set:cellbgcolor:grey}
[grid=none, frame=none]
|===
| {paramX} >| {paramY}
|===
{set:cellbgcolor!}

In your main document use it like this:

== My document

:paramX: lorem
:paramY: ipsum
include::snippet.adoc[]

Lorem ipsum dolore.

:paramX: aaaa
:paramY: bbbb
include::snippet.adoc[]

Lorem ipsum dolore.

---

That said asciidoctor can be extended. You can also create your own real macro (written in Java or in Ruby), but this requires more work. Depending on your use case, you can find several examples online.