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