# 使用技巧和注意事項 ## 注意事項 * 文件名最好不用中文（`good: 'help.md'` ; `bad: '使用手冊.md'`），即便這不是什么嚴重的問題。 * 文件編碼最好是 utf-8. * 明確清晰的文檔歸類（適當用文件夾進行區分）。 * 寫 `SUMMARY.md` 的時候使用統一的路徑格式： ```md * [前 言](./default.md) * [kc install](./useage/ins.md) ``` > 這只針對使用非看云編輯器編輯的情形，在看云的編輯器（在線編輯器器或者客戶端）上貌似不管你怎么寫可能都是這樣子的： ```md * [a](a.md) * [b](b.md) * [c](c.md) 然而你可能希望是這樣子的: * [a](a.md) * [b](a/b.md) * [c](a/b/c.md) ``` 說人話：看云不會創建文件夾！這也很正常，中文的文件夾會顯得很怪異，而且這也不是剛需，加上有 `SUMMARY.md` 的控制，若無潔癖可忽略。 ## 已知存在的問題及解決方法 #### 1. 生成 DOCX 文件發生的問題： 多個`.md`合成一個`.docx`時，如果有`.md`文件的末尾不是一個空白行，那么在它之后的`.md`的標題不會渲染成功————直接顯示原文：`# xxxx`， 解決方法是找到沒有正常轉換的`.md`文件的前一個`.md` 文件，打開它在末尾按回車（Enter鍵）新增一個空行，保存之后再重新生成一次。 **還有一個棘手的問題：代碼塊是無法正常轉換的，在docx中可能直接顯示原文，也有可能直接被渲染成代碼運行之后的結果（尤其是HTML、Markdown、XML這類的代碼片段）。目前還沒找到簡單粗暴的解決方法，如果你的文檔是API類型或者包含代碼塊的文檔最好不要轉換成DOCX文件。** #### 2. Markdown 轉其他文件的無奈 Markdown 有多種衍生標簽和語法，HTML的表現是豐富多樣的，我們無法折中，帶流程圖、數學表達式的內容可能轉換之后發生意想不到的錯漏。而轉換之后的HTML也不是你喜歡的。PDF 又需要做很多事情，從字體支持、渲染引擎......總之，HTML需要樣式模板，內容需要額外轉換，對這些去做兼容是不小的工程，往后的版本估計都不會去對這些進行優化。只能說讓專業的人去做專業的事，當發現“輪子”造不下去的時候要學會放棄。