关于数据库:如何用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/in…

🎄如果您更习惯于应用其余的操作系统环境，您能够参考「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-lis… 

运行 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 给咱们一个 ⭐奥~