Search code examples
asciidoc

How to set scope for document attributes in AsciiDoc


I want to set the keywords attribute based on the hierarchy of sections.

For example, suppose you have the following AsciiDoc document:

= Article
:keywords: keyword0

== Section1
:keywords: keyword1

== Section2

{keywords}

In this example {keywords} the output I expect is keyword0. In other words, I do not want the value of the keywords attribute set in Section1 to carry over to Section2.

However, the output of Asciidoctor.js Live Preview shows keyword1. Is it possible to set the scope based on the hierarchy of sections for the keywords attribute?

If the above method is not in line with AsciiDoc's practices, please let me know if there are better design strategies for AsciiDoc documents.


Solution

  • The functionality you're seeking extends beyond the intended capabilities of Asciidoc. This is not due to any shortcomings in its implementation but rather because the features you're describing fall into the realm of programming and structured programming, rather than document description. Your requirements are valid and understandable, but they are not designed to be handled by markup languages like Asciidoc.

    I, too, enjoy incorporating programming into my documentation. To address similar needs, I developed a meta-markup language that you might find useful. It integrates with various tools, including an Asciidoctor preprocessor, and works seamlessly with the IntelliJ Asciidoctor plugin and AsciidocFX.

    The core idea is to combine meta-markup with your document markup, process the meta-markup, and then pass the resulting pure Asciidoc document to the Asciidoc processor. This approach allows you to use meta-markup macros instead of Asciidoc attributes, which, in my opinion, are a limited solution to the problem and often fall short except in very specific cases.

    The meta-markup language I developed is called Jamal, and you can find it here:

    https://github.com/verhas/jamal