Markdown文档管理工具

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

案例

SummerPHP框架说明文档

组件

• Markdown转html: parsedown(无安全校验速度快)
• highlight.js 用于代码高亮
• 遍历md源文件夹: 用PHP实现的利用后根序遍历算法读取文件夹内所有文件的工具类(tool/Dir.php)
• 左侧目录树: 用PHP实现的生成HTML代码的工具类(tool/Html.php)

用法

• 将md文件放进src文件中, 其文件和目录的命名就是最终生成树型目录中的名字
• 将目录或文件名前加上前缀用来按顺序显示目录, 前缀格式为: _\d+_, 例如 _01_xxx.md. 最终目录中不会有此前缀
• 用PHP解释程序执行 compile.php 文件 (windows下建议用php7+: path/to/php.exe compile.php), 这一步会将md文件解析成html文件, 放到dist目录里
• Nginx/Apache 服务器
  • 建一个虚拟机 (例如：doc.hearu.top)
  • 将虚拟机的根目录指向 dist 目录
  • 虚拟机的入口文件设置为index.html
  • 启动服务器, 在浏览器里访问 doc.hearu.top 就可以了 (本地搭建需要修改hosts文件)

  // 一个nginx配置举例 (注意: root指令指向dist目录, 浏览器访问时, 不要在URL中输入dist, 否则访问不到js/css等静态文件)
  server {
          listen       80;
          server_name  www.test3.com;
  
  		index index.html;
  
          location / {
              root D:/server/code/markdown/dist;
          }
      }

小技巧

• 给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就可以全部重新编译了
• 程序编译时, 会把根目录下包含index字符串的md文件编译后, 复制到 dist/index.html 作为默认入口文件, 浏览器访问时可以不用输入index.html
• 总结