2020 年第一季度默勾，產(chǎn)品從 DITA 遷移到 Markdown牢酵，這讓我有幸在半年內(nèi)熟悉了 DITA 和 Markdown 兩種不同的寫作方式秸弛，也熟悉了遷移過程的各個方面医咨，總結(jié)了一些經(jīng)驗教訓(xùn)。產(chǎn)品第一季度 release 后灰追，時間相對寬裕堵幽，我想記錄下整個遷移過程中自己的所學(xué)所思，以后說不定會有用處弹澎。這篇文章我就單說 Markdown, 其它方面諸如 GitHub谐檀，我會在另一篇文章里詳述。
Markdown Tips
1. Header organization has to be consecutive (H1 > H2 > H3), if you accidentally go from H1 # to H3 #, your code will be off.
2. If content, like a list, should be indented and be a subset of the preceding content, include the subset content on a new line and indent it by two spaces or one tab.
3. Use git pull often to minimize conflicts when you merge and to ensure that you have the latest content that someone else merged.
4. Use the Visual Studio Code preview to see your output. Also use the browser preview as a guide…not always 100% accurate, but usually a good way to see your errors.
5. After you prompt the user to run a command, be sure to start the codeblock in the a new line; press the space bar three times to help with the alignment of the codeblock.
6. Use anchors for long topics. Since we are getting away from rigid concepts, task, and references, you can have different kinds of content all in one topic. Sometimes the topics get long. Anchors are built much like links.
7. Use the back tick character for surrounding coding text. You can’t use an apostrophe (‘). Use ```? in a row to begin a codeblock and end it with another ```
Markdown limitations
1. As previously mentioned, to add a list to a table cell, create your .md table, then use HTML within a cell to create your list. This should be the only time you need to use HTML within a.md file.
2. Version control can be an issue since you do not have .ditavals. The simpler you keep the versioning, the better.
3. You need to know the Style Guide and stay on top of changes. Standardization is not as easy as it is in DITA. For instance, IBM DITA writers know exactly when to use ui-control (click something is bold), and when to use wintitle (window or page is italicized). This is because the DITA tag alone takes care of the text meaning for us. Work as a team to follow the style guide and use bold, italics, lists, etc.
Markdown 標簽
剛開始不喜歡 Markdown, 覺得什么都要自己敲裁奇，沒有 DITA 標簽用的方便。對 Markdown 的用法熟記于心后麦撵，覺得敲就敲吧刽肠，也不費太多時間。但隨之而來的產(chǎn)品文檔格式不一致問題免胃，更讓人頭疼音五。每個 information developer 都用自己的方式來完成一篇文章，看起來也遵循了格式規(guī)范羔沙，可是整個文檔系統(tǒng)非常雜亂無章躺涝。舉幾個例子：
1. 代碼塊里的變量名，有人用 <install_dir>, 有人用 Install_dir扼雏。
2. 用戶需要注意的點坚嗜，有人用 **Note** 來加粗表示, 有人就用普通的 Note夯膀。
3. 有人用 html 格式的表格，有人用 Markdown 格式的表格苍蔬。
在 產(chǎn)品 800 個 DITA 文檔用 Pandoc 轉(zhuǎn)換成 Markdown 格式后诱建，文檔里有大量的格式錯誤，也充斥著大量 html 標簽碟绑，我們花了一段時間修改自己 own 的 文檔俺猿，卻沒有提前就格式統(tǒng)一問題定好規(guī)則。這個問題導(dǎo)致后來又進行了新一輪的修改格仲，費時費力押袍。
以下是目前產(chǎn)品統(tǒng)一采用的規(guī)范：
1. 去掉所有不必要的 html 標簽，比如 <table>, <span>, <img> <a href>.?? 全部使用 Markdown 格式凯肋。
例外：
- 允許使用 <br> 表示換行谊惭。
- Markdown 格式的 table 不支持 list. 盡量在 table 里不用 list。但必須用的情況下可以用 <ul> 和 <ol>否过。
2. 使用 #午笛，## ，### 表示 headings苗桂， 而不用---药磺。Use hash sign instead of dashes for headings.
示例：
# Heading 1
## Heading 2
3. 簡化表格，去掉合并單元格煤伟，因為 Markdown 表格不支持癌佩。
4. 使用 space 表示空格。
5. Use? <variable> in command and underneath use italic to describe variable.
示例：
Run the following command:
?<install_dir>/bin/ececute.sh config <instance_name>
?Where *install_dir*? is the path where the agent is installed and *instance_name* is the name that you want to give to the agent instance.
需要注意的是：
如果你把<variable_name>放到 ``` 和 ``` 之間的 codeblock 里便锨，或者 ` `之間用
monospace 表示围辙，<variable_name> 能夠正確顯示。但如果你把<variable_name>放到
** 和 ** 之間來加粗顯示放案，或者放到 * 和 * 之間來斜體顯示, markdown preview 顯示正常姚建，發(fā)布后就慘了，<variable_name>消失了你都不知道吱殉，因為命令的其他部分仍然可以顯示掸冤。用戶運行這個命令失敗，影響很大友雳。
解決辦法是用 <表示 <, 用 > 表示 >
6. 使用鍵盤上的 tab 鍵表示 tab稿湿。
7. 盡量去掉文檔中的截圖，因為產(chǎn)品更新太快押赊，截圖很有可能過時饺藤。
8. 使用 Acrolinx 檢查所有文檔，確保沒有 grammer、wording涕俗、trademark 等錯誤罗丰。
9. 統(tǒng)一 Tips, Important, Notes 格式。
- If there is only one sentence for the note/tip/important, use **note** and put the text right after it in one paragraph/line. It will NOT cause accessibility violation or potential violation. For example:
**Important1:**? All on same line, with no Enter. text text text text text text text text text text text text text text.
- If there are any lists under the note/tip/important, then it has to be in multiple lines. So use something like ### note, and then followed by the lists of text. But if there are more than 1 such header note,? make sure the id is unique, for example, for note 1, we can say something like ### things to note:, for note 2, we can say something like ### note, to avoid duplicate ids.
10. 所有文檔發(fā)布前統(tǒng)一用 Acrolinux 檢查語法咽袜、拼寫丸卷、標點、trademark询刹、用法等錯誤并修改谜嫉。
11. 使用 Markdown Attributes.
{:shortdesc:?.shortdesc}
Shortdesc renders as a special class in the HTML for the 1st paragraph.
Yes, one of its main roles involves retrievability. It also has some
functional roles within KC, such as the sentence that appears with links
within search results, child\nested topics, etc.?
{:screen:?.screen}
比如在 linux command line 敲了很多命令，返回了一些結(jié)果凹联，可以 copy 命令和結(jié)果到 文檔中沐兰，用以下方式表示：
```
linux command and result
```
{:screen}
{:codeblock:?.codeblock}
Markdown 的 codeblock 不帶自動復(fù)制功能，使用 {:codeblock} 可以使代碼塊能一鍵復(fù)制蔽挠。
示例：
```
code
```
{:codeblock}
{:child:?.link?.ulchildlink}
{:childlinks:?.ullinks}
用來在超級主題中表示子主題住闯。
示例：
-?{:?child}?[Installing xxx](config_xxx_install.md)
-?{:?child}?[Creating?a xxx test](config_xxx_restapi.md)
{:?childlinks}
Markdown 表格
Markdown 表格雖然方便，熟悉了寫起來也快澳淑，但坑也多比原。這里我記錄幾個坑以及如何趟過去。
1. Markdown 用 | 符號來分割每個單元格杠巡。比如：
| Tables | Are | Cool |
| ----------|-----| ------|
| col 3 is | right-aligned | $1600 |
有時候單元格內(nèi)容本身包含 |量窘。比如單元格內(nèi)容是：運行 kubectl get pods | grep ***。如就這么輸入氢拥，肯定會導(dǎo)致表格顯示出錯蚌铜。用 \| 的方式來表示 |，在 markdown preview 表格顯示無誤嫩海，但在實際發(fā)布后的文檔后表格顯示仍然有問題冬殃。正確的方式是用 | 的轉(zhuǎn)義字符 ¦
2. 如果表格的最后一個單元格是空的，markdown preview 沒問題叁怪，發(fā)布后會發(fā)現(xiàn)表格最后一個單元格消失了审葬。解決辦法是在最后一個空單元格加空格的轉(zhuǎn)義字符  
3. 實在需要在表格里加列表，就用 <ul> 或 <ol>奕谭。
|Tasks|References|
|-----|----------|
|View?applications?across?clusters?on?one?console.?|<ul><li>[Managing clusters on one console](managing_cluster_console.md)</li></ul>|
4. 表格后要添加標題耳璧。
示例：
{: caption="Table 1. Helm chart configuration parameters caption-side="top"}?
5. 最坑的是，但凡 Markdown 表格前有縮進展箱，整個表格即使在 markdown preview 能正常顯示，發(fā)布后一團亂蹬昌。做了很多試驗和交流后混驰，發(fā)現(xiàn) Markdown 表格前不能縮進。
舉個例子：
表格在某個步驟后：
3. Enter xxxx.
| Tables | Are | Cool |
| ----------|-----| ------|
按照 Markdown 的規(guī)矩，這個表格需要縮進栖榨，才能正確顯示在步驟 3 下面昆汹。一縮進，表格一團亂婴栽。不縮進满粗， 步驟4 顯示成步驟 1 了，表格沒有顯示在步驟3 下面的正確位置愚争。
解決辦法是不要在步驟 3 下面放這個表格映皆，直接放到文章最后，設(shè)置個錨點轰枝，直接 For more information, see [Table 1](#table1) 吧捅彻。這樣就不會有顯示問題了。
Markdown TOC (Content Of Table)
Markdown TOC 非常敏感鞍陨，但凡有一點小錯誤步淹，TOC 不會正常顯示。常見錯誤就是格式錯誤. 剛開始有問題大家就一行行的查诚撵，最近找到了個 XML 檢查工具 （https://onlinexmltools.com/validate-xml）缭裆，能自動查出問題。
Markdown 文件復(fù)制問題
云產(chǎn)品文檔里使用 YAML 文件比較多寿烟，Javascript 代碼塊也不少澈驼。從 DITA 自動轉(zhuǎn)換成 Markdown 格式后，文件格式會比較亂韧衣。 YAML 對格式要求又很高盅藻，多一個空格都會出錯〕┟可以用自動檢查工具代替肉眼檢查氏淑。Javascript 代碼塊最好是格式化后再寫入 codeblock 里。
YAML checker: https://onlineyamltools.com/validate-yaml
Javascript 格式化工具: https://tool.oschina.net/codeformat/js/
Markdown conref 文件
如何自動從 DITA conref 格式（xml）轉(zhuǎn)化成 markdown conref 格式呢硕噩？ 我寫了一個 python 腳本假残，可以自動轉(zhuǎn)化 xml 格式的 conref 到 markdown conref.
注意：
1. For conref.yml file, every space is meaningful.??Even if there is only one space error, the whole conref.yml file couldn’t be used.?Conref items couldn’t be showed well in documents.?Please ensure all the items are strictly right in format.
2. You can only use one conref.md file. It’s not possible to conref content from one file? to another.
3. You cannot use conrefs in your toc.xml file.? This file is not run through the build in the same way that the other files are. It is assumed by the build that it has already been through the process to resolve the conrefs.? Spell out the conrefs in this file only.
conrefs2.xml 如下：
<?xml version="1.0" encoding="utf-8" ?>
<!-- This is list of customers -->
<keywords>
? ? <keyword id="term_dc_cloudresource1">Kubernetes dc</keyword>
? ? <keyword id="term_dcs_cloud">Kubernetes dc</keyword>? ?
</keywords>
Python 腳本如下：
#coding=utf-8
import? xml.dom.minidom
dom = xml.dom.minidom.parse('C:\\Temp\\conrefs2.xml')
root = dom.documentElement
keywords = root.getElementsByTagName("keyword")
filename = "C:\\Temp\\keyword.txt"
for keyword in keywords:
? ? print(keyword.getAttribute("id"))
? ? try:
? ? ? ? tm = keyword.getElementsByTagName("tm")[0]
? ? ? ? if tm != 'null':
? ? ? ? ? ? str=keyword.toxml()
? ? ? ? ? ? print(str)
? ? ? ? ? ? with open(filename, 'a') as file_object:
? ? ? ? ? ? ? ? file_object.write(keyword.getAttribute("id"))
? ? ? ? ? ? ? ? file_object.write(":\n? ")
? ? ? ? ? ? ? ? file_object.write(str.replace(tm.toxml(),tm.childNodes[0].data))
? ? ? ? ? ? ? ? file_object.write("\n")
? ? ? ? ? ? ? ? print(str)
? ? except BaseException:
? ? ? ? print(keyword.childNodes[0].data)
? ? ? ? with open(filename, 'a') as file_object:
? ? ? ? ? ? file_object.write(keyword.getAttribute("id"))
? ? ? ? ? ? file_object.write(":\n? ")
? ? ? ? ? ? file_object.write(keyword.childNodes[0].data)
? ? ? ? ? ? file_object.write("\n")
腳本運行結(jié)果：
自動生成 Markdown conref 到 keyword.txt 文件里。
示例：
cf:
? ? Cloud Foundry
? cf-deploy-tool:
? ? Cloud Foundry deployment tool
? cfee:
? ? Cloud Foundry Enterprise Environment
如何使用 Markdown conref 文件里的 keyword：
{{site.data.keyword.xxx}}
示例：
It interates with {{site.data.keyword.cf}}
keyword 好處：
一次修改炉擅，到處使用辉懒。比如產(chǎn)品名變了，不用改動所有用到產(chǎn)品名的文檔谍失，只需要改動 conref 文件里的產(chǎn)品名對應(yīng)的 keyword眶俩。
