README

基于wulaphp的文档生成器。

安装

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

创建文档目录结构

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

./artisan booky init

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

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

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

配置

<?php

return [
  'dir'      => 'doc',
  'theme'    => 'wula',
  'summary'  => ['l1cls' => '', 'l2cls' => '', 'acls' => '', 'ccls' => ''],
  'theme_en' => 'wen',
  'plugins'  => [],
  'langs'    => ['default' => '中文', 'en' => '英文'],  
];

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

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

文档导航菜单(_summary.md)

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

- [简介](intro.md)
- [安装](install.md)
    * [安装步骤一](install1.md)
    * [安装步骤二](install2.md)   
- [...](xxx.md)

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

<ul class="navi-ul-1">
    <li class="active">
        <a class="active" href="..." >adfads</a>
        <ul class="navi-ul-2">
            <li> <a href="aaa">adfasdf</a> </li>
            <li> <a href="adsfasdf">adfasdf</a> </li>
        </ul>
    </li>
    <li></li>
    <li></li>
</ul>

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

文档编写

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

自定义文档变量

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

---
title: 文档标题
demo: [0|1] #是否生成html演示代码,不定义时默认为不生成演示代码.
layout: page1 # 页面使用的模板
index: abc adf efds # 全文索引关键词（字）
---

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

资源引用

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

[更多说明](../more.md)
![图片1](imgs/img.pnp)

<ul class="toc">
    <li>
        <a id="ref-header1" href="#header1">Header Text</a>
        <ul class="toc-1">
            <li>
            <a id="ref-header11" href="#header11">Header11 Text</a>
            </li>
        </ul>
    </li>
    <li><a href="#" id="ref-header2">Header2 Text</a></li>
</ul>

请使用CSS美化它.

模板

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

模板变量:

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

URL生成与资源引用

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

<a href="{'help.md'|docurl}">帮助</a>

<img src="{'logo.png'|docurl}"/>

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

搜索

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

{
    "hits":2,
    "execution_time":"1.399 ms",
    "q":"标",
    "pages":[
        {
            "url":"/aa.html",
            "title":"厉害的一篇文标 and php"
        },
        {
            "url":"/",
            "title":"厉害啊"
        }
    ]
}

生成索引

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

./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