https://discuss.asciidoctor.org/setting-imagesdir-for-asciidoc-articles-baked-with-awestruct-tp528p535.html
Xavier,
The solution you came up with certainly works, and for parts of the integration that approach will be the only solution. Fortunately, as of 0.1.4.rc.1, Asciidoctor accommodates the use case you present here.
The topic at hand is the precedence of attribute assignment. By default, the precedence, from highest to lowest is as follows:
- Attribute passed to the API or CLI
- Attribute defined in the document
- Intrinsic attribute value (default values)
The intrinsic value for the imagesdir attribute is empty string. If the attribute is defined no where else, then the value from the document is honored. However, we do define it somewhere else.
Awestruct defines a set of default attributes that it passes to the API (see
https://github.com/awestruct/awestruct/blob/master/lib/awestruct/config/default-site.yml). One of the attributes in that configuration is imagesdir. The value there is set to '/images'. That means the value in your document is skipped due to the precedence rules.
Fortunately, there is one additional place you can override the attribute. This gives you the opportunity to set your own default and to flip the precedence order so that the document wins out. Let's talk about how to change the precedence first.
If an attribute value that is passed to the API or CLI ends with an '@' symbol, it makes that assignment have a lower precedence than an assignment in the document. Let's add that to the precedence list defined earlier.
- Attribute passed to the API or CLI that does not end in '@'
- Attribute defined in the document
- Attribute passed to the API or CLI that ends in '@'
- Intrinsic attribute value (default values)
You can define attributes you want to pass to the API in the _config/site.yml file. Here's an example entry for Asciidoctor (inside the fenced code blocks):
```yaml
asciidoctor:
:safe: safe
:attributes:
imagesdir: /assets/images@
icons: font
...
```
NOTE: The second-level keys (safe and attributes, in this case) must have colons on both sides of the key name. The rest of the keys only have a colon after the key.
With this configuration added, you should observe that the imagesdir attribute in your document is now respected.
In closing, I want to mention something about the imagesdir setting in your document. Generally I like to set it to a value that makes images appear on GitHub. Then, I use Awestruct to override that value when building the site. It's up to you how you do it, but just keep that in mind.
Cheers,
-Dan