如何用Antora建设IvorySQL文档中心

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

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

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

🏃‍发展未有穷期，任重而道远。IvorySQL开源社区始终坚持开源共享的理念并且欢迎每一位愿意遵守「社区行为准则」的小伙伴的加入。文档中心还在完善，社区的每一份力量都一定会使得IvorySQL社区更加强壮。

为了您能在发现错误时做出的「commit」更容易接受，您需要了解我们文档的规范格式，以便您在修改时能够得到恰当的结果。如果您平常习惯书写markdown语言，那么您仅需要在书写时按照下文做一些小小的调整；如果您没有接触过此类标记语言，那么下文同样可以帮助您以最小的成本达成您提交修改的目的。

规格格式

🔔在书写adoc格式文件时，不要吝于使用换行和空格，多使用换行和空格可能会帮你更容易得到你想要的结果。

网址链接

如果您修改的内容涉及到网址链接，请您按照以下格式修改：

https://docs.ivorysql.org[IvorySQL文档中心]

如果这个链接前后出现了正文内容，请切记添加一个空格隔开以使这个链接生效。类似如下：

文本 https://docs.ivorysql.org[IvorySQL文档中心] 文本

代码块

如果您想修改代码块的内容，或者新增加一个代码块内容，您可以参照下面的格式进行书写：

[source,c/java/python/doc/SQL/...]
----
This is a code block.You can write code at here.
----

🐘注意，以下格式同样是规范的：

----
This is a block of text.You can write anything at here.
----

标题

adoc格式的文件同样兼容md格式中采用#来标明标题，不过在adoc文件中更加规范的格式为采用=。例如，md格式文档中。

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题

在adoc格式文档中。

= 一级标题
== 二级标题
=== 三级标题
==== 四级标题
===== 五级标题

🐘注意：adoc格式文件标题级别仅到第六级，请注意标题级别的书写。

有序列表和无序列表

adoc格式文件使用.来生成有序列表。

. 一级列表1
. 一级列表2
.. 二级列表1
... 三级列表1
.. 二级列表2
. 一级列表3

adoc格式文件使用*,-来表明列表。

* 一级列表
** 二级列表
*** 三级列表

或者

* 一级列表
- 二级列表
** 三级列表

🎄如果以上这些仍不能满足您的修改需求，您可以参照

「asciidoc官网」

🔗https://docs.asciidoctor.org/asciidoc/latest/ 

来继续学习如何书写规范的adoc格式的文档。

Antora环境准备（Linux环境）

//安装node
curl -o https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash 

//配置环境变量
vi .bashrc

export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

source .bashrc

//使用node版本
nvm install 16

//安装antora
npm i -g @antora/cli@2.3 @antora/site-generator-default@2.3

antora -v

以上为antora的linux安装步骤，仅供参考。

详情可以参考

 https://consolelog.gitee.io/docs-antora/antora/2.3/install/install-antora.html

🎄如果您更习惯于使用其他的操作系统环境，您可以参考「antora官网」，来安装antora。

Antora使用

经过上述步骤，您的系统中已经安装好了antora工具。

playbook.yml 的准备

在运行antora工具来将您的adoc文件组织成html文件时，您需要提前准备一个playbook.yml文件，您需要在该文件中准备以下内容:

site: 
  title: #这里是您的网页标题
  url: #这里是您网址的公网地址
  start_page: #这里是点击您网址的公网地址时，用户最先看到的页面
content:
  source:
  - url: #这里是您网页原内容的地址，一般是github等具有版本控制的项目托管平台，如果您有多个项目，您可以在新一行添加url。
    branches: #这里可以填写您具体想从哪几个分支里面取得内容，如果上面的url指向的项目仅有一个分支，可以忽略该值
ui:
  bundle:
    url: #这里是您组织成网页所需框架的地址
    snapshot: #一般写true，这样每次运行antora时都会重新获取一次ui框架，保证您对ui的任何更新都可以实时体现在您的网页上

以上内容是一个playbook.yml的基本内容。下面是antora文档中心在建设过程中的一个测试用途的yml文件：

site:
  title: IvorySQL Document Site
  url: https://docs.ivorysql.org
  start_page: ivorysql-doc::welcome.adoc
content:
  sources:
  - url: https://github.com/DutMsn/ivory-docs.git
    branches: [master,v1.0,v1.1,v1.2,v1.3,v1.4,v1.5,v2.1,v2.2]
asciidoc:
  attributes:
    experimental: ''
    idprefix: ''
    idseparator: '-'
    page-pagination: ''
ui:
  bundle:
    url: https://raw.githubusercontent.com/IvorySQL/ivory-doc-builder/main/templates/ui-bundle.zip
    snapshot: true
runtime:
  fetch: true

您同样可以在antora的官网上获取到一个用于入门antora的playbook.yml文件，以便您可以在您的电脑上快速的成功运行一次antora，这种正反馈对于您之后的学习非常有帮助。

antora.yml的准备

在成功运行过antora，并且成功生成了与源文件相对应的网页之后，您可能不满足于生成一些简单的demo，同样的，相信您也注意到经过antora工具生成的网页具有版本控制的特点，这对于管理那些经过迭代逐渐成熟的项目的文档系统以及具备多种生态工具的项目的文档系统是非常便利的。

通过对上述操作的复现以及antora官网的学习，相信您对于modules已经取得了初步的了解，要注意，每一个modules文件对应的同级目录下，应该准备一个antora.yml文件以供antora工具在运行时，能够正确识别您的文件内容并按照对应版本组织到合适的位置。以下为一个antora.yml文件的基本内容：

name: #这里是您其中一个组件的名字，该值的缺失可能会导致antora无法成功运行
title: #这里是该文件放在网页时，您希望显示的名字，您可以自由编写，不会影响antora的编译
version: #这里是该文件对应的版本号，您可以自由编写，不会影响antora的编译
start_page: #这里是当用户点击对应版本号时，你希望跳转出现的页面
nav:
- #这里需要写明您文件的导航文件的路径

以下为IvorySQL文档中心在建立过程中用于测试的antora.yml文件内容

name: ivorysql-doc-cn
title: IvorySQL
version: v2.2
start_page: welcome.adoc
asciidoc:
  attributes:
    source-language: asciidoc@
    table-caption: false
nav:
- modules/ROOT/nav.adoc

nav.adoc的准备

nav.adoc是生成网页的导航栏内容文件，您可以在这里获得您关于nav.adoc的一切内容。

https://docs.antora.org/antora/latest/navigation/multiple-lists/#create-a-navigation-file-with-two-lists 

运行anotra

准备好上述文件以及您的源文件（注意是.adoc文件）之后，您就可以通过运行antora playbook.yml命令来生成您的网页了。

如果一切顺利，在您熟悉antora的简单用法之后，您在运行时就可以添加参数来使得生成网页的工作更加效率。尝试以下命令；

antora generate --to-dir ../demo playbook.yml --stacktrace

✨以上，是IvorySQL文档中心建设过程中，对于antora工具使用的一些经验，希望能够帮助到你！

最后，欢迎加入到我们的IvorySQL社区。

---

官方网址：

https://www.ivorysql.org/zh-cn/

社区仓库：

https://github.com/IvorySQL/IvorySQL

IvorySQL社区欢迎并赞赏所有类型的贡献，期待您的加入！

还有，别忘了在Github给我们一个 ⭐奥~