# 使用技巧和注意事项 ## 注意事项 * 文件名最好不用中文（`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需要样式模板，内容需要额外转换，对这些去做兼容是不小的工程，往后的版本估计都不会去对这些进行优化。只能说让专业的人去做专业的事，当发现“轮子”造不下去的时候要学会放弃。