如何在AsciiDoctor-PDF输出的PDF中为标题添加边框

问题描述 #

我是一名高中生，正在使用AsciiDoctor-PDF制作供同学查阅的文档，想要给2级、3级标题添加符合示例效果的边框（2级标题上下边框，上细下粗；3级标题上边框），目前已有部分YAML主题配置，但不确定如何完善以达到预期效果。

现有配置：

heading:
  h1_font_size: floor($base_font_size * 2.4)
  h2:
    font_size: floor($base_font_size * 2.4)
    border-width: [0.75, 0, 2, 0]
    border-color: 000000

解决方案 #

你需要补全3级标题（h3）的配置，同时修正现有配置中的细节问题，最终的主题YAML配置如下：

heading:
  h1_font_size: floor($base_font_size * 2.4)
  h2:
    font_size: floor($base_font_size * 2.4)
    border-width: [0.75, 0, 2, 0] # 上、右、下、左边框宽度，单位为pt
    border-color: #000000 # 颜色值需添加#前缀，指定黑色边框
    border-style: solid # 明确边框样式为实线（默认也是solid，可省略但建议显式声明）
    padding: [6, 0, 6, 0] # 上下添加内边距，让文字与边框保持间距，避免拥挤
  h3:
    font_size: floor($base_font_size * 1.8) # 可根据需求调整字号
    border-width: [2, 0, 0, 0] # 仅设置上边框，宽度2pt
    border-color: #000000
    border-style: solid
    padding: [6, 0, 4, 0] # 上下内边距，适配标题层级

关键调整说明 #

• 颜色值修正：border-color必须以#开头（如#000000），否则AsciiDoctor-PDF无法识别颜色。
• h3配置补全：根据示例图的3级标题效果，添加h3节点，仅设置上边框宽度，匹配视觉效果。
• 内边距（padding）：添加上下内边距可以避免文字紧贴边框，提升可读性，数值可根据实际字号调整。
• 边框样式：默认是solid，显式声明可以让配置更清晰，若需要虚线等其他样式可改为dashed/dotted。

内容的提问来源于stack exchange，提问作者YasAko