# HarmonyMarkdown

**Repository Path**: peng-qiu/harmony-markdown

## Basic Information

- **Project Name**: HarmonyMarkdown
- **Description**: 鸿蒙版本的markdown预览工具
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-20
- **Last Updated**: 2026-08-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 鸿阅 Markdown（HarmonyMarkdown）

面向 **HarmonyOS NEXT / HarmonyOS 6.0 平板** 的 Typora 级 Markdown 阅读器。纯鸿蒙原生应用（ArkTS + ArkUI + ArkWeb），不依赖安卓运行时。

## 功能

- 打开平板本地 `.md` / `.markdown` / `.mdown` 文件
- 支持“打开文件夹”：从文件夹中选择文档，**相对路径图片/资源可正常解析**
- 渲染内核：`markdown-it` + CommonMark / GFM 扩展
  - 表格、任务列表、删除线、自动链接
  - 脚注、Emoji、上下标、高亮标记、自定义属性
  - `[TOC]` 文内目录
  - LaTeX 数学公式（KaTeX，离线字体）
  - Mermaid 流程图（离线运行）
  - 代码高亮（highlight.js，160+ 语言）
- 标题大纲侧栏：树形层级、支持展开/折叠，点击跳转
- 侧栏非固定常驻：横竖屏均为抽屉式，点 ☰ 展开、点遮罩或 ✕ 收起
- **相对路径跳转**：一个文件夹内的多个 .md 可通过 `[链接](./other.md)` 互相跳转，支持锚点，并提供返回按钮
- 最近打开记录（持久化文件授权）
- 深色/浅色主题、字号调节、源码/预览切换
- 平板横屏、手机竖屏自适应
- **导出自包含 HTML**：数学字体、代码样式、Mermaid、图片全部内联，单文件可直接在电脑浏览器打开
- 支持从系统“分享/打开方式”接收 .md 文件
- 内置 Wiki 相对跳转示例：`docs/wiki-demo/home.md`

## 目录结构

```
HarmonyMarkdown/
├── AppScope/                 # 应用级配置与图标
├── entry/src/main/
│   ├── ets/                  # ArkTS 源码
│   │   ├── entryability/     # Ability（含接收分享文件）
│   │   ├── pages/Index.ets   # 主界面
│   │   ├── service/          # 文件、导出、设置
│   │   ├── webview/          # ArkWeb JS 桥
│   │   └── model/            # 数据模型
│   └── resources/rawfile/
│       ├── renderer/         # 离线渲染器（HTML/CSS/JS/KaTeX/Mermaid）
│       └── export/           # 导出专用内联 CSS
├── tools/                    # 渲染器构建工具（npm）
└── sample.md                 # 测试文档
```

## 最快看效果（不用装任何东西）

用电脑浏览器直接打开：

```
tools/browser-preview.html
```

它加载的就是 App 内同一套渲染内核（markdown-it、KaTeX、Mermaid、highlight.js、同一份 CSS），内置了一篇覆盖全部特性的示例；也可以点“打开本地 .md”加载你自己的文件。浏览器里看到的效果，就是平板上将要看到的效果。

> 注意：浏览器预览主要用于“看渲染效果”。平板 App 额外提供了文件授权、最近记录、目录跳转、单文件 HTML 导出等系统能力。

## 开发工具（不入库）

DevEco Studio 安装包约 2.9GB，**不放入 Git 仓库**。请从华为官方页面下载：

- 下载页：https://developer.huawei.com/consumer/cn/deveco-studio/
- 本工程已在 DevEco Studio 6.1.1（HarmonyOS 6.1.1 / API 24）上验证编译通过
- 家里新电脑装好 DevEco Studio 后，直接克隆本仓库并打开工程即可

## 构建与安装

### 1. 准备环境

- 电脑安装 [DevEco Studio 6.1.1 或更高版本](https://developer.huawei.com/consumer/cn/deveco-studio/)
- 平板进入 **设置 → 关于平板电脑**，连点版本号 7 次开启开发者模式
- **设置 → 系统和更新 → 开发人员选项**：打开 **USB 调试**
- 平板用数据线连接电脑，授权调试

### 2. 打开工程

用 DevEco Studio 打开本目录（`HarmonyMarkdown`）。首次打开会同步 hvigor 与 SDK。

> 如果你的 DevEco Studio 还是 5.x，把根目录 `build-profile.json5` 中
> `"compileSdkVersion"` / `"targetSdkVersion"` 改成你本机已安装的 SDK 版本
> （例如 `"5.0.5(17)"`）即可；`compatibleSdkVersion` 保持 `"5.0.0(12)"`。

### 3. 签名

个人开发直接用 **自动签名**：
- 在 DevEco Studio 中点击 **File → Project Structure → Signing Configs**
- 勾选 **Automatically generate signature**
- 登录华为账号即可生成调试证书

### 4. 运行

顶部设备列表选择平板，点击 **Run ▶**。应用会安装到平板。

> 自动签名有效期通常为 1 年；过期后重新生成签名并安装即可。
> 如果要长期稳定使用，可在 [AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)
> 创建应用、申请发布证书并上架或做企业内部分发。

## 重新构建渲染内核

渲染器 JS/CSS 已经打进工程，通常不需要重建。修改 `tools/renderer-src/app.js` 后：

```bash
cd tools
npm install
npm run build
```

构建脚本会自动刷新 `entry/src/main/resources/rawfile/renderer` 下的 JS、KaTeX、Mermaid、高亮主题，并重新生成导出用 CSS。

## 使用建议

1. **文件夹里有图片**：请点顶部“文件夹”授权并选择文档所在文件夹，再选择 .md 文件，相对路径图片才能稳定显示。
2. 单个文件选择器在部分设备上只授予“该文件”的临时权限，因此直接打开时同目录图片可能无法读取（会显示图片缺失占位）。这是系统安全机制，不是解析错误。
3. 导出 HTML 时，所有可解析的本地图片会转为 base64 内联；无法解析的图片会保留原路径提示。

## 第三方开源组件

| 组件 | 用途 |
|---|---|
| markdown-it 及官方插件 | Markdown 解析 |
| KaTeX | 数学公式 |
| Mermaid | 流程图 |
| highlight.js | 代码高亮 |
| esbuild-wasm | 构建渲染器 |

本项目源码以 Apache-2.0 协议发布；上述组件版权归各自作者所有。

## 关于“完美解析”

没有任何 Markdown 解析器能 100% 覆盖所有方言（CommonMark、GFM、Obsidian、Typora 各有差异）。本项目以 **GFM + Typora 常用语法** 为基准，覆盖绝大多数日常文档。遇到不支持的方言可在 `tools/renderer-src/app.js` 中增加插件后重建。