Download the PHP package wula/booky without Composer

BOOKY

基于wulaphp的文档生成器。

安装

1. composer require wula/booky -vvvv
   • 请耐心等待,有时可能会很慢，很慢。。。
2. vender/bin/wulaphp init
   • 初始化wulaphp目录结构。
3. vender/bin/wulaphp conf
   • 获取nginx或httpd的配置，复制并配置你的nginx或httpd。

创建文档目录结构

执行以下命令创建文档目录结构:

./artisan booky init

booky init命令将创建doc目录并添加以下文件:

1. _summary.md 文档导航菜单
2. index.md 默认文档首页

同时生成文档配置文件: conf/booky_config.php。

配置

1. dir: 文档目录。
2. theme: 默认语言的模板主题
3. theme_en: 语言en的模板主题
4. plugins: 可以配置自己的插件.
   • 插件的全类名
5. summary : 配置导航菜单ul,a标签类
   • l1cls: 第一级导航ul标签类
   • l2cls: 第二级导航ul标签类
   • l3cls: 第三级导航ul标签类
   • acls: A标签类
   • ccls: 当前A标签类

其它配置，请根据需要自行添加，模板中通过$config变量引用.

文档导航菜单(_summary.md)

在_summary.md文件中通过markdown的列表语法定义文档导航菜单:

模板中通过$summary引用, booky生成的HTML代码如下:

请通过CSS来美化导航菜单.

文档编写

请使用markdown语法(支持extra)编写你的文档。

自定义文档变量

可以通过在文档头部添加yaml格式的字符串为文档添加自定义配置，格式如下:

除以上配置外，可任意添加配置,在模板中通过$page变量引用,如:$page.title为文档标题。

资源引用

在md文件中直接基于相对目录进行资源引用即可，如:

TOC

booky会根据文档正文的标题生成相应的toc，可以通过$page.tocStr或$page.toc在模板中引用。生成toc时会忽略掉跳级的标题。

tocStr片断如下:

请使用CSS美化它.

模板

booky使用smarty模板引擎，模板文件位于themes目录中。

模板变量:

1. $summary: 目录导航菜单
2. $url: 当前页面的url
3. $config: 配置，是个数组。
4. $nextPage，$prevPage: 上一个文档，下一个文档
   • url: URL
   • name: 标题
5. $page: 页面
   • title: 页面标题
   • tocStr: toc HTML片断
   • toc: toc 实例，可遍历
   • content: 文档正文
   • 其它自定义变量

URL生成与资源引用

在模板中通过docurl修饰器生成文档或资源的url，如：

URL会基于文档根目录生成。

搜索

BOOKY提供了搜索接口，可以通过ajax方法访问/search-doc?q=进行搜索，q为搜索词,搜索结果如下:

生成索引

在使用搜索功能之前，需要通过:

./artisan booky index

生成文档的搜索索引，每次新增、修改或删除文档后都需要执行此命令重新生成索引。

插件

写一个类实现\wula\booky\plugin\Plugin接口，并将类的全类名配置到plugins数组中即可。

高级

为了加快文档资源的访问，请修改相应的配置

nginx

在配置文件中找到:

location ~ ^/(modules|themes)/.+\.(js|css|png|gif|jpe?g)$ {

修改为:

location ~ ^/(modules|themes|doc)/.+\.(js|css|png|gif|jpe?g)$ {

httpd

在配置文件中找到:

AliasMatch "^/(modules|themes)/(.+\.(js|css|jpe?g|png|gif))$"

修改为:

AliasMatch "^/(modules|themes|doc)/(.+\.(js|css|jpe?g|png|gif))$"