关于Antora使用过程中的一些错误及解决办法

2023年3月31日，IvorySQL开源项目的文档中心进行了一次更新，如果您对此感兴趣，请点击

https://docs.ivorysql.org/index.html  对我们崭新的文档中心进行访问。

文档中心采用「Antora」工具生成，文档格式采用asciidoc格式。

🏆Antora是一种源自Asciidoctor的开源文档工具，它可以帮助团队创建和发布技术文档。Antora使用模块化文档结构，允许您将文档分解为较小的部分，并轻松地跨不同平台组合和重用这些部分。它还提供了针对多个输出格式（例如HTML、PDF和ePub）的定制选项和主题，以使文档内容更具可读性。Antora设计用于帮助管理和维护大量技术文档，并且适用于许多不同类型的项目和组织。

如果你仅仅想将项目过程中的「文档内容进行展示」例如将静态网页部署在公司或者个人的域名上，并且您的项目具有许多分支、版本以及周边衍生的各种工具，那么Antora能够很好的满足您的需求。

磕磕绊绊的运行

在运行Antora的过程中，随之而来的结果可能会使你的心情变得不会那么美丽，相信我，🐣这对于每一位初次使用新工具且需要使用新工具产出的开发者来说都是一样的。请保持耐心，下面是笔者在使用过程中经常碰到的一些问题以及对应的解决办法，希望可以帮到刚开始使用这个工具的你。

网络问题（疑似）

运行antora playbook.yml失败后，为了解决问题，需要重新运行antora playbook.yml --stacktrace来检查具体原因。以下两种错误会经常出现在您的运行过程中，例如Error: connect ECONNREFUSED X.X.X.X:443以及Error: read ECONNRESET。

• 假如您的项目托管于Github上，由于一些众所周知的原因可能会导致出现此类问题，这时您需要采用科学上网的方式来解决此类问题。

• 如果科学上网之后仍旧出现这些问题，您可以暂时停止运行antora，因为Github会拒绝来自短时间内多次拉取相同文件资源的IP地址的访问

• 排除以上原因之后，您的运行仍旧失败，那就需要考虑用于生成网页的文件结构是否正确。Antora只会对modules/ROOT/pages目录下的.adoc文件进行编译，并且在modules同级的目录下需要准备一个antora.yml文件用于对modules目录中的文档进行描述，具体内容可以参考Antora docs。您可以按照上述描述进行检查。

此类网络问题，即使在您已经成功运行过一次antora之后，仍旧可能会出现在您的屏幕上，尽管您已经采用了科学上网的方式又或者反复检查过项目的文件结构并确保正确无误。当遇到此类问题，记得多尝试几次^_^🏃‍♂️

关于playbook.yml的一些问题

由于.yml文件采用K-V键值对的写法，因此每一个Key都需要对应一个Value值，在书写时需要格外注意缩进和空格，行与行之间没有对齐或者缺少空格都会导致playbook.yml的编译失败。

值得注意的是，假如您的playbook.yml文件书写有误，比如您设定的start_page路径有错误，就会导致antora根据这个错误的路径不断地尝试在您的项目中寻找对应的文件，结果可想而知是找不到的>_<🤦‍♂️，但antora并不会将错误识别成是playbook.yml文件书写有误，而是将错误返回成上述的网络问题（因为每尝试一次就相当于在Github上进行了一次pull操作）。

关于antora.yml的一些问题

antora.yml作为每一个组件的描述文件，在您的项目中可能会出现多次，当这个文件出现错误时，可能会直接导致您的编译失败，为了尽量避免这类问题，请注意以下：

• antora.yml文件的名字尽量不做修改

• 每一个modules目录同级需要准备一个antora.yml文件

• antora.yml文件同样采用K-V键值对的写法，请注意缩进＆空格^_^

• antora.yml文件中最少要包含name, title, version, start_page, nav属性，更多可选的值请参考Antora docs

其他错误

以上三类问题是笔者在使用时较难定位原因的问题，但不代表仅会出现上述问题。幸运的是，运行时添加--stacktrace参数可以将其他大部分错误的堆栈信息准确的显示，从而帮助开发者快速得定位原因并解决。

结论

Antora的适用性或许不高，但其特点仍旧闪耀，希望初次接触这个工具的同行者们不会因失败而气馁，写下这篇，希望可以帮到你。

💪过程中的坎坷只会让结果带来的喜悦更强，共勉^_^