閱讀(12.4k) 書簽贊(0) 我要糾錯(cuò)

使用AsciiDoc文件

2018-01-19 15:28 更新

AsciiDoc語法表

AsciiDoc語法的權(quán)威手冊(cè)在“Asciidoctor用戶手冊(cè)”中。但是，為了幫助人們開始，這里提供一個(gè)簡(jiǎn)單的語法表。

AsciiDoc與Asciidoctor語法

我們使用Asciidoctor項(xiàng)目中的工具來構(gòu)建Ref Guide的HTML和PDF版本。Asciidoctor是原來的AsciiDoc項(xiàng)目的Ruby端口，幾年前這個(gè)項(xiàng)目大部分都被拋棄了。

雖然這兩者之間的大部分語法都是相同的，但AsciiDoc支持AsciiDoc中不存在的許多約定。雖然Asciidoctor項(xiàng)目試圖提供與舊項(xiàng)目的后向兼容性，但這可能永遠(yuǎn)不會(huì)是真的。出于這個(gè)原因，強(qiáng)烈建議只使用Asciidoctor用戶手冊(cè)作為任何在這里沒有描述的語法的參考。

基本的AsciiDoc語法

加粗（Bold）

將星號(hào)放在文字上以使其粗體。

更多信息：http : //asciidoctor.org/docs/user-manual/#bold-and-italic

斜體（Italics）

在字符串的任一側(cè)使用下劃線將文本變?yōu)樾斌w。

更多信息：http : //asciidoctor.org/docs/user-manual/#bold-and-italic

標(biāo)題（Headings）

等號(hào)（=）用于表示標(biāo)題級(jí)別。每個(gè)等號(hào)都是一個(gè)級(jí)別。每個(gè)頁面只能有一個(gè)頂層。

級(jí)別應(yīng)適當(dāng)嵌套。在構(gòu)建過程中，驗(yàn)證發(fā)生的目的是確保級(jí)別3之前是級(jí)別2，級(jí)別4之前是級(jí)別3等。包括不按順序的標(biāo)題級(jí)別（例如級(jí)別3，級(jí)別5）不會(huì)失敗建立，但會(huì)產(chǎn)生一個(gè)錯(cuò)誤。

更多信息：http://asciidoctor.org/docs/user-manual/#sections

代碼示例（Code Examples）

使用反引號(hào)`來表示應(yīng)該是等寬的文本，例如段落主體中的代碼或類名稱。

更多信息：http://asciidoctor.org/docs/user-manual/#mono

更長(zhǎng)的代碼示例可以用source塊與文本分開。這些允許定義正在使用的語法，以便代碼正確地突出顯示。

示例源塊：

[source,xml]
<field name="id" type="string" indexed="true" stored="true" required="true" multiValued="false" />

如果您的代碼塊將包含換行符，請(qǐng)?jiān)谡麄€(gè)塊之前和之后放置4個(gè)連字符（----）。

更多信息：http://asciidoctor.org/docs/user-manual/#source-code-blocks

源塊語法高亮（Source Block Syntax Highlighting）

PDF和HTML輸出使用Pygments為代碼示例添加語法高亮顯示。這是通過在source之后添加代碼塊的語言來完成的，如上面的示例源代碼塊所示（在這種情況下為 xml）。

Pygments有很多可用的詞法分析器。你可以在http://pygments.org/docs/lexers看到完整的列表。使用其中一個(gè)有效的短名稱來獲得該語言的語法高亮顯示。

理想情況下，我們將有一個(gè)適當(dāng)?shù)脑~法分析器用于所有的源代碼塊，但這是不可能的。如有疑問，請(qǐng)選擇text，或?qū)⑵浔Ａ魹榭铡?/p>

塊標(biāo)題（Block Titles）

標(biāo)題可以通過用句號(hào)（.）初始化標(biāo)題來添加到大多數(shù)塊（圖像，源塊，表格等）。例如，要為上面的源代碼塊添加一個(gè)標(biāo)題：

.Example ID field
[source,xml]
<field name="id" type="string" indexed="true" stored="true" required="true" multiValued="false" />

鏈接（Links）

鏈接到互聯(lián)網(wǎng)上的網(wǎng)站

將內(nèi)容轉(zhuǎn)換為HTML或PDF時(shí)，Asciidoctor將自動(dòng)呈現(xiàn)許多鏈接類型（例如http:和mailto:），而無需任何其他語法。

但是，您可以通過添加URI后跟方括號(hào)來為鏈接添加名稱：

http://lucene.apache.org/solr[Solr Website]

鏈接到其他頁面/部分

預(yù)先警告，鏈接到其他頁面可能會(huì)有點(diǎn)難。根據(jù)您要?jiǎng)?chuàng)建的鏈接類型以及您要鏈接的位置，規(guī)則略有不同。

構(gòu)建過程包括對(duì)內(nèi)部或頁面間鏈接的驗(yàn)證，所以如果您可以在本地構(gòu)建文檔，則可以使用它來驗(yàn)證是否正確構(gòu)建了鏈接（或者在提交后注意Jenkins構(gòu)建）。

通過以下所有示例，您可以添加文本以顯示鏈接標(biāo)題，方法是在節(jié)參考后面跟隨顯示文本添加逗號(hào)，如下所示：

<<schema-api.adoc#modify-the-schema,Modify the Schema>>

鏈接到同一頁上的部分

如果要鏈接到同一頁面上的定位點(diǎn)（或節(jié)標(biāo)題），則可以簡(jiǎn)單地在要鏈接的定位點(diǎn)/標(biāo)題/節(jié)標(biāo)題周圍使用雙角括號(hào)（<< >>）。任何部分標(biāo)題（以等號(hào)開頭的標(biāo)題）在轉(zhuǎn)換過程中自動(dòng)成為錨點(diǎn)，可用于深層鏈接。

示例

如果我在頁面上顯示如下（從defining-fields.adoc）的部分：

== Field Properties

Field definitions can have the following properties:

要從同一defining-fields.adoc頁面的另一部分鏈接到本節(jié)，我只需要將部分標(biāo)題放在雙尖括號(hào)中，如下所示：

See also the <<Field Properties>> section.

節(jié)標(biāo)題將被用作顯示文本; 自定義在章節(jié)標(biāo)題后面添加逗號(hào)，然后顯示用于顯示的文本。

更多信息：http : //asciidoctor.org/docs/user-manual/#internal-cross-references

鏈接到具有錨點(diǎn)ID的部分

鏈接到任何部分（在同一頁面或另一個(gè)頁面）時(shí)，還必須注意可能正在使用的任何預(yù)定義的節(jié)點(diǎn)（這些節(jié)點(diǎn)將位于雙括號(hào)內(nèi)[[ ]]）。當(dāng)頁面被轉(zhuǎn)換時(shí)，這些將是你的鏈接需要指向的引用。

示例

以configsets-api.adoc這個(gè)例子為例：

[[configsets-create]]
== Create a ConfigSet

要鏈接到本節(jié)，有兩種方法取決于您從哪里連接：

從同一頁面，只需使用節(jié)點(diǎn)名稱：<<configsets-create>>。
在另一個(gè)頁面上，使用頁面名稱和節(jié)點(diǎn)名稱：<<configsets-api.adoc#configsets-create>>。

鏈接到另一個(gè)頁面

要鏈接到另一個(gè)頁面或另一個(gè)頁面上的一個(gè)部分，您必須引用完整的文件名，并引用您要鏈接到的部分。

不幸的是，當(dāng)你想將閱讀器引用到另一個(gè)頁面而沒有深度鏈接到一個(gè)部分時(shí)，你不能簡(jiǎn)單地將其他文件名稱放在尖括號(hào)中，并稱之為一天。這是由于PDF轉(zhuǎn)換 - 一旦所有的頁面被合并成一個(gè)大頁面的一個(gè)大的PDF頁面，缺乏具體的引用，導(dǎo)致頁面間鏈接失敗。

所以，你必須總是鏈接到一個(gè)特定的部分。如果您只想引用另一個(gè)頁面的頂部，則可以使用page-shortname每個(gè)頁面頂部的屬性作為節(jié)點(diǎn)引用。

示例

該文件upgrading-solr.adoc在頂部有一個(gè)一個(gè)page-shortname看起來如下：

= Upgrading Solr
:page-shortname: upgrading-solr
:page-permalink: upgrading-solr.html

要構(gòu)建一個(gè)鏈接到這個(gè)頁面，我們需要引用文件名（upgrading-solr.adoc），然后使用page-shortname作為我們的節(jié)點(diǎn)引用。如：

For more information about upgrades, see <<upgrading-solr.adoc#upgrading-solr>>

鏈接到另一頁上的部分

鏈接到某個(gè)節(jié)與鏈接到頁面頂部的概念相同，只需要格外小心地在鏈接引用中正確設(shè)置的節(jié)點(diǎn)ID。

當(dāng)您鏈接到另一頁上的部分時(shí)，您必須將標(biāo)題轉(zhuǎn)換為在轉(zhuǎn)換過程中創(chuàng)建部分ID的格式。這些是改變部分的規(guī)則：

所有的字符都是小寫的：Using security.json with Solr 變 using security.json with solr
所有非alpha字符都被刪除，除了連字符（所有句點(diǎn)，逗號(hào)，＆符號(hào)，括號(hào)等被刪除）：using security.json with solr 變 using security json with solr
所有的空格都用連字符替換：using security json with solr 變 using-security-json-with-solr

示例

該文件schema-api.adoc有一個(gè)“修改架構(gòu)”部分，如下所示：

== Modify the Schema

`POST /_collection_/schema`

要從其他頁面鏈接到此部分，您需要?jiǎng)?chuàng)建一個(gè)如下所示的鏈接：

帶有section（schema-api.adoc）的頁面的文件名，
那么哈希符號(hào)（#），
那么轉(zhuǎn)換后的部分標(biāo)題（modify-the-schema），
然后顯示一個(gè)逗號(hào)和任何鏈接標(biāo)題。

上下文中的鏈接將如下所示：

For more information, see the section <<schema-api.adoc#modify-the-schema,Modify the Schema>>

更多信息：http : //asciidoctor.org/docs/user-manual/#inter-document-cross-references

有序和無序列表

AsciiDoc支持三種類型的列表：

無序列表
有序列表
標(biāo)記的列表

每種類型的列表可以與其他類型混合使用。所以，如果有必要的話，你可以在一個(gè)標(biāo)簽列表中有一個(gè)有序列表。

無序列表

簡(jiǎn)單項(xiàng)目符號(hào)列表需要每行以星號(hào)（*）開頭。它應(yīng)該是該行的第一個(gè)字符，后面跟著一個(gè)空格。

這些列表也需要從中分離出來

更多信息：http : //asciidoctor.org/docs/user-manual/#unordered-lists

有序列表

編號(hào)列表需要每一行以句點(diǎn)（.）開始。它應(yīng)該是該行的第一個(gè)字符，后面跟著一個(gè)空格。

這種風(fēng)格比手動(dòng)編號(hào)列表更受歡迎。

更多信息：http : //asciidoctor.org/docs/user-manual/#ordered-lists

標(biāo)記的列表

這些問題和答案列表或詞匯表定義。每行應(yīng)該以列表項(xiàng)開始，然后是雙冒號(hào)（::），然后是空格或換行。

標(biāo)記的列表可以通過添加額外的冒號(hào)（例如:::等）來嵌套。

如果您的內(nèi)容將跨越多個(gè)段落或包含源代碼塊等，您將需要添加一個(gè)加號(hào)（+）來保持閱讀器的各個(gè)部分。

我們更喜歡這些參數(shù)的列表樣式，因?yàn)樗试S更多的自由度來顯示每個(gè)參數(shù)的詳細(xì)信息。例如，它自動(dòng)支持內(nèi)部的有序或無序列表，并且您可以包含多個(gè)段落和源塊，而不必嘗試將它們?nèi)胍粋€(gè)較小的表單元格中。

更多信息：http : //asciidoctor.org/docs/user-manual/#labeled-list

圖像（Images）

有兩種方法可以包含圖像：內(nèi)聯(lián)或塊。

內(nèi)聯(lián)圖像是文字在圖像周圍流動(dòng)的位置。塊圖像是自己的行上出現(xiàn)的，從頁面上的任何其他文本出發(fā)。

兩種方法都使用圖像文件名之前的image標(biāo)簽，但在image定義后冒號(hào)的數(shù)量是內(nèi)聯(lián)還是塊。內(nèi)嵌圖像使用一個(gè)冒號(hào)（image:），而塊圖像使用兩個(gè)冒號(hào)（image::）。

塊圖像自動(dòng)包括一個(gè)標(biāo)題標(biāo)簽和一個(gè)數(shù)字（如Figure 1）。如果一個(gè)塊圖像包含一個(gè)標(biāo)題，它將作為標(biāo)題的文本包含在內(nèi)。

可選屬性允許您設(shè)置替代文本，圖像的大小，如果它應(yīng)該是一個(gè)鏈接，浮動(dòng)和對(duì)齊。

更多信息：http : //asciidoctor.org/docs/user-manual/#images

表（Tables）

表格可能很復(fù)雜，但要制作一個(gè)適合大多數(shù)需求的基本表格非常簡(jiǎn)單。

基本表

表格的基本結(jié)構(gòu)與Markdown類似，管道（|）分隔行之間的列：

|===
| col 1 row 1 | col 2 row 1|
| col 1 row 2 | col 2 row 2|
|===

注意|===在開始和結(jié)束時(shí)的使用。對(duì)于不完全需要的基本表格，但它確實(shí)有助于劃分表格的開始和結(jié)束，以防意外地在行之間引入（或者更喜歡）空格。

標(biāo)題行

要為表添加標(biāo)題，只需要header在表的開始處設(shè)置屬性：

[options="header"]
|===
| header col 1 | header col 2|
| col 1 row 1 | col 2 row 1|
| col 1 row 2 | col 2 row 2|
|===

定義列樣式

如果您需要為列中的所有行定義特定樣式，可以使用屬性來完成。

這個(gè)例子將把所有行的所有內(nèi)容放在中間：

[cols="2*^" options="header"]
|===
| header col 1 | header col 2|
| col 1 row 1 | col 2 row 1|
| col 1 row 2 | col 2 row 2|
|===

對(duì)齊或任何其他樣式只能應(yīng)用于特定的列。例如，這只會(huì)將表格的最后一列居中：

[cols="2*,^" options="header"]
|===
| header col 1 | header col 2|
| col 1 row 1 | col 2 row 1|
| col 1 row 2 | col 2 row 2|
|===

更多格式化的例子：

列：http : //asciidoctor.org/docs/user-manual/#cols-format
單元格：http : //asciidoctor.org/docs/user-manual/#cell

警告（注意，警告）

AsciiDoc支持幾種類型的標(biāo)注框，稱為“警告”：

NOTE
TIP
IMPORTANT
CAUTION
WARNING

用一個(gè)冒號(hào)（如NOTE:）開始一個(gè)段落就足夠了。當(dāng)它被轉(zhuǎn)換成HTML或PDF時(shí)，這些部分將被正確格式化 - 從主文本縮進(jìn)并顯示一個(gè)圖標(biāo)內(nèi)聯(lián)。

您可以通過將警告標(biāo)題添加到警告區(qū)塊來為警告添加標(biāo)題。警告塊的結(jié)構(gòu)是這樣的：

.Title of Note
[NOTE]
====
Text of note
====

在這個(gè)例子中，警告的類型被包含在方括號(hào)（[NOTE]）中，并且標(biāo)題以句點(diǎn)為前綴。四個(gè)等號(hào)表示注釋文本的起點(diǎn)和終點(diǎn)（可以包括新行，列表，代碼示例等）。

更多信息：http : //asciidoctor.org/docs/user-manual/#admonition