继续提交
This commit is contained in:
207
README.md
207
README.md
@@ -1,29 +1,198 @@
|
||||
# Markdown To Web
|
||||
# 萌芽笔记 🌱
|
||||
|
||||
> 将本地 Markdown 笔记目录“一键”编译为可部署的静态 React 网站。
|
||||
一个优雅的 Markdown 笔记 Web 应用，支持实时预览和 GitHub 风格渲染。
|
||||
|
||||
此仓库会读取 `public/mengyanote/` 下的所有 Markdown 文件，生成 JSON 数据，并在前端通过 React + react-markdown 渲染，最终可直接构建成 **纯静态站点**（可部署到 GitHub Pages / Netlify / Vercel / 任意 Nginx / OSS 等）。
|
||||
> **🎉 v2.0 重要更新 (2025-12-19)**
|
||||
> - ✅ 完全移除 localStorage 依赖，解决浏览器权限弹窗问题
|
||||
> - ✅ 完美支持移动端浏览器（微信、Safari iOS 等）
|
||||
> - ✅ 隐私模式/无痕模式下正常工作
|
||||
> - ✅ 添加错误边界和友好的错误提示
|
||||
> - ✅ 优化网络请求，支持相对路径部署
|
||||
> - 📖 详细说明请查看 [前端优化说明.md](前端优化说明.md)
|
||||
|
||||
本 README（中文）包含：项目定位、特性说明、运行与构建、内部工作原理、目录结构、忽略与定制、部署方式、常见问题（FAQ）与未来计划（Roadmap）。
|
||||
## ✨ 特性
|
||||
|
||||
如需英文版本，请查看 `README.en.md`。
|
||||
- 📝 **Markdown 渲染**: 使用 `react-markdown` 提供强大的渲染能力
|
||||
- 🎨 **GitHub 风格**: 标准的 GitHub Markdown 样式
|
||||
- 🔤 **霞鹜文楷字体**: 全站使用 LXGW WenKai Mono 等宽字体
|
||||
- 📂 **文件树导航**: 直观的侧边栏目录结构
|
||||
- 🚀 **快速响应**: FastAPI 后端 + React 前端
|
||||
- 💡 **代码高亮**: 支持多种编程语言的语法高亮
|
||||
- 🧮 **数学公式**: KaTeX 数学公式渲染支持
|
||||
- 📱 **响应式设计**: 完美适配桌面和移动设备
|
||||
- 🌐 **跨浏览器兼容**: 支持所有主流浏览器和移动端
|
||||
- 🔒 **隐私模式支持**: 在隐私/无痕模式下正常工作
|
||||
|
||||
## ✨ 主要特性
|
||||
## 🛠 技术栈
|
||||
|
||||
- 🚀 **一键生成数据**：脚本自动递归扫描 `public/mengyanote`，提取目录树、文件内容与统计信息。
|
||||
- 📦 **纯静态输出**：构建阶段就准备好全部数据，无需后端 / Serverless API。
|
||||
- 🧭 **动态目录树**：可展开/折叠，每个节点保留唯一 `path` 与 `id`。
|
||||
- 📝 **Markdown 全面支持**：GFM（表格 / 任务列表 / 删除线）、换行、数学公式（KaTeX）、代码块高亮（Highlight.js）。
|
||||
- 🧮 **数学公式渲染**：`remark-math` + `rehype-katex`。
|
||||
- 💡 **代码体验增强**：复制按钮、语言标签、自动高亮。
|
||||
- 📚 **面包屑导航**：基于文件路径实时生成。
|
||||
- 🧱 **可定制渲染组件**：可移除/替换任意 remark/rehype 插件，或覆写组件（如链接、图片、表格、代码块）。
|
||||
- 🕶 **深色风格**（可自定义）：CSS 易修改，可换成“极简/原味/图片优先”布局。
|
||||
- 🔍 **预生成数据多路径兜底**：前端运行时尝试从 `/data` 或 `/src/data` 加载，兼容不同构建/部署结构。
|
||||
- 🧯 **忽略机制**：支持 `ignore.json` 自定义排除目录 / 文件。
|
||||
- 📊 **统计信息**：生成文件总数、文件夹总数、生成时间等元数据。
|
||||
### 后端
|
||||
- **Python 3.8+**
|
||||
- **FastAPI** - 现代、快速的 Web 框架
|
||||
- **Uvicorn** - ASGI 服务器
|
||||
|
||||
### 前端
|
||||
- **React 19** - 用户界面库
|
||||
- **Vite 7** - 极速构建工具
|
||||
- **react-markdown** - Markdown 渲染
|
||||
- **github-markdown-css** - GitHub 风格样式
|
||||
- **rehype/remark 插件** - 扩展 Markdown 功能
|
||||
- GFM (GitHub Flavored Markdown)
|
||||
- 代码高亮 (highlight.js)
|
||||
- 数学公式 (KaTeX)
|
||||
- HTML 支持
|
||||
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 方式一：使用批处理脚本（Windows推荐）
|
||||
|
||||
#### 启动后端
|
||||
双击运行 `启动后端.bat`
|
||||
|
||||
#### 启动前端
|
||||
双击运行 `启动前端.bat`
|
||||
|
||||
### 方式二：手动启动
|
||||
|
||||
#### 1. 启动后端服务
|
||||
|
||||
```bash
|
||||
# 进入后端目录
|
||||
cd mengyanote-backend
|
||||
|
||||
# 安装依赖（首次运行）
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 启动服务
|
||||
python main.py
|
||||
```
|
||||
|
||||
后端将在 `http://localhost:8000` 运行
|
||||
|
||||
#### 2. 启动前端服务
|
||||
|
||||
```bash
|
||||
# 进入前端目录
|
||||
cd mengyanote-frontend
|
||||
|
||||
# 安装依赖（首次运行）
|
||||
npm install
|
||||
|
||||
# 启动开发服务器
|
||||
npm run dev
|
||||
```
|
||||
|
||||
前端将在 `http://localhost:5173` 运行
|
||||
|
||||
## 📁 项目结构
|
||||
|
||||
```
|
||||
mengyanote/
|
||||
├── mengyanote-backend/ # 后端服务
|
||||
│ ├── main.py # FastAPI 应用入口
|
||||
│ ├── requirements.txt # Python 依赖
|
||||
│ └── mengyanote/ # Markdown 文件存储目录
|
||||
│ ├── 编程语言/
|
||||
│ ├── 计算机科普/
|
||||
│ ├── 计算机网络/
|
||||
│ └── ...
|
||||
│
|
||||
├── mengyanote-frontend/ # 前端应用
|
||||
│ ├── src/
|
||||
│ │ ├── components/ # React 组件
|
||||
│ │ │ ├── Sidebar.jsx # 侧边栏组件
|
||||
│ │ │ ├── MarkdownRenderer.jsx # Markdown 渲染器
|
||||
│ │ │ └── ...
|
||||
│ │ ├── context/ # React Context
|
||||
│ │ ├── utils/ # 工具函数
|
||||
│ │ ├── App.jsx # 主应用组件
|
||||
│ │ └── main.jsx # 应用入口
|
||||
│ ├── public/ # 静态资源
|
||||
│ │ └── LXGWWenKaiMono-Medium.ttf # 字体文件
|
||||
│ ├── package.json # 前端依赖
|
||||
│ └── vite.config.js # Vite 配置
|
||||
│
|
||||
├── 启动后端.bat # 后端启动脚本
|
||||
├── 启动前端.bat # 前端启动脚本
|
||||
├── 启动说明.md # 详细启动说明
|
||||
└── README.md # 项目说明
|
||||
```
|
||||
|
||||
## 🎯 功能说明
|
||||
|
||||
### 后端 API
|
||||
|
||||
- `GET /api/tree` - 获取文件树结构
|
||||
- `GET /api/file?path={path}` - 获取指定文件内容
|
||||
- `GET /api/health` - 健康检查
|
||||
- `GET /docs` - API 文档（Swagger UI）
|
||||
|
||||
### 前端功能
|
||||
|
||||
- **文件导航**: 点击左侧文件树浏览笔记
|
||||
- **Markdown 渲染**: 自动渲染 GitHub 风格的 Markdown
|
||||
- **代码高亮**: 自动识别并高亮代码块
|
||||
- **数学公式**: 支持行内和块级数学公式
|
||||
- **图片支持**: 点击图片可放大查看
|
||||
- **外链处理**: 外部链接自动在新标签页打开
|
||||
|
||||
## 🎨 字体配置
|
||||
|
||||
项目使用 **霞鹜文楷等宽体 (LXGW WenKai Mono)** 作为全站字体。
|
||||
|
||||
字体文件位置：`mengyanote-frontend/public/LXGWWenKaiMono-Medium.ttf`
|
||||
|
||||
如果字体文件缺失，系统会自动回退到默认字体。
|
||||
|
||||
## 🔧 环境变量
|
||||
|
||||
### 前端环境变量（可选）
|
||||
|
||||
在 `mengyanote-frontend` 目录创建 `.env` 文件：
|
||||
|
||||
```env
|
||||
VITE_API_BASE=http://localhost:8000
|
||||
```
|
||||
|
||||
## 📦 构建生产版本
|
||||
|
||||
### 前端构建
|
||||
|
||||
```bash
|
||||
cd mengyanote-frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
构建产物在 `dist` 目录，可部署到任何静态托管服务。
|
||||
|
||||
## 🐛 故障排除
|
||||
|
||||
### 前端无法连接后端
|
||||
1. 确认后端服务正在运行（访问 http://localhost:8000/api/health）
|
||||
2. 检查浏览器控制台的网络请求错误
|
||||
3. 确认后端端口为 8000
|
||||
|
||||
### 字体未加载
|
||||
1. 确认 `LXGWWenKaiMono-Medium.ttf` 存在于 `public` 目录
|
||||
2. 检查浏览器开发者工具的网络面板
|
||||
3. 清除浏览器缓存重试
|
||||
|
||||
### Markdown 渲染异常
|
||||
1. 检查文件编码是否为 UTF-8
|
||||
2. 查看浏览器控制台错误信息
|
||||
3. 确认 react-markdown 相关依赖已正确安装
|
||||
|
||||
## 📝 开发建议
|
||||
|
||||
1. **IDE**: 推荐使用 VS Code
|
||||
2. **代码规范**: 前端使用 ESLint 进行代码检查
|
||||
3. **热重载**: 后端和前端都支持热重载，修改代码自动刷新
|
||||
4. **调试**: 使用 Chrome DevTools 进行前端调试
|
||||
|
||||
---
|
||||
|
||||
**Made with ❤️ by 树萌芽**
|
||||
|
||||
> 该项目适合：知识库发布、学习笔记归档、团队内部静态文档、离线备份网页化。
|
||||
|
||||
## 🛠 技术栈
|
||||
|
||||
|
||||
Reference in New Issue
Block a user