Markdown文档管理工具

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

版本说明

5.1 版本之前, 是用php的markdown解析工具解析的, 6.0 以后的版本是用前端js插件去解析markdown文件的

案例

• MengPHP框架说明文档
• 知识库

架构

• 后端代码:
  • 读取源文件夹结构
  • 自动生成目录js
  • 将源文件改名转存到另一个文件夹下边
• 前端代码:
  • 实现目录折叠
  • 当前页面的目录高亮
  • 获取md文件,并解析成HTML渲染

文件结构

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

组件

• Markdown转HTML(js库): https://gitee.com/mirrors/marked
• 遍历md源文件夹: 利用后根序遍历算法读取文件夹内所有文件的工具类(tool/Dir.php)
• 左侧目录树: 生成HTML代码的工具类(tool/Html.php)

用法

• 将md文件放进src目录中, 其文件和目录的命名就是最终生成树型目录中的名字(支持多层嵌套)
• 将目录或文件名前加上前缀用来按顺序显示目录, 前缀格式为: _\d+_, 例如 _01_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|ico$ {
          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/my.css，修改后不用重新编译

说明

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