Include attributes from another file instead of site definition
Hi, We are converting our FrameMaker/Webworks documentation to Antora system. And we inherit a lot of variables (~150 variables), for which we struggle finding the right implementation. Some of these variables have predefined formatting.
We'd like to make sure the authors are easily setup for writing:
- Preview easily set-up with VSCode/AsciiDoc extension
- Simple usage of variables for authors
Here are the two options we tested:
Option 1: Defining attributes at the site/component level (.yml)
antora.yml
product: ProductName
cCompanyNameTM: MyCompany™
rnpNext_PhraseReuse: click *Next*.
= Page Title: {product} Quick Tour
In the text, use a predefined sentence.
pass:a,q[{rnpNext_PhraseReuse}]
With this method,
- We have a huge list of variables that authors have to copy in the preview settings of VSCode.
- We are not sure they will maintain this list up-to-date
- As soon as you use a variable with formatting, the author has to add the pass macro, which makes the reading less pleasant.
Option 2: Defining attributes by including a file
_attributes.adoc
:product: ProductName
:cCompanyNameTM: MyCompany™
:rnpNext_PhraseReuse: pass:a,q[click *Next*.]
= Page Title: {product} Quick Tour
include::_myvariable.adoc[]
In the text, use a predefined sentence.
{rnpNext_PhraseReuse}
This option is attractive to us, because when we define the attribute in the page, the passthrough macro can be defined in the attribute and it makes the writing for author seamless. It also ensures the authors will have an up-to-date list of variables.
However this is not working for replacing the attributes in the page title. If we add the include the page title, this breaks the detection of the page title, and possible ref text to it.
This is also fragile in implementation. If you remove the empty space before the include, it is no longer working.