如何在AsciiDoc转HTML时将level 1标题映射为H1标签

AsciiDoc默认将单等号=标记的文档级标题（level 0）映射为h1标签，因此正文内双等号==标记的level 1章节标题默认会偏移一级，渲染为h2标签。要实现level 1标题直接输出h1的效果，只需调整内置的章节层级偏移属性即可，不同场景的配置方式如下：

• 命令行单次转换
  调用asciidoctor转换命令时追加sectoffset=0属性参数：
  asciidoctor -a sectoffset=0 target-file.adoc
sectoffset是AsciiDoc内置的章节标题偏移控制属性，默认值为1，规则为「level N的章节标题渲染为h(N+1)」；将值设为0后，偏移规则变为「level N的章节标题渲染为h(N)」，此时level 1的==标题会直接输出为h1，level 2的===标题对应h2，后续层级依次顺延，完全适配语雀以h1为标准章节标题的层级要求。
• 单文件固定配置
  如果不想每次转换都手动追加命令参数，可以直接在.adoc文件的头部添加属性配置：

  :sectoffset: 0
  

  该行需要放在文档内容最前端，如果文档写了单等号开头的文档级标题，就把这行放在文档级标题的下一行，后续任意方式转换该文件都会自动应用这个映射规则，不需要额外传参。
• API批量转换
  如果是通过Asciidoctor官方API写脚本批量处理文件，只需在初始化转换配置时，给属性集传入sectoffset=0即可，各语言版本API配置逻辑一致，以Ruby版本为例：

  Asciidoctor.convert_file 'target-file.adoc', attributes: {'sectoffset' => 0}
  

配置完成后建议先取单个测试文件做转换验证，查看输出HTML源码确认==标记的标题已渲染为<h1>标签，再进行批量转换和语雀导入，避免出现层级错乱问题。

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