本篇內容旨在幫助大家更規范的在看云完成寫作，并且同時給用戶帶來良好的閱讀體驗。 >[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.hmoore.net/explore` 錯誤的： >[danger] `廣場地址（http://www.hmoore.net/explore）` ### 章節導航 對于較長的內容，建議采用 H2~H4 將內容層次化，并在開頭或者需要的位置添加目錄導航標識`[TOC]`，效果如圖：  >[info] 如果發現`[TOC]`標簽無法正常解析，最好在前后添加一個空行。 ### 其它 其他關于中文排版的規范可以參考這篇：[中文文案排版指北](http://www.hmoore.net/thinkphp/chinese-copywriting-guidelines/)。