网站基于 GitHub Pages
和 Jekyll
,主题是 just-docs
,如果不需要本地运行网站的话,无需安装相关环境,直接克隆本仓库,创建和编辑 Markdown
文件即可,可以参考仓库里已有的 Markdown
文件。
文章编写规范请遵循:中文技术文档的写作规范
所有文档统一放置在 docs
目录中,按照顺序层级进行排列,最终会在网站左边的目录树中展示。
文档头需要增加目录信息说明,nav_order
参数代表该文件在左边目录树中的顺序,示例如下:
---
layout: default
title: Customization
nav_order: 4
---
如果文档有层级关系,
+-- ..
|-- (Jekyll files)
|
|-- docs
| |-- ui-components
| | |-- index.md (parent page)
| | |-- buttons.md
|
|-- (Jekyll files)
+-- ..
创建父文件夹和 index.md
文档,index.md
代表父文档,然后设置 has_children: true
参数,示例如下:
---
layout: default
title: UI Components
nav_order: 2
has_children: true
---
子文件里增加 parent
参数说明,值为 parent
文件里的 title
信息,示例如下:
---
layout: default
title: Buttons
parent: UI Components
nav_order: 2
---
如果子文档包含子文档,
+-- ..
|
|-- UI Components
| |-- ..
| |
| |-- Buttons
| | |-- Button Child Page
| |
| |-- ..
|
+-- ..
需要设置以下参数:
- 子文档添加
has_children
参数
---
layout: default
title: Buttons
parent: UI Components
nav_order: 2
has_children: true
---
- 子子文档添加
grand_parent
参数
---
layout: default
title: Buttons Child Page
parent: Buttons
grand_parent: UI Components
nav_order: 1
---
建议三层大纲结构:
- 说明
- 示例(截图可选,类似bottomSheet最好截图说明)
- 参数
- 参数包含字段:
- 属性名,类型,属性说明,必填,默认值,取值范围(function出入参也要做说明)
- 参数包含字段:
跳转到其他文档,示例如下:
[快速开始]({{ site.baseurl }}{% link docs/quick-start.md %})
所有资源文件统一放置在 assets
目录中,按照文件类型放置,比如图片放在 assets/images/**.png
。
- 文档站的版本管理功能
- 通用 style,attribute 梳理,颜色格式,单位说明 @昶行
- 左侧大纲结构确认,增加一个调试,@占坤
- 自定义组件、API 文档说明,待定,优先级不高