# 朱码 JS 转换器文档
---
## 目录
1. [项目介绍](#1-项目介绍)
2. [文件结构](#2-文件结构)
3. [无 UI 模式](#3-无-UI-模式)
4. [UI 模式](#4-ui-模式)
6. [转换规则](#5-转换规则)
---
## 1. 项目介绍
[朱码](https://gitee.com/drewneon/drewmark) 是一款受 [Markdown](https://daringfireball.net/projects/markdown/) 和 [Showdown](https://github.com/showdownjs/showdown) 所启发的全功能型标记语言系统。
为了方便习惯使用 Markdown 的用户快速切换至*朱码*，也方便仍未开始使用任何标记语言的用户，特提供基于原生 JavaScript（Vanilla JS）开发的*朱码 JS 转换器*，支持*[朱码](https://gitee.com/drewneon/drewmark)*、[Markdown](https://daringfireball.net/projects/markdown/) 和 HTML 三种格式之间的多种相互转换。
支持的转换方向：
| 源格式 → 目标格式 | 支持状态 |
| ------------------- | ----------------------------- |
| Markdown → 朱码 | ✅ |
| HTML → 朱码 | ✅ |
| 朱码 → Markdown | ✅ |
| 朱码 → HTML | ❌ 请使用 *DrewMark JS 解析器* |
| Markdown → HTML | ❌ 请使用专门的 Markdown 解析器 |
| HTML → Markdown | ✅ |
提供两种使用模式：
- **无 UI 模式** —— 通过在函数中提供必要参数，直接返回转换结果字符串
- **UI 模式** —— 在指定 DOM 元素内渲染可交互的转换器界面，支持文件上传
---
## 2. 文件结构
```javascript
drewmark-js-converter/
├── js/
│ └── drewmark-converter.min.js 主程序
├── css/
│ └── drewmark-converter.min.css CSS样式
├── lang/
│ ├── en.json 英文 UI 字符串（供翻译其它语种使用）
│ └── zh-cn.json 中文 UI 字符串
├── docs/
│ ├── doc.md 英文文档
│ └── doc-cn.md 本文档
├── examples/
│ ├── sample.html 演示页（英文界面）
│ └── sample-cn.html 演示页（中文界面）
├── README.md
└── README-cn.md
```
---
## 3. 无 UI 模式
更适合工程化项目（Node.js + 构建工具），例如使用 Webpack、Vite、Rollup 等构建工具的项目。
### 3.1 使用方法
**1. 安装依赖**
```bash
npm install drewmark-converter
```
**2. 在源码中导入并使用**
在入口文件或组件中导入转换器及样式文件，并调用初始化函数：
```javascript
// 导入转换器
import { drewmarkConverter } from 'drewmark-converter';
const content = '# 标题\n这是一段**朱码**文本。';
const result = drewmarkConverter({
source_text: content,
source_format: 'drewmark',
target_format: 'markdown',
}); // 实际值为：'# 标题
这是一段**朱码**文本。'
// 将结果渲染到页面或进行后续处理
document.getElementById('output').innerHTML = html;
```
### 3.2 必要参数
无 UI 模式必须提供如下三个必要参数才能返回转换后的字符串。
| 参数名（缩写） | 含义 | 类型 | 接受值（缩写） |
| ----------------------- | ---------- | -------- | -------------------------------------------------------------- |
| `source_format`（`sf`） | 原始文本格式 | `string` | `'drewmark'`（`dm`）\| `'markdown'`（`md`）\| `'html'`（`htm`） |
| `target_format`（`tf`） | 转换目标格式 | `string` | `'drewmark'`（`dm`）\| `'markdown'`（`md`）\| `'html'`（`htm`） |
| `source_text`（`st`） | 原始文本内容 | `string` | 要转换的字符串 |
* 参数名和文本格式都可以使用缩写，例如以下几种写法的功能完全相同：
```javascript
drewmarkConverter({source_format: 'markdown', target_format: 'drewmark`, source_text: '# test'});
drewmarkConverter({source_format: 'md', target_format: 'dm`, source_text: '# test'});
drewmarkConverter({sf: 'markdown', tf: 'drewmark`, st: '# test'});
drewmarkConverter({sf: 'md', tf: 'dm`, st: '# test'});
```
* 特殊情况：如果原始文本格式为*朱码*或 Markdown，转换目标格式为 HTML，转换器不会返回解析结果，而会返回提示：请使用相应的 JS 解析器。
---
## 4. UI 模式
更适合纯 HTML 页面直接调用，无需 Node.js 环境，通过 `
```
+ 从 CDN 直接引用脚本（跳过下载步骤）：
```html
```
**3. 在指定容器元素中加载转换器**
```html
```
+ `converter_id` 参数名可缩写为 `cid`，例如上述示例中加载转换器 UI 界面的语句也可以写作：`drewmarkConverter({ cid: 'my-converter' });`。
+ *UI 模式*同样支持*无 UI 模式*的三个参数，并作为初始值加载到 UI 界面中。
### 4.2 界面展示
### 4.3 功能介绍
1. 选择原始文本格式的下拉菜单包含：`朱码(.dm)`、`Markdown(.md)` 和 `HTML(.html)` 三个选项。
2. 点击上传按钮可上传本地 `.dm`、`.md`、`.html`、`.htm` 后缀的文件，自动识别文件格式并读取内容填写到输入框中。
3. 原始文本输入框也支持手动填写内容。
4. 选择要转换的格式的下拉菜单同样包含：`朱码(.dm)`、`Markdown(.md)` 和 `HTML(.html)` 三个选项。当原始文本格式选择*朱码*或 Markdown 时，会自动选择唯一可转换的格式。
5. 转换按钮默认为禁用（灰色），当上述两个下拉菜单（1和4）有了具体选项且原始文本框（3）中有内容时被激活，点击即将转换结果输出到下面的输出框中。
6. 转换结果输出框仅供显示输出结果，不提供编辑修改功能，所以一直保持禁用状态。
7. 复制按钮默认为禁用（灰色），当结果输出框中有内容时激活，点击即可将转换结果复制到剪贴板。
8. 下载按钮默认为禁用（灰色），当结果输出框中有内容时激活，点击即可将转换结果下载到本地，其格式和扩展名由选择的转换格式决定。
---
### 4.4 多语言支持
*朱码 JS 转换器*在加载时会读取 `` 标签的 `lang` 属性值或者浏览器自带的 `navigator.language`，并默认在与 `js` 平级的 `lang` 目录中寻找以此语言为文件名的 `.json` 文件。如果该语言文件存在且包含界面所需的语言条目，则使用该语言加载转换器的界面；如果找不到对应文件名的文件或者该文件内容不符合要求，则使用内置的英文版本加载转换器的界面。本项目的 `lang` 目录中提供了简体中文的语言文件（`zh-cn.json`）以及供翻译用的英文原文（`en.json`）。
如果想对上述多语言的默认状态加以调整，可以使用 `drewmarkConverterLang()` 函数：
**方法一**
1. 使用此函数的 `