Antora+AsciiDoc环境下在文档标题上方添加可视化内容且不破坏结构的方案咨询

我完全理解你的痛点：想在Antora生成的页面标题上方添加图标+文本组合，直接在标题前编写内容会被Antora放到标题下方的内容区，用固定负em值的CSS定位又在页面缩放时出现布局错位，还受限于不能使用页面标题属性、[discrete]隐藏标题这些方法。下面给你两个方向的可靠解决方案：

一、更稳健的CSS优化方案（解决缩放适配问题） #

你的核心问题是当前用固定负em值的定位在缩放时失效，我们可以通过基于根字体的弹性单位（rem）+ 正确的容器定位来解决：

1. 调整定位逻辑，改用绝对定位+弹性间距

首先修改你的AsciiDoc代码，把图标+文本容器放在最开头，用原生HTML块避免AsciiDoc的结构干扰：

+++
<div class="pre-title-bar">
  <img src="{page-url}/articles/my-icon.svg" alt="Section Icon" class="pre-title-icon">
  <span class="pre-title-text">My Block</span>
</div>
+++

= {document-title-key}

然后替换你的CSS为以下弹性方案：

/* 基于Antora默认页面结构，假设页面根容器为.page */
.page {
  position: relative;
  /* 给前导栏预留顶部空间，用rem适配缩放 */
  padding-top: 4rem;
}

.pre-title-bar {
  position: absolute;
  top: 1.5rem; /* 距离页面顶部的弹性间距 */
  left: 1.25rem; /* 距离左侧的边距，避免贴边 */
  right: 1.25rem; /* 距离右侧的边距，适配不同宽度 */
  display: flex;
  align-items: center;
  gap: 0.8rem; /* 图标与文本的间距，可自由调整 */
}

/* 可选：调整图标大小 */
.pre-title-icon {
  width: 24px;
  height: 24px;
}

/* 重置标题容器的默认间距，保证和前导栏的距离 */
.page-header {
  margin-top: 0;
}

这个方案的优势：

• 用rem单位（基于根字体大小）代替固定em，页面缩放时会自动适配
• 通过left/right的边距设置，彻底避免图标贴到页面边缘的问题
• 用gap控制图标与文本的间距，比固定margin更灵活

2. 利用CSS伪元素简化实现（适合固定文本的场景）

如果你的“我的块”文本是全局固定的，还可以用::before伪元素直接插入到标题容器前，不需要在AsciiDoc中编写额外内容：

/* 针对Antora默认的.page-header容器 */
.page-header::before {
  content: "My Block";
  /* 插入图标作为背景 */
  background-image: url("/articles/my-icon.svg");
  background-size: 24px 24px;
  background-repeat: no-repeat;
  background-position: left center;
  /* 给图标预留空间，控制文本与图标的间距 */
  padding-left: 32px;
  /* 控制与标题的间距 */
  margin-bottom: 0.8rem;
  display: block;
  /* 继承标题的字体样式，保持视觉统一 */
  font-size: 1rem;
  color: #666;
}

如果需要每个页面的文本不同，可以结合自定义AsciiDoc属性+JS动态设置：

/* 在AsciiDoc页面开头定义自定义属性 */
:pre-title: My Block

+++
<script>
// 将自定义属性值绑定到页面容器的data属性
document.querySelector('.page').dataset.preTitle = '{pre-title}';
</script>
+++

= {document-title-key}

然后修改CSS：

.page-header::before {
  content: attr(data-pre-title);
  /* 其余图标、间距样式同上 */
}

二、AsciiDoc技巧：绕过Antora的标题提取逻辑 #

Antora会把AsciiDoc文档的第一个标题（= ...）提取到页面的header区，而标题前的内容会被放到下方的内容区。我们可以用嵌套文档块的小技巧，让Antora把我们的前导内容和标题放在同一层级：

[.pre-title-container]
++++
<div class="pre-title-bar">
  <img src="{page-url}/articles/my-icon.svg" alt="Icon">
  <span>My Block</span>
</div>
++++

= {document-title-key}

// 页面正文内容

然后用CSS调整容器的位置，把它移到标题上方的视觉区域，同时用margin-top而不是负top值：

.pre-title-container {
  margin-bottom: 2rem;
  display: flex;
  align-items: center;
  gap: 0.8rem;
}

/* 针对Antora的.content容器，调整顶部间距 */
.content {
  margin-top: -6rem;
  padding-top: 6rem;
}

这个技巧的核心是利用AsciiDoc的块容器，让Antora把内容放在.content的最开头，然后通过padding-top给前导栏预留空间，margin-top负数值把内容区上移，同时用padding-top避免正文内容被覆盖。

关键注意事项 #

1. 优先使用rem单位代替em或固定像素，rem基于根字体大小，页面缩放时会自动适配，避免错位
2. 尽量基于Antora默认的HTML结构编写CSS（比如.page、.page-header、.content这些类），避免依赖自定义模板
3. 如果需要多页面复用这个样式，建议把CSS放到Antora的ui-bundle的自定义样式文件中，而不是每个页面内联编写

内容来源于stack exchange