# PHP-Markdown-Doc

**Repository Path**: myDcool/PHP-Markdown

## Basic Information

- **Project Name**: PHP-Markdown-Doc
- **Description**: markdown文档管理工具, 可自动创建目录, 可指定顺序，支持多层级展开，支持目录高亮
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 32
- **Forks**: 20
- **Created**: 2017-09-18
- **Last Updated**: 2025-06-15

## Categories & Tags

**Categories**: markdown-utils

**Tags**: None

## README

## Markdown文档管理工具

> 可用于接口文档, 知识体系等, 支持多人协作, 可以在手机/浏览器端浏览

#### 版本说明
- 5.1 版本之前, 是用php的markdown解析工具解析的, 
- 6.0 以后的版本是用前端js插件去解析markdown文件的 (2023-09-19)
- 7.0 以后的版本是用前端js插件去展示菜单的 （2025-06-15）


#### 案例
- [MengPHP框架说明文档](http://www.hearu.top) 
- [知识库](http://docs.hearu.top/)
- [图片库](http://pics.hearu.top/index.html)
- [在线小说](http://xiaoshuo.hearu.top/index.html)

#### 架构
- 后端代码:
    - 读取源文件夹结构  
    - 将源文件改名转存到另一个文件夹下边
    - 生成前端搜索，菜单展示等功能使用的json数据
- 前端代码:
    - 实现菜单的交互
    - 支持搜索
    - 获取md文件,并解析成HTML渲染

#### 文件结构
* src/: markdown源文件, 支持多层文件夹嵌套和排序
* dist/: 从src/中提取所有文件, 统一存放在这里, 不再分层存放, 便于前端访问
* tool/: 读取源文件结构, 生成目录
* file_sign.php :支持增量编译, 用md5记录下每个文件的内容摘要, 如果发生变化才会被编译
* compile.php: 入口文件, 调度实现各个功能

#### 组件

* Markdown转HTML(js库): https://gitee.com/mirrors/marked
* 将本地文件目录转为json: 借鉴树的遍历算法，将多层文件映射生成json(自研，tool/FSM.php)
* 左侧目录树: 目录插件(自研，dist/static/sys/zbMenuPro.js)
* 搜索：支持自动补全（自研，dist/static/search/zbAsComplete.js）


#### 用法
* 将md文件放进src目录中, 其文件和目录的命名就是最终生成树型目录中的名字(支持多层嵌套)
* 将目录或文件名前加上前缀用来按顺序显示目录, 前缀格式为: `[\d+]`, 例如 `[001]xxx.md`. 最终展示时，目录中不会有此前缀
* 用PHP解释程序执行 `compile.php` 文件 (windows下建议用php7+: path/to/php.exe compile.php), 这一步会将md文件重命名, 放到`dist`目录里
* Nginx 服务器配置 
    * 配置好后, 启动服务器, 在浏览器里访问 www.doc.com 就可以了 (本地搭建需要修改hosts文件)
    * 一个nginx配置举例:
    ```
    server {
        listen       80;
        server_name  www.doc.com;

        location ~ \.(js|css|ico|png|jpg|gif)$ {
            root D:/server/code/mkdown/dist/static/;
            #expires 300d;
        }

        location ~ \.md$ {
            root D:/server/code/mkdown/dist/docs/;
            #expires 300d;
        }


        location / {
            root D:/server/code/mkdown/dist/;
            index index.html;
        }
    }
    ```

#### 小技巧
* 给git 加一个pre-commit hook, 将执行PHP编译md文件的命令放在 提交前 的时候执行, 这样就不用每次都手动执行编译命令了
* 给git 加一个post-push hook, 可以将_book作为git仓库, 提交(push)后自动部署到服务器根目录下
* code, table 的样式(github风格)已经写好了, 在 dist/static/sys/index.css，修改后不用重新编译

#### 说明
* 程序每次编译都会把编译后的内容记录下来`file_sign.php`, 下次编译的时候如果该文件没有修改, 就不会再编译了, 删掉`file_sign.php`就可以全部重新编译了
* `dist/index.tpl` 作为默认入口文件的模板, 是必须存在的, 这个文件已经在源码中了, 不能删掉