AsciiDoc 的相关整理

 

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 <[email protected]>
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: ?

[TIP]
It's possible to use Unicode glyphs as admonition icons.

• HTML 格式输出。

<td class="icon">
<div class="title">?</div> </td> 

1.