迁移过程
1. 把所有 DITA 文件放到同一个目录
可以自己写一个 python 脚本。有时间写了放到这里。
2. DITA 转换成 Markdown 格式
Convert your .dita files in Oxygen. You can convert individually or in bulk using a flat ditamap. To transform in Oxygen: Configure Transformation Scenarios>New>Dita-OT Transformation>Markdown.
3. HTML 文件转换成 Markdown 文件
先用 Oxygen 把 DITA 文件转换成 HTML, 再用 Pandoc （https://pandoc.org/MANUAL.html） 把 HTML 转换成 Markdown 文件。
a. Download pandoc-1.19.1-windows.msi from GitHub (jgm/pandoc) and run it to install.
b. Check that everything works okay:
C:\>pandoc --version
pandoc 1.19.1
Pandoc is a command-line tool. Refer to https://pandoc.org/MANUAL.html for all possible parameters, but this is typical for simple transforms:
C:\testtopics>pandoc test1.html -f html -t markdown -o test1.md
4. DITAMAP 转换成 SUMMARY. md
5. Conref.dita 转换成 conref.md
参考 《Markdown 吐血整理经验大全》里的 conref 部分（https://www.jianshu.com/p/6e12c9500f51）
6. 在 GitHub 上创建 master branch.
参考 《GitHub，Markdown 的好搭档》(https://www.jianshu.com/p/d5f77b3830b8)
7. 将转换后的文件放到 GitHub 本地目录。
如：C:\Users\xxx\Documents\GitHub\xxx-docs.
转换后 clean-up
用工具转换后还是有很多问题，需要人工校对每个文档，检查问题。
1. Conref 替换问题。
转换成 .md 文件后，conref 全变成 <span class="keyword">term_context</span> 的格式，需要手工改成 {{site.data.keyword.term_keyword}} 的格式。
a. Find the label term_keyword and take it as an example.
term_keyword:
keyword_context
b. Input the conref text for your agent in any text editor, for example, {{site.data.keyword.term_keyword}}. It is for future copy/paste use.
c. Open Notepad++ or Visual Studio Code.
d. In Notepad++, click Search -> Find in Files ( In Visual Studio Code, it is Edit-> Replace in files).
e. In the Find what field, input the original conref text from converted dita topics. For keyword_context, it is <span class="keyword">keyword_context</span>. In the Replace with field, input the correct conref text that you created in step 2, for example, {{site.data.keyword.term_keyword}}.
f. In the Directory field, navigate to the directory where you store your .md files, for example,
C:\Users\xxx\Documents\GitHub\product-docs.
g. Click Replace in Files. Then all occurences of the <span class="keyword">term_context</span> will be replaced with the correct conref text {{site.data.keyword.term_keyword}}.
2. 检查文档确保符合规范。
- Varname changes to italic.
- UI Control and Param name change to bold.
- Script names should be in monospace and bold, for example, pre_install.sh.
- File names and paths/directorys should be in monospace.
- codeph in dita should be in codeblock.
For example:
```
```
{: codeblock}
- Section in dita does not work in md, we need to add ** xx** to make it bold.
- Check the procedure steps are displayed well. Remove redundant space because it will cause the steps to be displayed as a codeblock text or make the step number in a mess.
- Check the links, especially the index links within the page. Usually the parent/child topic links work correctly, but if you have index links in the page that link to corresponding sections within the same page, the anchor is probably corrupted, so you need to re-create the anchor links in .md file.
LIMITATION: you can only link to another page NOT another section in another page.
- Adding registered trademark symbols: So in Oxygen, we had our lovely Trademarks tool, which you ran and it magically added our registered trademarks to the required company/product names in our topics. In MD, a little different, so basically for any company/product name that you need to include a registered trademark symbol for, you simply add ® directly after the product or company name.
3. 检查文档确保文档一致性。
参考：
《Markdown 吐血整理经验大全》中 Markdown 标签部分（https://www.jianshu.com/p/6e12c9500f51）
《你知道什么时候使用粗体、斜体、monospace 吗？》（https://www.jianshu.com/p/10ba5c55c86a）
d. 确保 PII compliance、accessibility 和 易于 translation
《文档质量之规范写作》（https://www.jianshu.com/p/dd44ab8f9bf4）
《技术文档写作常用工具大全》（https://www.jianshu.com/p/06696de014af）
