AsciiDoc 的相关整理

asciidoctor
Step1:下载安装  rubyinstaller-devkit

https://asciidoctor.org/

(c) Windows

To use Asciidoctor with Windows, you have two easy options.

Chocolatey

When you already use chocolatey on your machine, you can use:

choco install ruby

Then follow gem installation instructions.

Rubyinstaller

Or you use the Rubyinstaller, download the package for your Windows Version and after the installation go ahead with gem installation instructions.

Step2:

Open a terminal and type:

$ gem install asciidoctor

If you want to install a pre-release version (e.g., a release candidate), use:

$ gem install asciidoctor --pre

When you install a new version of the gem using gem install, you end up with multiple versions installed. Use the following command to remove the old versions:

$ gem cleanup asciidoctor

Step3:

Usage

If the Asciidoctor gem installed successfully, the asciidoctor command line interface (CLI) will be available on your PATH. To verify it’s available, run the following in your terminal:

$ asciidoctor --version

You should see information about the Asciidoctor version and your Ruby environment printed in the terminal.

Asciidoctor 2.0.10 [https://asciidoctor.org]
Runtime Environment (ruby 2.6.0p0 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)

Asciidoctor also provides an API. The API is intended for integration with other Ruby software, such as Rails, Sinatra and GitHub, and other languages, such as Java (via AsciidoctorJ) and JavaScript (via Asciidoctor.js).

Command line interface (CLI)

The asciidoctor command allows you to invoke Asciidoctor from the command line (i.e., a terminal).

The following command converts the file README.adoc to HTML and saves the result to the file README.html in the same directory. The name of the generated HTML file is derived from the source file by changing its file extension to .html.

$ asciidoctor README.adoc

Asciidoc Book Editor based on JavaFX 8

 Asciidoc FX is a book / document editor to build PDF, Epub, Mobi and HTML books, documents and slides. AsciidocFX is also a winner of Duke’s Choice Award 2015.

Figure 1. AsciidocFX - Duke’s Choice Award 2015 winner

Features

• Real-Time Preview

• Multi-platform (Windows, Mac, Linux)

• Creating Asciidoc Books

• Creating Markdown Books

• Creating PDF, HTML, Epub, Mobi, Odt, Docbook

• Epub Viewer

• External Browser Support

• Table Generator

• MathJax Extension

• PlantUML Extension

• ditaa Extension

• Filesystem Tree Extension

• JavaFX Charts Extension

• Source Code Highlighter

• Reveal.js Converter

• Deck.js Converter

• Nashorn support

• Pseudo Terminal Emulator

• Themeing (Dark & White) _New _

https://asciidocfx.com/

文前说明

作为码农中的一员，需要不断的学习，我工作之余将一些分析总结和学习笔记写成博客与大家一起交流，也希望采用这种方式记录自己的学习之旅。

本文仅供学习交流使用，侵权必删。
不用于商业目的，转载请注明出处。

1. AsciiDoc 简介

• AsciiDoc 是一种文本文档格式（轻量级的标记语言），用于编写注释、文档、文章、书籍、电子书、幻灯片、网页、手册页和博客。
  • AsciiDoc 文件可以翻译成多种格式，包括 HTML、PDF、EPUB、手册页面等。
  • AsciiDoc 是高度可配置的，用户可以定制和扩展 AsciiDoc 源文件语法和后端输出标记（几乎可以是任何类型的 SGML/XML 标记）。
  • AsciiDoc 是免费软件，并根据 GNU 通用公共许可证版本 2（GPLV2）的条款进行许可。

1.1 语法

1.1.1 文档头

• 可以包含文档头、作者、修订行、自定义属性等。
  • 头部可选但是必须在文档的顶部。

= My Document's Title
Doc Writer <doc.writer@asciidoctor.org>
v1.0, 2018-04-11
:toc:
:imagesdir: assets/images
:homepage: https://asciidoctor.org

My document provides...

1.1.2 标题

• 需要靠左侧顶格。
• 可以包含文档头、第 1 ~ 第 5 章节标题。
• 当使用项目文档类型（默认值）时，只能有一个 0 级的节标题（即，文档标题），并且它必须位于文档头中。
• 等号的数目与 HTML 输出中的标题级别相匹配。
  • 例如，（=）转换成为 <h2> 标签。

= 文档标题 (0级) =
== 段落标题 (1级) ==
=== 段落标题 (2级) ===
==== 段落标题 (3级) ====
===== 段落标题 (4级) =====

1.1.3 段落

• 段落不需要任何特殊的标记，段落只需要是连续文本的一行或多行。
  • 开始新的段落需要用一个空行进行分隔。
• 文档中的大部分内容是段落文本，因此 AsciiDoc 不需要任何特殊的标记或属性来指定段落内容。

Paragraphs don’t require any special markup in AsciiDoc. A paragraph is just one or more lines of consecutive text.

To begin a new paragraph, separate it by at least one blank line. Newlines within a paragraph are not displayed.

1.1.3.1 换行

• 在 AsciiDoc 中，相邻或连续的文本行形成段落元素。若要在另一个元素（如节标题或表）之后开始新的段落，则插入空行，然后继续键入内容即可。
  • 因为 AsciiDoc 转换文档时，相邻的文本行会被合并为单个段落，这意味着可以包装段落文本或将每个句子或短语放在单独的行上，输出中是不会出现换行的。
  • 如果希望保留段落中的换行符，可以使用加号 （+） 后的空格或 hardbreaks 属性。这样会导致每一行之后增加可见的换行标记（例如 <BR>）。

Rubies are red, +
Topazes are blue.

[%hardbreaks]
Ruby is red.
Java is black.

• 通过将 hardbreaks 属性添加到文档头部，可以在整个文档中保留换行符。

:hardbreaks:
......
Rubies are red,
Topazes are blue.

1.1.3.2 文字段落

• 由至少一个空间偏移的段落成为文字段落，文字段落中的所有行必须是相邻的。
  • 文本段落显示为预格式化文本，文本以固定宽度字体显示，空格和换行符都会被保留下来。

1.1.3.3 提示段落

• 主要是为了引起读者注意，用标签开头。
  • 标签必须大写，后面跟着冒号（：）。

标签	说明
NOTE	注释
TIP	提示
WARNING	警告
IMPORTANT	重要
CAUTION	注意

TIP: Pro tip...
IMPORTANT: Don't forget...
WARNING: Watch out for...
CAUTION: Ensure that...

• 当想对复杂内容应用警告时，可以将标签设置为块上的样式属性。
  • 下例是在分隔块上的属性列表中设置标签，标签必须大写。

[IMPORTANT]
.Feeding the Werewolves
====
While werewolves are hardy community members, keep in mind the following dietary concerns:

. They are allergic to cinnamon.
. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.
. Celery makes them sad.
====

• 可以使用 icons 参数制定图标的路径。

[icons="./images/icons/wink.png"]
NOTE: What lovely war.

• 使用 caption 参数定义警告标题返回的文本信息（在警告图标设置为可用时 icons 参数必须设置为 icons=None）。

[icons=None, caption="特殊提示"]
NOTE: This is my special note.

1.1.3.3.1 图标

• AsciiDoc 提供三种显示图标的策略。

  • 作为文本
  • 作为图像
  • 作为从图标字体中选择的字符。

• 使用图标属性控制策略。默认行显示返回的文本。

• 如果希望使用图像显示图标，可以在文档头中将图标属性设置为空值。如果正在转换为 DocBook，或者希望使用一种简单的方法使 HTML 可以脱机查看，则建议采用此策略。DocBook 工具链提供了警告和标注等图标的图像，这些图标可以用自己的自定义图标替换。如果使用内联图标宏，则需要为这些图标提供图像。

• 也可以使用字体图标设置为 AsciiDoc 图标，若要使用此特性，需要将图标文件属性的值设置为文档标题中的字体。可以从 Awesome 中获得更多的字体图标。这种方式默认情况下需要在线访问。

= Document Title
:icons: font
......
NOTE: Asciidoctor supports font-based admonition icons, powered by Font Awesome!

• HTML 格式输出。

<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Asciidoctor supports font-based admonition icons, powered by Font Awesome!
</td>
</tr>
</table>
</div>

• AsciiDoc 中添加了 Awesome 的字体超强样式表和字体文件的引用。

<link rel="stylesheet" href="http://cdnjs.cloudflare.com/ajax/libs/font-awesome/3.1.0/css/font-awesome.min.css">

1.1.3.3.2 Unicode 文本图标

• 代替图像或基于字体的图标，可以通过使用一个小技巧使用 Unicode 文本来表示警告图标。
• 如果在文档上没有设置图标属性，AsciiDoc 输出一个标识警告类型的文本标签。此标签的文本来自 AsciiDoc 属性。
  • 属性的名称是 <类型> 标题，其中 <类型> 是小写中的警告类型。例如，提示提示的属性是提示字幕。
• 可以将一个 Unicode 字形赋值给这个属性，而不是单词。

:tip-caption: