智能小程序文档编写指导&规范

如何编写

开启本地预览

进入 swan-docs，终端执行 npm start;

终端看到VuePress dev server listening at http://localhost:4000/docs/ 提示，启动成功。

访问 http://localhost:4000/docs/introduction/register/ 开始编辑（path与线上一致）。

编写

编辑器打开模块，找到你要编辑的文档所在文件夹，修改刷新浏览器即可看到修改。

新增文档

如果是新增文档，去到program-docs/nav/nav.yml新增一份配置（nav.yml配置说明见编写规范）。 然后到对应的目录下(program-docs/docs/)建立一个.md。

编写规范

导航配置

该配置相当于书的目录。 第一层级为header导航栏（一级导航），第二层级为左侧导航（二级导航），第三层级为左侧导航子导航（h1），第四层级为md页面（h2），第五层级为md页面内锚点（h3）。
第三层级是可选的，如果不配置text，则第三层级不显示。

nav.yml 例子如下

  1.     -
  2.       link: /design/principle
  3.       text: 设计
  4.       name: design
  5.       nav:
  6.         -
  7.           link: /design/principle
  8.           text: 智能小程序设计指南
  9.           name: book
  10.           sidebar:
  11.             -
  12.                 link: /design/principle
  13.                 text: 设计原则
  14.                 name: principle
  15.             -
  16.                 link: /design/specification
  17.                 text: 样式规范
  18.                 name: specification
  19.             -
  20.                 link: /design/component
  21.                 text: 组件
  22.                 name: component
  23.                 sidebar:
  24.                 -
  25.                     link: /design/header
  26.                     text: 头部组件
  27.                     name: header

定制模板

在.md文件中可以引入定制模板按参数替换即可

下载模板

  1. <div class="m-doc-custom-download">
  2.   <a href="{下载链接左}" class="m-doc-custom-download-left">
  3.     <img src="{图片左}">
  4.     <p>{文案左}</p>
  5.   </a>
  6.   <a href="{链接右}" class="m-doc-custom-download-right">
  7.     <img src="{图片右}">
  8.     <p>{文案右}</p>
  9.   </a>
  10. </div>

参数

  • {链接左} 替换成下载链接
  • {链接右} 替换成下载链接
  • {图片左} 替换成图片地址
  • {图片右} 替换成图片地址
  • {文案左} 替换成文案说明
  • {文案右} 替换成文案说明

双图模板 & 三图模板

  1.   <div class="m-doc-custom-img">{待选模板}</div>
  2.   // 待选模板
  3.   <div><img src="{图片}"></div>

参数

  • {图片} 替换成图片地址
  • {待选模板} 两图就复制两个待选模板进去，三图就复制三个待选模板进去，将{图片}替换要展示图片地址。

左图右文模板

  1.   <div class="m-doc-custom-text-image"><div>{待选模板}</div><div><img src="{图片}"></div></div>
  2.   // 待选模板1
  3.   <p class="m-doc-custom-text-image-h2">{标题文案}</p>
  4.   // 待选模板2
  5.   <notice>{加粗文案}</notice>
  6.   // 待选模板3
  7.   <p>{普通文案}</p>
  8.   // 待选模板4
  9.   <ul><li>{列表文案}</li><li>{列表文案}</li></ul>

示例模板

  1.   <div class="m-doc-custom-examples">{待选模板}</div>
  2.   // 待选模板
  3.   <div class="{待选样式}">
  4.     <img src="{图片地址}">
  5.     <p class="m-doc-custom-examples-title">{高亮文案}</p>
  6.     <p class="m-doc-custom-examples-text">{解释说明}</p>
  7.   </div>

参数

  • {图片} 替换成图片地址
  • {待选模板} 两列就复制两个待选模板进去，三列就复制三个待选模板进去。
  • {待选样式} 正确：m-doc-custom-examples-correct，错误：m-doc-custom-examples-error，警告：m-doc-custom-examples-warning
  • {高亮文案} 高亮的文案
  • {解释说明} 对示例的解释说明

控制在不同设备中显示

只在pc端显示添加 class="ispc"，只在百度 App端显示添加 class="isbox"，只在除百度 App外移动端显示添加 class="ismobile"，参考 设计-重创新 实现。