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环境）

//装置nodecurl -o https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash //配置环境变量vi .bashrcexport 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 nvmsource .bashrc//应用node版本nvm install 16//装置antoranpm i -g @antora/cli@2.3 @antora/site-generator-default@2.3antora -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.adoccontent:  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: trueruntime:  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-cntitle: IvorySQLversion: v2.2start_page: welcome.adocasciidoc:  attributes:    source-language: asciidoc@    table-caption: falsenav:- 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给咱们一个 ⭐奥~