zDoc 是一种 wiki，设计它的目的和 markdown 是一样的。 后来我决定再重写一个解析器， 同时支持 zDoc 和 markdown 这两种语法。由于 markdown 语法偏弱，所以我选择了 GFM(github 的一种 markdown 方言) 来进行支持。

下面几点，在你阅读本篇文档的时候，需要先了解一下 …

    • 根据不同的文件扩展名，zDoc 解析器可以决定用哪种方法来解析 wiki 文件。

默认的，.md 文件就是 GFM 格式，.zdoc 文件就是 zDoc 格式2. 在同一个文件里，你不能混用 zDoc 和 GFM 语法，但是你可以混用 HTML3. 对于解析器，一个制表符和4个空格，是一样的

文档的元数据

我支持你用 zDoc，GFM(markdown的方言)和 HTML的一个我规定的子集书写你的文档。 一个文档可以有任意的元数据，以便其他程序使用。通常，这些元数据是声明在文档的开头部分。

zDoc 文档

  1. #title : 文档标题 #author : zozoh #author : wendal #tags : [Git,编译]
  • 对于名称为 "author" 或者 "verifier" 的元数据，一定认其值为一个列表
  • 或者用 [ 和 ] 包裹的值，半角逗号分隔也表示列表

    GFM 文档

除了文档标题，均采用 HTML 注释

  1. ---
  2. author : zozoh
  3. tags   : 
  4. - Git
  5. - 编译
  6. ---

HTML 文档

  1. <html>
  2. ...
  3. </html>
  • zDoc 解析器将任何 HTML 文件理解成根节点下仅有多个 HTML 类型的节点
  • 根据占位符和链接，来拆分 HTML 字符串

    zDoc和GFM 的语法

段落标题

  1. zDoc 的标题层级根据缩进的级别来划分
  2. ---------------------------------------- zdoc
  3. 标题 A
  4.     内容 A
  6.     标题 B
  7.         内容 B
  1. ---------------------------------------- GFM
  2. ## 标题 A
  3. 内容 A
  4. ### 标题 B
  5. 内容 B
  • zDoc 的文档层级划分是参考了 Python 语言，这是它 GFM 最大的区别
  • 对于 zDoc 来说，确定一个段落是否是标题，主要是看它后面有没有一个段落缩进层级比它更多。

    段落

  1. zDoc 和 GFM 一样，段落为连续两个段内换行，
  2. 段内换行 `\n` 表示一个空格，符号`\`表示跳过段内换行
  3. 下面两段文字输出的效果是一致的
  4. ---------------------------------------- zdoc
  5. 这里是段落A
  6. 这里还是段落A，实际是与上一行是一行
  8. ---------------------------------------- GFM
  9. 这里是段落A
  10. 这里还是段落A，实际是与上一行是一行
  11.  
对于段落，是自动作为自己前一个标题的内容，对于 zDoc 来说会根据缩进多一些判断。判断是否是一个 新标题的开始

内嵌锚点

  1. 对应 GFM 和 zDoc 任何一个标题都会有一个自动的锚点，锚点的值为
  2.     MD5(标题保留字母数字下划线和一切256以上的字符)
  3. 同时你可以通过内嵌 HTML 来做到这一点，声明自己自定义的锚点
  5. <a name="my_anchor"></a>
  6.  

链接

  1. zDoc 的链接写在 [..] 中，如果 [^..] 表示要在新窗口打开
  2. ---------------------------------------- zDoc 
  3. [http://nutzam.com]            本窗口跳转
  4. [^http://nutzam.com]           新窗口跳转
  5. [http://nutzam.com Google]     本窗口跳转, 带文字
  6. [http://nutzam.com <abc.png>]  本窗口跳转, 带图标
  7. [#- 标题A]           页内链接，会根据"标题A"自动计算锚点的值
  8. [#my_anchor]       自定义的页内链接
  9. [../readme.md]     指向一个 GFM 文档，链接文字会被这个文档标题替代
  10. [../readme.zdoc]   指向一个 zDoc 文档，链接文字会被这个文档标题替代
  12. ---------------------------------------- GFM
  13. [Nutz](http://nutzam.com)  相当于 [http://nutzam.com Nutz]
  14. http://nutzam.com          相当于 [http://nutzam.com]
  15. [](#- 标题A)                 相当于 [#- 标题A]
  16. [](#my_anchor)             相当于 [#my_anchor]
  17. [](../readme.md)           相当于 [../readme.md]
  18. [](../readme.zdoc)         相当于 [../readme.zdoc]

图片

  1. zDoc 的图片写在 <..> 中，只要不和它支持的 HTML 标签冲突即不会有问题
  2. ---------------------------------------- zDoc 
  3. <../imgs/abc.png>          采用原始宽高
  4. <../imgs/abc.png alt text> 采用原始宽高，指定鼠标悬停文字
  5. <80:../imgs/abc.png>       指定宽度为 80
  6. <x90:..imgs/abc.png>       指定高度为 90
  7. <80x90:imgs/abc.png>       指定宽高为 80x90
  9. ---------------------------------------- GFM
  10. ![](../imgs/abc.png)           相当于  <../imgs/abc.png>
  11. ![alt text](../imgs/abc.png)   相当于  <../imgs/abc.png alt text>
  12. ![80:](../imgs/abc.png)        相当于  <80:../imgs/abc.png>
  13.  

列表

  1. ---------------------------------------- zDoc 
  2. # 有序列表
  3.     # 有序列表
  4.     # 有序列表
  5. * 无序列表
  6.     * 无序列表
  7.     * 无序列表
  9. ---------------------------------------- GFM
  10. 1. 有序列表
  11.     a. 有序列表
  12.     B. 有序列表
  13. * 无序列表
  14.     - 无序列表
  15.     + 无序列表
  16.
对于列表来说，只有遇到了和自己类型不一致的列表，或者非列表段落才算终止。 列表内的缩进段落均属于当前列表

代码

  1. 通过 `<Java>` 来声明代码的语言类型，可选   
  2. ---------------------------------------- zDoc 
  3. {{{<Java>
  4. public class Abc {
  5.     ...
  6. }
  7. }}}
  9. GFM 的代码片段，语言声明也是可选的
  10. ---------------------------------------- GFM
  11. ```Java
  12. public class Abc {
  13.     ...
  14. }
  15. ```
  16. 或者所有代码至少带一个缩进
  18.     public class Abc {
  19.         ...
  20.     }
  21.  

表格

  1. 对 zDoc 来说，行开始是否为 `||` 很重要，表头可选
  2. ---------------------------------------- zDoc 
  3. || A1  || B1  || C1  ||
  4. || --- ||:---:|| ---:||
  5. || A2  || B2  || C2  ||
  7. 对 GFM 来说，表头为必须，是否有有表头分隔行很重要
  8. ---------------------------------------- GFM
  9. | A1  | B1  | C1 |
  10. | --- |:---:|---:|
  11. | A2  | B2  | C2 |
  12.  
对于 .zdoc 的文件，你可以用 GFM 支持的表格形式编写表格

引用

  1. zDoc 和 GFM 支持同样的引用格式
  3. > 一级引用
  4. > > 二级引用
  5. > 回到一级引用
  6. Z

行内文字

  1. 通过 {..} 来为一段文字声明特殊的样式
  2. ---------------------------------------- zDoc 
  3. 粗体         {*some text}
  4. 斜体         {/some text}
  5. 下划线    {_some text}
  6. 穿越线    {~some text}
  7. 红色斜体       {#F00;_some text}
  8. 穿越线斜体  {*/~some text}
  9. 标注         {^sup}
  10. 底注         {,sub}
  12. ---------------------------------------- GFM
  13. 粗体         **some text** 或 __some text__
  14. 斜体         *some text*   或 _some text_
  15. 穿越线    <del>some text</del>
  16.

分割线

  1. 支持连续 ---- 以上的减号作为分割线

逃逸字符

  1. 任何一个被 `` 包裹的文字，都被逃逸，连续两个 `` 表示一个普通的 ` 字符
  2. 如果仅仅想逃逸特殊符号，之前加一个 '\' 即可，特殊字符 '\' 如果不是在行尾
  3. 那么它就是用来逃逸下一个字符，因此它也能被用来逃逸自身
  4.  

占位符

  • 无论 zDoc 和 GFM，以及 HTML 都支持 - {placeholder} 来声明占位符，
  • 根据 zdoc.conf 中声明的 zdoc-vars 来为占位符设值

    外部链接文档

如果很多文档都有共同的段落，你可以声明一个外部链接段落，引入共同的部分，这是个补充语法，zDoc,GFM, HTML 都支持，你只需要在任意的地方声明一个 HTML 注释即可

  1. <!--@import head.menu-->
  2.  

需要说明的一点是， zDoc 和 GFM 你必须把这个声明放到一个单独的段落里，所以下面的链接是不生效的，其效果就是普通的注释:

  1. A<!--@import head.menu-->B

你必须写成这样才行

  1. A
  3. <!--@import head.menu-->
  5. B
  6.  

当然，在一行中，前后空格是无所谓的

嵌入式 HTML

zDoc 还是 GFM 都支持直接书写 HTML 子集， GFM 由于 markdown 的语法对于缩进不敏感,因此可以在任何段落里书写 HTML，比如

  1. 这是我的一段<b style="color:red">加粗加红色</b> 文字
  2. <p>
  3. 我可以用 `<p>` 声明一个段落
  4.  

对于 zDoc，你也可以在任何段落写 HTML，但是如果你想写大段的 HTML，比如表格等比较复杂的 HTML结构，你需要这么写

  1. <HTML>
  2. <Table>
  3.     <tr><td>列A</td><td>列B</td></tr>
  4.     <tr><td>aa</td><td>bb</td></tr>
  5. </table>
  6. </HTML>
  7.  

即，你的 HTML 代码，由 <html> 标签包裹，且这两个开始结束标签必须是单独一行。这时，会调用HTML 子集 对应的解析方式来分析 HTML。

当然如果你想在普通的段落里随便嵌入 <a> 和 <img> 等 HTML 子集 允许的行内标签，对于zDoc 和 GFM 都是一样的，您随意 ^

HTML 子集

无论是 GFM 还是 zDoc 都支持内嵌 HTML 标签，当解析器遇到和可以理解的 HTML 标签 它会将其进行解析，丢弃不支持的属性，你可以在行内或者段落甚至文档级别应用 HTML 标签。 同时，如果你的文档本身就是 html 文档，zDoc 从 开始，会统一理解你的这些标签。

下面有一些注意事项

  • 所有不认识的属性和标签将被丢弃，就好像你没写过它们一样
  • 标签的大小写并不敏感
  • 标签的属性可以不必用双引号包裹，单引号，或者不包裹均可
  • 对于 .html|.htm 文件，如果没有元数据 zdoc=true，则认为是普通 HTML 文件
    • 普通 HTML 将会替换相应的 src,href 等属性
    • 仅仅是这样
TAG Name Attributes Example
A 链接 href,target="blank" <a href="http://nutzam.com">Nutzam</a&gt;
A 锚点 name <a name="my_anchor"></a>
BR 换行 — <br>
B,I,U,EM 文字 style <b style="color:red">哈哈</b>
STRONG 文字 style <strong style="color:red">哈哈</strong>
SUB,SUP 文字 style 脚注和尾注
CODE 文字 — 相当于反引号引用的部分
IMG 图片 src,width,height,title <img src="abc.png">
P 段落 align <p align="left">我是一段文字
BLOCKQUOTE 引用 — <blockquote>我是引用文字</blockquote>
H1-H6 标题 — <h2>我是二级标题</h2>
OL,UL,LI 列表 — —
TABLE 表格 — —
COLGROUP,COL 表格 align 只有这里才能声明单元格左右对齐
TR,THEAD 表格 — THEAD 里只能是 TH, TR 里只能是 TD
TH,TD 表格 — —
HR 水平线 — <hr>
!— 注释 — <!—这里随便写什么注释—>
PRE 代码 title <pre title="java">public class .. </pre>

对于文字的 HTML 标签，支持 style 指定的 CSS

  1. color : #FF0 | #FF00AA | red
  2. background-color :  #FF0 | #FF00AA | red
  3. text-decoration: line-through
  4.  

原文:

http://nutzam.com/zdoc/syntax.html