本篇内容旨在帮助大家更规范的在看云完成写作，并且同时给用户带来良好的阅读体验。 >[danger] 下面规范内容大部分仅为建议或者推荐，并非强制。 * [1 文档规范](http://help.kancloud.cn/66780#1__6) * [文档规划](http://help.kancloud.cn/66780#_8) * [文档标识](http://help.kancloud.cn/66780#_18) * [文档描述](http://help.kancloud.cn/66780#_35) * [文档封面](http://help.kancloud.cn/66780#_41) * [2 目录规范](http://help.kancloud.cn/66780#2__51) * [目录结构规划](http://help.kancloud.cn/66780#_53) * [目录文件命名](http://help.kancloud.cn/66780#_64) * [3 内容规范](http://help.kancloud.cn/66780#3__90) * [目录层次](http://help.kancloud.cn/66780#_92) * [代码](http://help.kancloud.cn/66780#_106) * [链接](http://help.kancloud.cn/66780#_114) * [章节导航](http://help.kancloud.cn/66780#_125) * [其它](http://help.kancloud.cn/66780#_133) ## 1 文档规范 ### 文档规划 对于大量文档需求或者周期性文档写作需求的用户，建议分开不同的文档书写，编上期号或者集数，而不是混在一个文档里面写大量的内容，另外一方面，避免文档过大而超出限制大小无法继续编辑。 如果你的文档中需要使用代码高亮功能，确保在创建文档的时候使用的文档类型为技术文档，该类型会自动添加代码高亮插件。 如果你需要对文档的用户和产品做不同的区分的话，可以使用团队功能来区分不同的用户群和产品线，因为每个团队标识代表了不同的文档访问URL地址，相当于文档的命名空间，在创建文档的时候可以选择不同的团队或者用户标识。  ### 文档标识 文档的标识尽量采用容易识别的英文单词（全部小写，并且建议用`-`或者`_`分割），会让你的文档的URL地址更加美观和友好。 >[danger] 注意：文档标识不支持数字打头，最大长度为100个字符。 正确的： >[success] cloud-design-pattern > cloud\_design\_pattern 错误的： >[danger] Cloud\_Design\_Pattern > Cloud&Design&Pattern > clouddesignpattern ### 文档描述 给你的文档添加一个简短的描述文字，读者会在阅读文档之前首先看到。  ### 文档封面 最后一步，当你好不容易写完文档后，别忘了设计一张更适合的封面图片而不是采用默认生成的图片，对比下下面两个文档的效果就知道了：  文档封面图片在线的显示尺寸是：`173*231`，但建议尺寸是宽高至少：`800*1068`，超过比例部分的宽高将会截掉。 > 清晰的封面图片是为了导出文档中的效果更好，如果只是为了在线显示的效果，满足 173\*231 或者相同比例即可。 ## 2 目录规范 ### 目录结构规划 尽量首先对文档和书籍的目录结构做好统一规划，而不是想到一个添加一个。 目录的设计对于导出的电子文档格式会有一定的影响，通常对于书籍来说，一级目录是章，二级目录是节，内容多一些的书籍会把某些章节单独归类，例如：`第一部分 / 第一章 / 1.0 小节内容`这样的结构，在最终导出的PDF/WORD文档的页面，会按照章节自动分页。 >[info] 过多层次的目录会影响阅读体验，如非必要，建议最多采用三级目录 例如：  ### 目录文件命名 看云的每个目录都对应了一个实际的文件，因此无论是在线还是离线写作，目录的文件名尽量避免使用特殊字符，尤其是：`\/:*<>|"`。 >[danger] 事实上大多数情况下在线写作的时候系统会自动过滤，但离线写作的时候需要特别注意。 正确的： >[success] `cloud_design_pattern.md` > `cloud-design-pattern.md` 错误的： >[danger] `cloud<design>pattern.md` > `cloud_design_pattern` 实际上，目录文件命名的时候，为了方便离线写作的识别，我们更建议使用中文命名，例如： 正确的： >[success] `云计算设计模式-概述.md` 错误的： >[danger] `云计算设计模式|概述.md` ## 3 内容规范 ### 目录层次 如果你的内容是有层次关系的，建议尽量用`H2~H4`标识区分，并且便于自动提取当前页的目录，除非特别必要，谨慎使用`H1`，从`H2`开始是由于默认的样式`H2`带有一个下划线样式，很容易区分。  >[info] 对于H4以后的则不建议使用，可以考虑直接使用粗体替代。 不建议对H2~H4 再次使用粗体，例如：  >[info] 相关的样式可以通过自定义样式来做一些调整，避免固化。 ### 代码 **代码部分确保使用代码标签**，否则可能导致页面显示出错或者某些内容被过滤、混淆而导致预览和阅读出现问题，例如下面的示例中使用了单行代码和多行代码标签：  >[info] 对于很长的内容或者中文内容尽量少用单行代码标签，因为单行代码标签没有自动换行样式支持。 ### 链接 内容中的URL地址会自动转换为超链接，无需使用链接标签，但是需要注意，链接URL地址前后必须加上空格，否则可能会有混淆。 正确的： >[success] `广场地址 http://www.kancloud.cn/explore` 错误的： >[danger] `广场地址（http://www.kancloud.cn/explore）` ### 章节导航 对于较长的内容，建议采用 H2~H4 将内容层次化，并在开头或者需要的位置添加目录导航标识`[TOC]`，效果如图：  >[info] 如果发现`[TOC]`标签无法正常解析，最好在前后添加一个空行。 ### 其它 其他关于中文排版的规范可以参考这篇：[中文文案排版指北](http://www.kancloud.cn/thinkphp/chinese-copywriting-guidelines/)。