项目概述

MarkCraft 是一款专为 Android 平台设计的纯离线 Markdown 编辑器。应用无任何网络权限，所有数据本地存储，专注于提供安全、高效的 Markdown 编辑体验。

核心定位

• 纯离线应用: 无网络权限，数据完全本地存储，保护隐私
• 专业级编辑: 支持完整标准 Markdown 语法 + 扩展语法
• Material Design 3: 现代美观的界面设计，支持深色/浅色主题
• 实用功能: 编辑/预览/分屏三模式、图片导出、文档管理

技术栈

层级	技术
开发语言	Kotlin 1.9.22
UI 框架	Jetpack Compose (BOM 2024.02.00)
架构模式	MVVM + Clean Architecture
依赖注入	Hilt 2.50
本地存储	Room 2.6.1 + DataStore 1.0.0
Markdown 渲染	Markwon 4.6.2
构建工具	Gradle 8.5

---

项目结构

markdown/
├── app/src/main/java/com/markdown/app/
│   ├── data/                    # 数据层
│   │   ├── local/               # Room 数据库、DataStore
│   │   ├── model/               # 数据模型（Document、Settings等）
│   │   └── repository/          # 数据仓库
│   ├── di/                      # Hilt 依赖注入模块
│   ├── navigation/              # 导航配置（Navigation Compose）
│   ├── ui/                      # UI 层（Jetpack Compose）
│   │   ├── documents/           # 文档列表页面
│   │   ├── editor/              # 编辑器页面（核心功能）
│   │   ├── settings/            # 设置页面
│   │   └── theme/               # 主题配置
│   ├── util/                    # 工具类
│   │   ├── MarkdownHelper.kt    # Markdown 语法辅助
│   │   ├── MarkdownRenderer.kt  # Markdown 渲染器
│   │   └── ImageExporter.kt     # 图片导出工具
│   ├── viewmodel/               # ViewModel 层
│   ├── MainActivity.kt          # 主 Activity
│   └── MarkdownApplication.kt   # Application 类
│
├── app/src/main/res/            # 资源文件
├── build.gradle.kts             # 根构建脚本
├── app/build.gradle.kts         # 应用模块构建脚本
├── settings.gradle.kts          # Gradle 设置
└── gradle.properties            # Gradle 属性

---

构建指南

环境要求

• JDK: 17+
• Android SDK: API 34
• Android Studio: Hedgehog (2023.1.1) 或更高版本
• Gradle: 8.5（通过 wrapper 自动安装）

构建命令

# Windows 命令行构建
.\gradlew.bat assembleDebug

# 安装到设备
.\gradlew.bat installDebug

镜像配置

项目已配置阿里云镜像加速依赖下载：

• https://maven.aliyun.com/repository/google
• https://maven.aliyun.com/repository/public

---

核心功能

已实现功能 ✅

模块	功能	状态
架构	MVVM + Hilt 依赖注入	✅
文档管理	新建、保存、删除、重命名、列表展示	✅
编辑模式	纯编辑、纯预览、分屏（编辑+预览）三模式	✅
语法支持	标准 Markdown + 表格、任务列表、代码高亮	✅
快捷工具栏	H1-H6、粗体、斜体、代码块、列表、表格等	✅
主题	深色/浅色/跟随系统三种模式	✅
图片导出	导出为 PNG，支持自定义宽度、背景色、边距	✅
设置	字体大小、行间距、主题偏好	✅
外部文件	支持打开系统分享的 .md 文件	✅

待完善功能 🚧

功能	优先级	说明
撤销/重做	P0	编辑器历史记录管理
查找替换	P0	文本搜索和替换功能
嵌套列表缩进	P0	Tab 增删缩进
数学公式完整渲染	P1	LaTeX 公式（部分支持）
Emoji 选择器	P1	表情符号快捷插入
Mermaid 流程图	P2	图表渲染支持

---

Markdown 语法支持

基础语法（全部支持）

• 六级标题 (H1-H6)
• 粗体 **text**、斜体 *text*、删除线 ~~text~~
• 无序列表 - 、有序列表 1. 、任务列表 - [x]
• 引用块 >、代码块 ```
• 链接 [text](url)、图片 ![alt](url)
• 表格（支持左/中/右对齐）
• 水平分隔线 ---

扩展语法（已支持）

• HTML 标签：<u>下划线</u>、<sup>上标</sup>、<sub>下标</sub>、<kbd>键盘</kbd>、<mark>高亮</mark>
• 脚注 [^1]
• 数学公式（行内 $...$、块级 $$...$$）- 需要进一步完善

语法实现细节

参考文件：markdown语法实现计划.md、语法展示.md

---

开发规范

代码规范

• 使用 Kotlin 进行开发
• 遵循 Kotlin Coding Conventions
• 采用 MVVM 架构，数据流使用 StateFlow
• Composable 函数使用大驼峰命名
• ViewModel 使用 Hilt 注入

架构分层

UI Layer (Composable) -> ViewModel -> Repository -> Data Source (Room/DataStore)

文件命名规范

类型	命名规则	示例
Activity/Fragment	XxxActivity/XxxScreen	EditorScreen.kt
ViewModel	XxxViewModel	EditorViewModel.kt
Repository	XxxRepository	DocumentRepository.kt
Model	Xxx/XxxEntity	Document.kt
Util	XxxHelper/XxxUtil	MarkdownHelper.kt

---

关键依赖说明

// Jetpack Compose - UI 框架
implementation(platform("androidx.compose:compose-bom:2024.02.00"))

// Navigation - 页面导航
implementation("androidx.navigation:navigation-compose:2.7.6")

// Room - 本地数据库
implementation("androidx.room:room-runtime:2.6.1")
implementation("androidx.room:room-ktx:2.6.1")
ksp("androidx.room:room-compiler:2.6.1")

// Hilt - 依赖注入
implementation("com.google.dagger:hilt-android:2.50")
ksp("com.google.dagger:hilt-compiler:2.50")

// Markwon - Markdown 渲染
implementation("io.noties.markwon:core:4.6.2")
implementation("io.noties.markwon:ext-tables:4.6.2")      // 表格
implementation("io.noties.markwon:ext-tasklist:4.6.2")    // 任务列表
implementation("io.noties.markwon:syntax-highlight:4.6.2") // 代码高亮
implementation("io.noties.markwon:ext-latex:4.6.2")       // LaTeX 数学公式

// DataStore - 偏好设置
implementation("androidx.datastore:datastore-preferences:1.0.0")

---

重要文件说明

文件	用途
README.md	项目主文档，包含完整功能介绍和使用说明
Markdown_app.md	详细需求规格说明书
BUILD_GUIDE.md	构建指南和环境配置说明
task_plan.md	开发任务计划和进度追踪
progress.md	开发进度日志
findings.md	技术调研和架构决策记录
markdown语法实现计划.md	Markdown 语法功能实现规划
语法展示.md	Markdown 语法完整示例文档

---

常见问题

Q: Gradle 同步失败

A: 检查网络连接，确保能访问阿里云镜像和 Google/MavenCentral 仓库。

Q: 编译错误：找不到 Hilt 生成的类

A: 执行 Build -> Clean Project 然后 Build -> Rebuild Project。

Q: 深色模式预览字体颜色异常

A: 已在 MarkdownRenderer.render() 中根据 isDarkMode 设置文字颜色。

---

开发路线图

阶段 1: 基础框架 ✅

• 项目初始化、MVVM 架构
• Room 数据库配置
• 基础 UI 主题和导航

阶段 2: 文档管理 ✅

• 文档 CRUD 操作
• 文档列表 UI

阶段 3: Markdown 编辑 ✅

• 编辑器功能
• 快捷工具栏
• 自动保存

阶段 4: 预览渲染 ✅

• Markwon 集成
• 三模式切换

阶段 5: 图片导出 ✅

• 导出 PNG 功能
• 自定义配置

阶段 6: 设置与优化 🚧

• 主题、字体设置
• 性能优化

阶段 7: 测试与发布 ⏳

• 功能测试
• 打包发布

---