Markdown is the lightweight markup behind READMEs, documentation, notes and many blogs: # starts a heading, - starts a list item and backticks mark code. Static site generators often add front matter at the top of the file for the title, date and other details. Converting such a file as plain text would also change variable names in code and Chinese paths in links, which breaks code samples and links. This page reads the Markdown structure first and converts only the parts people read.
What is converted
- Body text, headings, lists, tables and block quotes.
- Link text and image alt text.
- Front matter values.
- Links to headings on the same page, which change together with the headings.
- Text attributes such as title and alt in embedded HTML tags.
What stays the same
- Fenced code blocks, indented code blocks and inline code. Comments in code blocks can be converted if you choose; by default they are not.
- Link and image addresses, including Chinese paths. In the examples below, the link text 使用文档 becomes 使用文檔 while the path
docs/使用文档.mdstays as it is. - Front matter keys and the HTML tags themselves.
Encoding and editor support
Markdown editors and static site generators usually read files as UTF-8. Older docs saved as GBK or Big5 are detected and converted to UTF-8. Line endings are kept and the BOM follows the original file, so when the original is UTF-8, a Git diff of the converted file shows changes only in the converted text.
Conversion examples
| Original | Result |
|---|---|
| ## 安装说明 | ## 安裝說明 |
| 请先阅读[使用文档](docs/使用文档.md)。 | 請先閱讀[使用文檔](docs/使用文档.md)。 |
| 运行 `npm install 软件包` 安装依赖。 | 運行 `npm install 软件包` 安裝依賴。 |
|  |  |
| | 名称 | 说明 | | | 名稱 | 說明 | |
| - **注意**:后台程序会自动更新。 | - **注意**:後臺程序會自動更新。 |
Real output from OpenCC (s2t).
How to use
- Drop .md or .markdown files onto the page, or click Choose files. All the files of a docs folder can be selected at once.
- Choose the direction and standard. For docs aimed at readers in Taiwan, choose Taiwan and keep Convert regional terms on.
- If needed, open Advanced options by format and decide whether comments in code blocks should be converted.
- Check the preview and download, or click Download all (ZIP) for several files.
Things to check
- With Convert regional terms on, technical words change too. Under the Taiwan standard 程序 (program) becomes 程式 and 文件 (file) becomes 檔案, even where 文件 means a document, so read technical docs through after converting.
- One-to-many characters are not highlighted in files. Paste passages you are unsure of into the Text tab to see the characters that need review.
- Link targets are kept exactly, for example docs/使用文档.md. For docs that link to each other, choose Keep name under File name, or the renamed files will no longer match the links.
FAQ
Is Chinese inside code blocks converted?
No. Fenced code blocks, indented code blocks and inline code stay as they are, so variable names and strings are safe. Comments in code blocks are left alone by default too; to convert them, turn on “Markdown: also convert comments in code blocks” under Advanced options by format.
Do table-of-contents links still work?
Yes. Links to headings on the same page are converted along with the headings, so [安装](#安装) becomes [安裝](#安裝) and still points to the converted heading.
What happens to front matter?
The keys stay the same and only the values are converted, such as the title and summary. Values that are paths or URLs are kept as they are.
How are HTML tags inside Markdown handled?
The tags stay as they are, while text attributes in them, such as title and alt, are converted.
Is this the same as localising my docs?
Not quite. It converts the script and, with Convert regional terms on, the vocabulary in OpenCC's dictionary. Phrasing, examples and screenshots still need someone who knows the readers you are writing for.