自动化移除Frontmatter：优化Hugo与AsciiDoctor PDF集成流程

无需注释首行隐藏Frontmatter的方法 #

Hugo会自动移除Asciidoc文件开头的YAML Frontmatter（---包裹的区块），但直接用asciidoctor-pdf渲染时，这部分会被当作普通文本显示。以下是两种无需注释首行的隐藏方案：

方案1：借助Hugo资源管道预处理 #

让Hugo先处理Asciidoc文件并移除Frontmatter，再将处理后的内容传递给asciidoctor-pdf生成PDF。在Hugo模板中可以这样实现：

{{ $adoc := resources.Get "docs/my-document.adoc" }}
{{ $cleanContent := $adoc.Content }}
{{ $pdf := $cleanContent | resources.ExecuteAsTemplate "temp.adoc" . | resources.Process "asciidoctor-pdf" }}

$adoc.Content已经是Hugo移除Frontmatter后的纯Asciidoc内容，以此为基础生成的PDF不会包含Frontmatter。

方案2：用Asciidoctor注释包裹Frontmatter #

在YAML Frontmatter前后添加Asciidoctor行注释，让asciidoctor-pdf忽略这段内容，同时不影响Hugo识别Frontmatter：

// tag::hugo-frontmatter[]
---
title: "文档标题"
subtitle: "副标题"
---
// end::hugo-frontmatter[]

Hugo依然能正常解析中间的---区块，而asciidoctor-pdf会将注释行及包裹内容跳过，不会渲染到PDF中。

自动化实现方案 #

方案1：配置Hugo自定义输出格式 #

在Hugo的config.toml中定义PDF输出格式，让Hugo自动处理所有Asciidoc文件的Frontmatter并生成PDF：

[outputs]
home = ["HTML", "PDF"]

[outputFormats.PDF]
baseName = "document"
isPlainText = false
mediaType = "application/pdf"
protocol = "file"
path = "pdfs"
generator = "asciidoctor-pdf"

配合对应模板，Hugo会自动完成Frontmatter移除、内容渲染到PDF的全流程。

方案2：批量处理脚本 #

编写Shell/Python脚本批量处理Asciidoc文件，自动移除Frontmatter后调用asciidoctor-pdf。示例Shell脚本：

#!/bin/bash
# 遍历当前目录下所有Asciidoc文件
for file in *.adoc; do
  # 移除开头的YAML Frontmatter区块
  sed -n '/^---$/,$p' "$file" | sed '1d' | sed '/^---$/q' > temp_content.adoc
  # 生成PDF
  asciidoctor-pdf temp_content.adoc -o "${file%.adoc}.pdf"
  # 清理临时文件
  rm temp_content.adoc
done

执行该脚本即可批量处理文件，无需手动操作。

Asciidoc中适配Hugo的单独参数 #

可以通过Frontmatter传递自定义参数，在Asciidoc内容中结合Hugo模板变量引用，同时兼顾asciidoctor-pdf的渲染需求：

1. 在Asciidoc的Frontmatter中定义参数：

---
title: "我的文档"
image_path: "/images/figure1.png"
---

2. 在Asciidoc内容中使用Hugo模板变量引用参数：

image::{{ .Params.image_path }}[文档配图]

3. 直接用asciidoctor-pdf渲染时，通过命令行属性覆盖参数值：

asciidoctor-pdf -a image_path=./static/images/figure1.png my-document.adoc

这样既能满足Hugo的路径解析需求，也能适配asciidoctor-pdf的本地渲染路径。

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