Panda Api纯文档编写和多级菜单目录文档

除了用json5编写接口文档，Panda Api还支持像微信公众号接口文档一样的纯文档编写, 例如 https://developers.weixin.qq.com/doc/offiaccount/Getting_Started/Overview.html 中的 开发前必读 的子菜单： 首页、更新日志、开发着规范、接口权限说明、全局返回码说明、入门指引 都是纯文档的，开始开发的子菜单：接入指南、接口域名说明、接口测试账号申请、报警排查指引也都是纯文档的。

这些文档都是纯文档的，不需要提供接口服务，也不需要进行测试，单纯的只是文档，这些文档和接口文档在一起，作为接口文档的一部分，进行更详细的说明。

Panda Api也支持这样的文档编写，使用Markdown语法，文档展示出来的时候，Panda Api会把markdown的内容渲染为html内容。

以下功能对markdown文档和json5文档都是适用的

支持多级菜单

可以使用文件夹支持多级菜单目录，文件夹目录会对应到菜单目录。像微信公众号开发文档的例子，我们可以这样建立目录和文件：

├── $1 开发前必读
│   ├── $1 首页.md
│   ├── $2 更新日志.md
│   ├── $3 开发者规范.md
│   ├── $4 接口权限说明.md
│   ├── $5 全局返回码说明.md
│   └── $6 入门指引.md
├── $2 开始开发
│   ├── $1 接入指南.md
│   ├── $2 接口域名说明.md
│   ├── $3 接口测试号申请.md
│   ├── $4 报警排查指引.md
│   └── $5 常见问题.md

多级菜单目录同样适用语言json5格式的接口文档，而且可以根据需要把json5文档和markdown文档混合放在同一级菜单中使用。

使用文件名控制菜单排序和名称

目录名和文件名的最开始有一个美元符号$加一个数字，这个表示菜单和文档在菜单上显示的排序，这个美元符号$和数字不会在菜单上展示出来。例如： $1 开发前必读，里面的1是排序，开发前必读是菜单名称。$1后面的空格是可选的。

api接口文档和markdown纯文档的顺序的统一的，也就是通过调整排序，使得纯markdown的文档可以穿插到api接口文档之间。

api接口文档和markdown接口文档都支持多级目录，多级目录会对应到前端的多级菜单上。

在文档中配置排序和名称

如果不想把排序order写在文件名上，或者文件名和显示的菜单名不一致，我们可以在对应md文件的内容头进行配置，例如我们把　想让更新日志在菜单上显示为：接口更新日志，　排序改为７，可以在$2 更新日志.md内容的开头进行设置：

在$2 更新日志.md的内容开头用三个反引号包裹，中间一个json5的配置，{menu_title: "接口更新日志",order:7}，　menu_title表示在菜单上显示的名称，order表示排序，如果在文件内容中设置了order，那么就以文件内容中的为准。如果文件名开头和文件内容开头都没有设置，那么默认的排序order是０，　默认的menu_title就是文件名。

配置文件夹菜单

所有的文件夹菜单，作为一个父级菜单，默认情况下，仅只是一个菜单，只能点开查看下级菜单，是不能点开查看这个菜单对应的页面内容的。

我们还可以在要展示内容的文件夹中创建一个文件$_folder.md来配置　是否可以点开展示内容show_content，以及要展示的内容，同时还可以配置这个菜单的排序order，名称menu_title，

例如我们想让开发前必读这个父级菜单，也可以点开展示内容，那么就在开发者必读这个文件夹中创建文件$_folder.md，内容如下：

\`\`\` // -> 这里是三个反引号,为了显示，所以加了三个反斜杆, 如果要复制使用，要去掉反斜杠
{
    menu_title: "6666",
    order:10,
    show_content:true
}
\`\`\` // -> 这里是三个反引号,为了显示，所以加了三个反斜杆, 如果要复制使用，要去掉反斜杠

# 这里是内容
# Hello World

配置后，开发前必读就变成了一个可以点开，并展示页面内容的菜单。点开展示的内容就是

<h1>这里是内容</h1>
<h1>Hello World</h1>

注意： 有且只有show_content设置为true，文件夹菜单可以被点击查看内容，默认情况下show_content的值都是true，也就是，只要有$_folder.md文件，那么就会变为可以点击菜单查看内容。除非show_content被设置为了false。

静态文件　图片或其它存放

写markdown文档的时候，经常会用到一些图片，我们可以把图片放到接口文档根目录的media目录或者static目录，比如一张图片a.png放到media目录里面，这时的路径是：media/a.png，我们在markdown文档中使用这个图片要这么写：

![xxx](/media/a.png)

xxx 是图片标签，根据自己的需要设置即可。

2020-02-22 08:25