I am using Antora+AsciiDoc to create technical documentation. I am facing the problem of needing to visually add content before the document header in the .adoc file to make it display correctly in HTML after Antora build and can't find a suitable solution.
For example, I need to add image and text: image:articles/my-icon.svg[] [.text-block-page]#My Block#
before the document title = {document-title-key}
in .adoc file.
Because any text added before the document title in .adoc breaks the page structure, I decided to use absolute values via CSS:
= {document-title-key}
[.block-page-top-container]
--
image:articles/my-icon.svg[] [.text-block-page]#My Block#
--
++++
<style>
.block-page-top-container {
position: relative;
top: -7.2em;
margin-bottom: -3.5em;
}
</style>
++++
This variant works quite well and I get a good result (see the result of building through Antora in HTML):
However, this approach with absolute CSS values is not universal, for example, at a page zoom of 110% and beyond, this bar rests on the edge of the page (see edge of the page icon), and I would like to have more space between icon and the header:
At the same time, due to a number of limitations I don't want to use page title attribute, as well as hiding headers via [discrete], so I don't have a lot of options to put a picture + text before the page title in the .adoc file itself, so I had to rely on CSS to visually insert an icon and label above the title.
Are there options for more robust CSS customization for my case or some AsciiDoc hacks for adding text before the page title? Thanks in advance.
While you ask for hacks, you should avoid hacks because that makes your implementation fragile.
Instead, you should fork the Antora Default UI and change the article.hbs
template to test for attribute definitions that can be used to include content before the page title.
The default article.hbs
template includes:
<article class="doc">
{{#with page.title}}
<h1 class="page">{{{this}}}</h1>
{{/with}}
{{{page.contents}}}
{{> pagination}}
</article>
Before the {{#with page.title}}
line, you could add something like:
{{#if (or page.attributes.attention page.attributes.attention_icon)}}
<div class="attention">
{{#if page.attributes.attention_icon}}
<img src="{{{page.attributes.attention_icon}}}">
{{/if}}
{{page.attributes.attention}}
</div>
{{/if}}
That conditionally adds a <div>
using the attribute definitions. So, your page could include:
= Document title
:attention: This page is deprecated.
:attention_icon: deprecation.svg