Flatworm 文档渲染引擎被设计得非常简单，但为记录 JavaScript 库提供了足够的必要格式化。
它的很多灵感来自 Read the Docs(link-rtd)和Sphinx(link-sphinx)项目。
每个页面是由片段组成的。每个片段是一条指令, 有一个值和可选的链接, 拓展 和一个主体。
许多的指令在他的值和主体支持markdown
一个片段的主体一直持续到遇到另一个片段的主体。
_DIRECTIVE: 值 @<LINK> @EXTENSION<PARAMETER>
BODY
MORE BODY
DIRECTIVE: 指令名称
VALUE: 可选的; 要传递给指令的值
LINK: 可选的; 一个用于内部链接的名称
EXTENSION: 可选的; 拓展指令的功能
PARAMETER: 可选的; 用来传递给扩展指令功能的值
BODY: 可选的; 指令主体内容（仅适用于某些指令）
_section: TITLE
section的TITLE字体样式为H1。Sections会被链接到目录中，并在它们的上方有一条分界线。
正文支持markdown。
每页应该只能有一个 _section:。
拓展: @inherit, @src, @nav, @note
_subsection: TITLE
subsection的TITLE字体样式为H2。会被链接到目录中，并在它们的上方有一条分界线。
标题和正文支持markdown。
拓展: @inherit, @src, @note
_definition: TERM
definition的TERM是正常文本，正文是缩进的
标题和正文支持markdown。
_property: SIGNATURE
property有它的JavaScript SIGNATURE格式化.
正文支持markdown并且signature返回的部分支持markdown链接
拓展: @src
_note: BANNER
note被放置在蓝色边框的盒子中以此引起对它的注意。
正文支持markdown。
_warning: BANNER
warning被放置在橙色边框的盒子中以此引起对它的注意.
正文支持markdown。
_code: CAPTION
创建一条代码 block。
正文不支持markdown, 同时将会按照原样输出, 除了代码评估以外.
如果一行以一个"_"开头, 它应该以一个"\"转义。
拓展: @lang
_table: FOOTER
根据正文创建一个表格结构。
每个单元格支持markdown并且变量支持markdown.
拓展: @style
_toc:
toc注入目录, 将主体的每一行作为文件名加载，如果存在的话，递归加载toc,否则的话，会加载所有的sections和subsections.
正文不支持markdown, 因为它被解释为一个要处理的文件和目录的列表。
_null:
null是用来终止命令的。 打个比方, 在definition之后, 主体是缩进的, 所以null可以用来重置缩进。
主体支持markdown。
_section: Hello World @<link-main>
Body for section...
_subsection: Some Example @<link-secondary>
Body for subsection...
_heading: Large Bold Text @<link-here>
Body for heading...
_definition: Flatworm
A phylum of relatively **simple** bilaterian, unsegmented,
soft-bodied invertebrates.
_property: String.fromCharCode(code) => string
Returns a string created from //code//, a sequence of
UTF-16 code units.
_code: heading
// Some code goes here
while(1);
_table: Table Footer
| **Name** | **Color** |
| Apple | Red |
| Banana | Yellow |
| Grape | Purple |
_toc:
some-file
some-directory
_note: Title
This is placed in a blue box.
_warning: Title
This is placed in an orange box.
_null:
This breaks out of a directive. For example, to end
a ``_note:`` or ``_code:``.
markdown是很简单并且没有其他语种的灵活性, 但允许粗体, 斜体, 下划线, 单空格, 上标 and 删除文本, 支持链接和列表。
列表是作为正文的块所渲染的，所以不能在标题或另一个列表中使用。
**bold text**
//italic text//
__underlined text__
``monospace code``
^^superscript text^^
~~strikeout text~~
- This is a list
- With bullet points
- With a total of three items
This is a [Link to Ethereum](https://ethereum.org) and this
is an [Internal Link](some-link).
This is a self-titled link [[https://ethereumorg]] and this
[[some-link]] will use the title from its directives value.
代码指令创建了一个有用的单空间包含块，用于显示代码示例。
对于JavaScript文件, 文件被编译并在VM中执行，允许块的输出(或异常)被包含在片段的输出。
整个代码片段 源是包括在一个异步IIFE中,这就意味着await是被允许的,并且少量的特殊注释代码是被允许的。
//_hide: 直接将以下代码包含在输出中，但不会将其包含在生成的片段输出中。
//_log: 在输出中包括以下任何表达式的值，前缀为' ' // ' ',如果可以的话，渲染器将会以不同的样式标记输出。
//_result: 将会开始一个块, 内容分配给_。这个块会以一个//_log:或者 //_null:结束,如果没有给定log值, 那么假定为_。如果发生错误，则生成失败。
//_throws:将开始一个块, 该块将抛出分配给 _的错误.这个块可以以一个 //_log:或者//_null:结束, 如果没有给定log值, 那么假定为_。 如果没有发生一个错误，则生成失败。
_code: Result of Code Example @lang<javascript>
//_hide: const url = require("url");
//_result:
url.parse("https://www.ricmoo.com/").protocol
//_log:
//_throws:
url.parse(45)
//_log:
// You want to assign (doesn't emit eval) AND display the value
const foo = 4 + 5;
//_log: foo
url.parse("https://www.ricmoo.com/").protocol
// 'https:'
url.parse(45)
// Error: The "url" argument must be of type string. Received type number (45)
const foo = 4 + 5;
// 9
语言可以用@lang extension来指定。
| Language | Notes | |
| javascript | Syntax highlights and evaluates the JavaScript | |
| script | 和javascript一样, 但是不会评估结果 | |
| shell | Shel脚本或者命令行 | |
| text | 没有语法要点的纯文本 | |
table指令会占用整个指令体，直到下一个指令。为了开始一个文本块而提前终止表格,使用_null:指令。
正文的每一行应该是Row Data 或者 一个 Variable Declaration (一个变量声明的延续). 空行会被忽略。
每个Row Data 行必须以一个"|"开头和结尾,每个间隙代表着单元格数据,alignment带有可选的column and row spanning。
单元格的对齐方式由单元格数据周围的空格决定。
| Alignment | Whitespace | |
| Left | 内容前的空格不超过1个 | |
| Right | 内容后的空格不超过1个 | |
| Center | 在内容的之前和之后都有2个以上的空格 | |
| 对齐条件 (优先级高的排在前面) | |
_table: 对齐示例结果 @style<compact>
| center |
| left |
|left |
| right |
| right|
| center | |
| left | |
| left | |
| right | |
| right | |
| 对齐示例结果 | |
一个列可以以任意数量的 "<"结束它的内容，这表示要拓展到多少个额外的列。
如果单元格内容只包含一个 "^", 那么上面的行会被拓展到这个单元格 (拓展到相同数量的列)。
_table: 单元格扩展示例结果 @style<compact>
| (1x1) | (1x2) <| (2x1) |
| (2x2) <| (2x1) | ^ |
| ^ | ^ | (1x1) |
| (1x1) | (1x2) | (2x1) | |
| (2x2) | (2x1) | |
| (1x1) | |
| 单元格扩展示例 | |
表格的@style extension可以用来控制它的外观。
| Name | Width | Columns | |
| minimal | 最小长度 | 最适合的 | |
| compact | 40% | 等间距的 | |
| wide | 67% | 等间距的 | |
| full | 100% | 等间距的 | |
通常情况下，表的布局更易于表达和维护，而不会不均匀或改变其中的内容。在一条table指令中使用variables单独定义内容。变量名必须以字母开头，并且只能包含字母和数字。
当内容在表中重复的时候，变量也会很有用。
变量是通过以"$NAME:"开头的行来声明的, 它占用下一个变量声明或者下一个表格的行之前所有的行。
变量名必须以字母开头，可以由字母和数字组成。(i.e. /[a-z][a-z0-9]*/i)
_table: 示例变量的结果
$Yes: 这个选项是支持的。
$No: 这个选项是不支持的。
$bottom: 这只是一个可能的例子。注意的是变量内容可以跨越多行。
| **Feature** | **Supported** |
| Dancing Monkey | $Yes |
| Singing Turtle | $No |
| Newt Hair | $Yes |
| $bottom <|
| Feature | Supported | |
| Dancing Monkey | 这个选项是支持的。 | |
| Singing Turtle | 这个选项是不支持的。 | |
| Newt Hair | 这个选项是支持的。 | |
| 这只是一个可能的例子。注意的是变量内容可以跨越多行。 | |
| 示例变量的结果 | |
配置上可选的（但强烈建议）并且可能是放在源文件夹顶部简单的JSON文件(config.json)或者JS文件(config.js)。
TODO: example JSON and example JS
向指令添加继承说明。markdown可能包含链接。
将语言设置成code directive应该凸显出语法。如果是"javascript",代码将会被评估。
当不是当前节点时，在breadcrumbs中设置名称。
向指令添加注释。The markdown可能包含链接。 如果指令已经有一个@INHERIT拓展名, 则将该使用该拓展名并且@NOTE将会被忽略。
调用配置getSourceUrl(key, VALUE)来获取一个URL，该URL将会通过指令旁边的链接链接到该URL。
这个拓展的指令函数需要一个高级的config.js 配置文件因为它需要一个JavaScript函数。
Table Style用于table指令。