文字

本篇内容旨在帮助大家更规范的在看云完成写作,并且同时给用户带来良好的阅读体验。

下面规范内容大部分仅为建议或者推荐,并非强制。

1 文档规范

文档规划

对于大量文档需求或者周期性文档写作需求的用户,建议分开不同的文档书写,编上期号或者集数,而不是混在一个文档里面写大量的内容,另外以方便,避免文档过大而超出限制大小无法继续编辑。

如果你的文档中需要使用代码高亮功能,确保在创建文档的时候使用的文档类型为技术文档,该类型会自动添加代码高亮插件。

如果你需要对文档的用户和产品做不同的区分的话,可以使用团队功能来区分不同的用户群和产品线,因为每个团队标识代表了不同的文档访问URL地址,相当于文档的命名空间,在创建文档的时候可以选择不同的团队或者用户标识。

文档标识

文档的标识尽量采用容易识别的英文单词(全部小写,并且建议用-或者_分割),会让你的文档的URL地址更加美观和友好。

注意:文档标识不支持数字打头,最大长度为100个字符。

正确的:

cloud-design-pattern
cloud_design_pattern

错误的:

Cloud_Design_Pattern
Cloud&Design&Pattern
clouddesignpattern

文档描述

给你的文档添加一个简短的描述文字,读者会在阅读文档之前首先看到。

document/2015-09-22/56011a635939e

文档封面

最后一步,当你好不容易写完文档后,别忘了设计一张更适合的封面图片而不是采用默认生成的图片,对比下下面两个文档的效果就知道了:

document/2015-09-22/56011612e7bf5

文档封面图片在线的显示尺寸是:173*231,但建议尺寸是宽高至少:800*1068,超过比例部分的宽高将会截掉。

清晰的封面图片是为了导出文档中的效果更好,如果只是为了在线显示的效果,满足 173*231 或者相同比例即可。

2 目录规范

目录结构规划

尽量首先对文档和书籍的目录结构做好统一规划,而不是想到一个添加一个。

目录的设计对于导出的电子文档格式会有一定的影响,通常对于书籍来说,一级目录是章,二级目录是节,内容多一些的书籍会把某些章节单独归类,例如:第一部分 / 第一章 / 1.0 小节内容这样的结构,在最终导出的PDF/WORD文档的页面,一级目录会自动换页显示,其他目录的内容是紧随上文内容后面显示,不会分页。

过多层次的目录会影响阅读体验,如非必要,建议最多采用三级目录

例如:
document/2015-09-22/560118d267db9

目录文件命名

看云的每个目录都对应了一个实际的文件,因此无论是在线还是离线写作,目录的文件名尽量避免使用特殊字符,尤其是:\/:*<>|"

事实上大多数情况下在线写作的时候系统会自动过滤,但离线写作的时候需要特别注意。

正确的:

cloud_design_pattern.md
cloud-design-pattern.md

错误的:

cloudpattern.md
cloud_design_pattern

实际上,目录文件命名的时候,为了方便离线写作的识别,我们更建议使用中文命名,例如:

正确的:

云计算设计模式-概述.md

错误的:

云计算设计模式|概述.md

3 内容规范

目录层次

如果你的内容是有层次关系的,建议尽量用 H2~H4 标识区分,并且便于自动提取当前页的目录,除非特别必要,谨慎使用 H1,从 H2 开始是由于默认的样式 H2 带有一个下划线样式,很容易区分。

document/2015-09-22/560117c8a31f0

对于H4以后的则不建议使用,可以考虑直接使用粗体替代。

不建议对H2~H4 再次使用粗体,例如:

document/2015-09-22/56011f0fa8143

相关的样式可以通过自定义样式来做一些调整,避免固化。

代码

代码部分确保使用代码标签,否则可能导致页面显示出错或者某些内容被过滤、混淆而导致预览和阅读出现问题,例如下面的示例中使用了单行代码和多行代码标签:

document/2015-09-22/56011960c1b59

对于很长的内容或者中文内容尽量少用单行代码标签,因为单行代码标签没有自动换行样式支持。

链接

内容中的URL地址会自动转换为超链接,无需使用链接标签,但是需要注意,链接URL地址前后必须加上空格,否则可能会有混淆。
正确的:

广场地址 http://www.kancloud.cn/explore

错误的:

广场地址(http://www.kancloud.cn/explore

目录导航

对于较长的内容,建议采用 H2~H4 将内容层次化,并在开头或者需要的位置添加目录导航标识 [TOC],效果如图:

document/2015-09-22/560123450b056

如果发现[TOC]标签无法正常解析,最好在前后添加一个空行。

其它

其他关于中文排版的规范可以参考这篇:中文文案排版指北

上一篇: 下一篇:
  页面正在加载中