文档规范 - sofastack/sofastack.tech GitHub Wiki

所有提交到官网中的文档都有遵循以下规范，如有违反可能导致 CI 检查不通过，需要修复后重新提交。 这里所说的文档是指：content/ 目录下的所有 Markdown 文件。 文档规范主要包括以下几个类别：

• 命名规范
• Markdown 语法规范
• 其他约定

命名规范

文档的目录结构将直接反应在网站的 URL 上，因此需要对文章的命名作出规范：

• 所有文档的目录名使用全小写，单词间使用英文连字符链接，目录名称建议最长不要超过 20 个字符
• 所有文档都命名为 xxx/index.md，不再划分二级目录，project 的文档侧边栏通过在 project 的 _index.md 文件中配置完成

其他约定

除了了文档的命令规范和 Markdown 预发规范外，还有其他约定如下：

• 文档正文字数不要超过 3000 字，如内容过程可以分为多篇提交，这样便于构建 algolia 索引（algolia 对于单篇文章的有 10k 大小的限制）
• 图片尽量存储在 CDN 中，这样可以压缩代码库的大小