-
Notifications
You must be signed in to change notification settings - Fork 185
文档规范
Jimmy song edited this page Jul 26, 2019
·
4 revisions
所有提交到官网中的文档都有遵循以下规范,如有违反可能导致 CI 检查不通过,需要修复后重新提交。
这里所说的文档是指:content/
目录下的所有 Markdown 文件。
文档规范主要包括以下几个类别:
- 命名规范
- Markdown 语法规范
- 其他约定
文档的目录结构将直接反应在网站的 URL 上,因此需要对文章的命名作出规范:
- 所有文档的目录名使用全小写,单词间使用英文连字符链接,目录名称建议最长不要超过 20 个字符
- 所有文档都命名为
xxx/index.md
,不再划分二级目录,project 的文档侧边栏通过在 project 的_index.md
文件中配置完成
除了了文档的命令规范和 Markdown 预发规范外,还有其他约定如下:
- 文档正文字数不要超过 3000 字,如内容过程可以分为多篇提交,这样便于构建 algolia 索引(algolia 对于单篇文章的有 10k 大小的限制)
- 图片尽量存储在 CDN 中,这样可以压缩代码库的大小
© 2019 The SOFAStack Authors