顶级目录结构

zDoc 假想你的工作目录由如下结构组成

  1. [imgs]       # 存放你所有的图片文件，zDoc 会全部 copy 到目标目录
  2. [js]         # 存放你所有的脚本文件，zDoc 会全部 copy 到目标目录
  3. [css]        # 存放你所有的样式表单，zDoc 会全部 copy 到目标目录
  4. [_tmpl]      # 这里存放模板，一个网站可以有多个模板
  5. [_libs]      # 这里存放代码片段
  6. zdoc.conf    # 你的网站项目的总体配置文件
  7. index.xml    # 【选】你的文档索引的顺序
  8. index.html   # 所有的 HTML,markdown,zDoc 文件都会一视同仁进行转换
  9. readme.md     
  10. aboutus.zdoc
  11.  

_tmpl 目录

这个目录就是给 ZDocTemplateFactory 的实现类使用的模板目录。具体如何获取模板，由实现类决定，下面我就用默认提供的 FreemarkerTemplateFactory 来作为例子:

  1. [_tmpl]                # 目录内任何一个 .ftl 文件就是一个Freemarker模板
  2.     normal.ftl         # 这个模板的名字为 "normal"
  3.     [black]             
  4.         myblank.ftl    # 这个模板的名字为 "black.myblank"
  5.

无论你是什么模板引擎，你都会得到一个用 org.nutz.lang.util.NutMap 封装的一个上下文:

  1. {
  2.     siteTitle : "雨打沙滩点点坑",   // 整个站点的标题
  3.     topTags   : [{key:'34..a9',text:'翻译',count:87},{...}],
  4.     othersTag : {key:'others',text:'未归类',count:194},
  5.     tags      : [{key:'ae..f0',text:'小说',count:87},{...}],
  6.     tagPath   : 'tags',   // 要将所有的 tag 索引页输出到哪个路径
  7.     // 每个页面模板将额外得到这个属性
  8.     // 如果对应 tag 页面，只有 title, 和 bpath 有效
  9.     doc : {
  10.         author   : [{name:'zozoh',email:'zozoh@me.com'},{...}],
  11.         verifier : [{name:'zozoh',email:'zozoh@me.com'},{...}],
  12.         title    : '文档的标题',
  13.         tags     : ['标签A', '标签B', '标签C'],
  14.         lm       : Date(2014-12-09 12:34:21),
  15.         rpath    : 'post/2014/001.md',   // 相对于根的路径
  16.         bpath    : '../..',              // 回到根的路径
  17.         conent   : '<div>.....</div>',   // 渲染出来的 HTML
  18.         ... 剩下的是你在 doc 声明的对应属性 ...
  19.     }
  20.     // 每个标签列表页将额外得到这个属性
  21.     tag  : {
  22.         key   : '45..f2',
  23.         text  : '翻译',
  24.         count : 53,
  25.         items : {
  26.             // @see ZDocIndex.toMap()
  27.         }
  28.     }
  29. }

因此在任何模板引擎里，如果要输出标题，应该支持类似如下写法:

  1. ...
  2. <title>- {doc.title}</title>
  3. ...

_libs 目录

和 _tmpl 目录基本一样 …

zdoc.conf

放置这个文件的的目录将作为 zdoc 的工作目录，这个文件也不是必须的，如果没有，一切将采用默认值

  1. #-----------------------------------------------------------
  2. # 模板目录，默认 _tmpl
  3. zdoc-tmpl=_tmpl
  4. #-----------------------------------------------------------
  5. # 代码片段目录，默认 _libs
  6. zdoc-libs=_libs
  7. #-----------------------------------------------------------
  8. # 下面的路径，都是要全部执行 copy 的，如果比较多，可以变成一行一个
  9. zdoc-rs=imgs,js,css,main.html
  10. #-----------------------------------------------------------
  11. # 当渲染输出到 HTML 文件时，也会在目标目录生成一个索引页
  12. # 本配置项指明了这个索引页的名称，如果为空，则不生产索引页
  13. # 这个路径需要在 "zdoc-rules" 项目里找到相应的模板才行
  14. zdoc-html-index-path=index.html
  15. #-----------------------------------------------------------
  16. # 这里定义了整个站点顶级标签
  17. zdoc-tag-tops=翻译,小说,技术文章,日记
  18. # 没有打上标签的文章会归入"others"标签，下面的配置项给出了"others"标签的显示名
  19. zdoc-tag-others=未归类
  20. # 所有输出的标签索引页，输出到哪个路径，默认为 'tags'
  21. zdoc-tag-path=tags
  22. #-----------------------------------------------------------
  23. # 网页的模板设置
  24. #
  25. #  > 每行两个字段 :  [网页路径匹配模式(正则表达式)]  : 模板名
  26. #  > 排在第一行的匹配规则有更高的优先级
  27. #
  28. zdoc-rules:
  29. tags         : tag
  30. index.html   : index
  31. /page/.*     : black.page
  32. .*           : none
  33. # ~ 结束模板设置
  34. #-----------------------------------------------------------
  35. # 你可以声明一组变量，在文档中通过占位符使用它们，这样你就能声明自己的术语表
  36. zdoc-vars:
  37. Nutz=[http://nutzam.com Nutz]
  38. # ~ 结束变量声明
  39.  

关于标签

2. zDoc工作目录约定 - 图1
2. zDoc工作目录约定 - 图2

原文:

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