🎉 v2.0 重要更新 (2025-12-19)

✅ 完全移除 localStorage 依赖，解决浏览器权限弹窗问题

✅ 完美支持移动端浏览器（微信、Safari iOS 等）

✅ 隐私模式/无痕模式下正常工作

✅ 添加错误边界和友好的错误提示

✅ 优化网络请求，支持相对路径部署

📖 详细说明请查看前端优化说明.md

✨ 特性

📝 Markdown 渲染: 使用 react-markdown 提供强大的渲染能力
🎨 GitHub 风格: 标准的 GitHub Markdown 样式
🔤 霞鹜文楷字体: 全站使用 LXGW WenKai Mono 等宽字体
📂 文件树导航: 直观的侧边栏目录结构
🚀 快速响应: FastAPI 后端 + React 前端
💡 代码高亮: 支持多种编程语言的语法高亮
🧮 数学公式: KaTeX 数学公式渲染支持
📱 响应式设计: 完美适配桌面和移动设备
🌐 跨浏览器兼容: 支持所有主流浏览器和移动端
🔒 隐私模式支持: 在隐私/无痕模式下正常工作

🛠 技术栈

后端

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. 启动后端服务

# 进入后端目录
cd mengyanote-backend

# 安装依赖（首次运行）
pip install -r requirements.txt

# 启动服务
python main.py

后端将在 http://localhost:8000 运行

2. 启动前端服务

# 进入前端目录
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 文件：

VITE_API_BASE=http://localhost:8000

📦 构建生产版本

前端构建

cd mengyanote-frontend
npm run build

构建产物在 dist 目录，可部署到任何静态托管服务。

🐛 故障排除

前端无法连接后端

确认后端服务正在运行（访问 http://localhost:8000/api/health）
检查浏览器控制台的网络请求错误
确认后端端口为 8000

字体未加载

确认 LXGWWenKaiMono-Medium.ttf 存在于 public 目录
检查浏览器开发者工具的网络面板
清除浏览器缓存重试

Markdown 渲染异常

检查文件编码是否为 UTF-8
查看浏览器控制台错误信息
确认 react-markdown 相关依赖已正确安装

📝 开发建议

IDE: 推荐使用 VS Code
代码规范: 前端使用 ESLint 进行代码检查
热重载: 后端和前端都支持热重载，修改代码自动刷新
调试: 使用 Chrome DevTools 进行前端调试

Made with ❤️ by 树萌芽

🛠 技术栈

React 19 + Hooks + Context
Vite 构建
react-markdown + remark / rehype 插件：
- remark-gfm（扩展语法）
- remark-math（数学公式）
- remark-breaks（软换行）
- rehype-raw（允许原始 HTML 渲染）
- rehype-katex（数学公式渲染）
- rehype-highlight（代码高亮）
Highlight.js 默认主题（可替换）
KaTeX 样式（按需可移除）

所有数据生成逻辑在 Node 脚本层 完成，前端只做纯渲染，部署安全轻量。

⚡ 快速开始（Windows / cmd.exe）

安装依赖

npm install

本地开发（会先生成静态数据）

npm run dev

这会先执行 node scripts/generateData.js 从 public/mengyanote 读取 Markdown 并生成 src/data 下的 directoryTree.json / fileContents.json / stats.json，然后启动 Vite 开发服务器。

生成生产构建

npm run build

预览构建产物

npm run preview

单独生成数据（不启动服务器）

npm run generate-data

代码检查

npm run lint

🧬 项目结构（重要文件/目录）

public/mengyanote/ - 源 Markdown 笔记目录（请把你的 .md 文件放在这里以纳入站点）。
scripts/generateData.js - 将 Markdown 文件读取并生成 src/data 的脚本。
src/data/ - 由脚本生成的 JSON 数据（目录树、文件内容、统计信息）。
src/components/MarkdownRenderer.jsx - Markdown 渲染组件（样式与功能定制点）。
src/components/MarkdownRenderer.css - Markdown 渲染相关样式（可在此处简化或替换为你喜欢的样式）。
src/components/Sidebar.jsx - 侧边栏目录树组件。
src/context/AppContext.jsx - 全局上下文与路由状态。
scripts/ - 工具脚本（目前包含 generateData.js）。

示例：如果你想让 Markdown 渲染更简洁（“换成我图片那种”样式），可以编辑 src/components/MarkdownRenderer.css 或直接修改 MarkdownRenderer.jsx 中的渲染类名/元素结构。

✍️ 如何编辑/添加笔记

在 public/mengyanote 下增加或修改 .md 文件，保持目录组织即可。
运行 npm run generate-data（或 npm run dev）以重新生成 src/data。
刷新浏览器查看最新内容。

忽略机制

默认忽略：.obsidian、.trash、.git、node_modules、所有以 . 开头的文件或目录。
自定义忽略：在 public/mengyanote/ignore.json 中加入：

{
	"ignore": ["临时", "草稿.md", "private"]
}

ignore.json 位于源根目录（public/mengyanote），脚本运行时会打印“已加载忽略配置”。

🚢 部署建议

静态站点：npm run build 会在 dist/ 生成静态文件，适合部署到 GitHub Pages、Netlify、Vercel、或任意静态文件托管服务。
GitHub Pages：构建后将 dist/ 的内容发布到 gh-pages 分支或通过 GitHub Actions 自动发布。

示例（手工）：

构建

npm run build

将 dist/ 内容上传到你的静态托管服务或 gh-pages 分支。

如果需要，我可以为你添加一个自动部署到 GitHub Pages 的 GitHub Actions 工作流（deploy.yml）。示例工作流会：

触发条件：push 到 main 或手动触发
安装依赖 & 运行 npm run build
发布 dist/ 到 gh-pages 分支

（如需请开 Issue 或在 PR 中请求）

其他托管方式

平台	方式	备注
GitHub Pages	gh-pages 分支 / Action	需启用 Pages
Netlify	直接连接仓库	Build 命令：`npm run build`，Publish：`dist`
Vercel	导入项目	自动识别 Vite
OSS / Nginx	上传 dist	纯静态即可

基础 Nginx 配置示例

server {
	listen 80;
	server_name example.com;
	root /var/www/markdown-to-web/dist;
	location / { try_files $uri /index.html; }
	add_header Cache-Control "public, max-age=31536000";
}

🎨 定制渲染样式

如果你觉得当前 Markdown 美化太重并想改回更简洁的“图片优先”或原始样式：

编辑 src/components/MarkdownRenderer.css：移除或覆盖过度的样式（字体、背景、代码块高亮等）。
编辑 src/components/MarkdownRenderer.jsx：调整渲染器的 className、元素包装或忽略某些 remark/rehype 插件。

常见修改点

需求	修改位置	说明
去掉公式支持	`MarkdownRenderer.jsx`	移除 `remark-math` / `rehype-katex` 并删 CSS 引入
去掉代码高亮	`MarkdownRenderer.jsx`	移除 `rehype-highlight` 与对应样式
禁用内联代码特殊样式	已内置	自定义插件 `remarkDisableInlineCode` 已将 inlineCode 转普通文本
改图片最大宽度	`MarkdownRenderer.css`	调整 `.markdown-image img`
更换高亮主题	安装新主题	引入其他 highlight.js CSS
调整面包屑	`fileUtils.generateBreadcrumbs`	可改分隔符或格式

架构 / 数据流程简述

┌──────────────┐   扫描/过滤    ┌────────────────┐   JSON写入   ┌───────────────┐
│ public/mengya │ ─────────────▶ │ generateData.js │ ───────────▶ │ src/data/*.json │
│ note/ (原始MD)│   ignore.json  │  (Node脚本)     │   public/data │ (目录/内容/统计)│
└──────────────┘                 └────────────────┘               └───────────────┘
																	  │
																	  ▼
															 前端 (React 渲染)

前端加载策略：尝试按顺序 fetch：/data/... → /src/data/... → ./data/...。

渲染组件要点

代码块组件：支持复制、语言标签、降尾换行处理
图片：包裹 <figure> + <figcaption>
标题：自动生成 id + 锚点链接
链接：区分内部/外部，[[wikilink]] 保留为文本标签（可扩展）
表格：外层包裹 div 实现横向滚动容器

性能提示

Markdown 数量巨大时，可按需拆分 lazy-load（目前为一次性加载全部 JSON）
可拓展为：构建阶段拆分单文件 JSON，运行时按需请求
可增加 Service Worker 缓存静态 JSON

❓ 常见问题（FAQ）

Q: 为什么我新增文件后页面没有显示？
A: 需要重新运行 npm run generate-data 或 npm run dev 让脚本再生成数据。

Q: 想忽略某个目录但它还是出现？
A: 确认 ignore.json 位于 public/mengyanote/ 根目录，键名是 ignore，数组项不要写路径前缀。

Q: 能否按需加载而不是一次性加载所有内容？
A: 当前实现为构建期大 JSON。可拓展为“每文件单独 JSON + 动态 fetch”。

Q: 是否支持搜索？
A: 目前未实现。可通过构建阶段生成反向索引（lunr / minisearch）再前端搜索。

Q: 图片如何放大预览？
A: 可在 MarkdownRenderer.jsx 中为 img 包裹 Lightbox 组件或添加点击事件。

Q: 可以改成多语言站点？
A: 可在数据生成脚本中区分语言目录（如 en/、zh/），渲染层添加语言切换上下文。

🧭 Roadmap（计划）

全文搜索（可选：关键词高亮）
按需加载：文件内容拆分
文件更新 diff / 最近更新列表
Tag/Frontmatter 支持（YAML 解析）
RSS / JSON Feed 输出
导出 PDF / 打印优化
Service Worker 缓存加速
GitHub Actions 自动部署工作流示例

欢迎在 Issue 中补充你的需求。

🤝 贡献与许可

欢迎提交 Issue 或 Pull Request。仓库包含 LICENSE（请查看该文件以确认许可证类型）。

为了保持项目干净：

新功能请先创建 issue 讨论。
提交 PR 时附带简短说明和相关截图（如果是 UI 变更）。

Languages

JavaScript 46.5%

CSS 38.8%

Python 11.6%

Batchfile 1.8%

Dockerfile 0.8%

Other 0.5%

README.md Unescape Escape

萌芽笔记 🌱

✨ 特性

🛠 技术栈

后端

前端

🚀 快速开始

方式一：使用批处理脚本（Windows推荐）

启动后端

启动前端

方式二：手动启动

1. 启动后端服务

2. 启动前端服务

📁 项目结构

🎯 功能说明

后端 API

前端功能

🎨 字体配置

🔧 环境变量

前端环境变量（可选）

📦 构建生产版本

前端构建

🐛 故障排除

前端无法连接后端

字体未加载

Markdown 渲染异常

📝 开发建议

🛠 技术栈

⚡ 快速开始（Windows / cmd.exe）

🧬 项目结构（重要文件/目录）

✍️ 如何编辑/添加笔记

忽略机制

🚢 部署建议

其他托管方式

基础 Nginx 配置示例

🎨 定制渲染样式

常见修改点

架构 / 数据流程简述

渲染组件要点

性能提示

❓ 常见问题（FAQ）

🧭 Roadmap（计划）

🤝 贡献与许可

README.md