使用AsciiDoc文件

AsciiDoc語法表

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

AsciiDoc與Asciidoctor語法

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

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

基本的AsciiDoc語法

加粗（Bold）

將星號放在文字上以使其粗體。

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

斜體（Italics）

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

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

標題（Headings）

等號（=）用于表示標題級別。每個等號都是一個級別。每個頁面只能有一個頂層。

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

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

代碼示例（Code Examples）

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

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

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

示例源塊：

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

如果您的代碼塊將包含換行符，請在整個塊之前和之后放置4個連字符（----）。

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

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

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

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

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

塊標題（Block Titles）

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

.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時，Asciidoctor將自動呈現(xiàn)許多鏈接類型（例如http:和mailto:），而無需任何其他語法。

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

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

鏈接到其他頁面/部分

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

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

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

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

鏈接到同一頁上的部分

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

示例

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

== Field Properties

Field definitions can have the following properties:

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

See also the <<Field Properties>> section.

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

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

鏈接到具有錨點ID的部分

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

示例

以configsets-api.adoc這個例子為例：

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

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

• 從同一頁面，只需使用節(jié)點名稱：<<configsets-create>>。

• 在另一個頁面上，使用頁面名稱和節(jié)點名稱：<<configsets-api.adoc#configsets-create>>。

鏈接到另一個頁面

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

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

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

示例

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

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

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

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

鏈接到另一頁上的部分

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

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

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

示例

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

== Modify the Schema

`POST /_collection_/schema`

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

• 帶有section（schema-api.adoc）的頁面的文件名，

• 那么哈希符號（#），

• 那么轉(zhuǎn)換后的部分標題（modify-the-schema），

• 然后顯示一個逗號和任何鏈接標題。

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

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支持三種類型的列表：

• 無序列表
• 有序列表
• 標記的列表

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

無序列表

簡單項目符號列表需要每行以星號（*）開頭。它應該是該行的第一個字符，后面跟著一個空格。

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

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

有序列表

編號列表需要每一行以句點（.）開始。它應該是該行的第一個字符，后面跟著一個空格。

這種風格比手動編號列表更受歡迎。

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

標記的列表

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

標記的列表可以通過添加額外的冒號（例如:::等）來嵌套。

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

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

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

圖像（Images）

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

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

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

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

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

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

表（Tables）

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

基本表

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

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

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

標題行

要為表添加標題，只需要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|
|===

定義列樣式

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

這個例子將把所有行的所有內(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|
|===

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

[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

更多的選擇

表格還可以被賦予頁腳行、邊框和標題。您可以確定列的寬度或整個表的寬度。

也可以使用CSV或DSV來代替在管道中格式化數(shù)據(jù)。

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

警告（注意，警告）

AsciiDoc支持幾種類型的標注框，稱為“警告”：

• NOTE
  
• TIP
  
• IMPORTANT
  
• CAUTION
  
• WARNING
  

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

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

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

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

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

使用AsciiDoc文件的工具

AsciiDoc與Asciidoctor

Solr 參考指南以 AsciiDoc 格式編寫的。這種格式通常被認為是Markdown的擴展，因為它支持目錄，更好的表格支持和其他特性，使得它更適合編寫技術(shù)文檔。

我們正在使用AsciiDoc語法的一個版本以及來自一個名為Asciidoctor的開源項目的工具。這提供了對AsciiDoc語法的全面支持，但是用Ruby編寫的代碼取代了原來的Python處理器。有一個Java實現(xiàn)，稱為AsciidoctorJ。原始AsciiDoc項目的進一步擴展包括對基于字體的圖標和UI元素的支持。

Doc預覽

這允許您在接近于HTML輸出時看到您的文檔。

以下信息來自http://asciidoctor.org/docs/editing-asciidoc-with-live-preview。

• Atom有AsciiDoc預覽，它為您提供了一個在您鍵入時更新的面板。還有一些其他的插件來支持AsciiDoc格式和自動完成。
• Chrome，F(xiàn)irefox和Opera有一個實時預覽瀏覽器插件，允許你在瀏覽器中打開你的AsciiDoc頁面。它也將隨著你的輸入而更新。
• 還有一個Intellij IDEA插件來支持AsciiDoc格式。