128 lines
4.6 KiB
Markdown
128 lines
4.6 KiB
Markdown
# Markdown To Web
|
||
|
||
此仓库将一组本地 Markdown 笔记（位于 `public/mengyanote`）转换成一个静态的 React 网站，便于浏览、检索和发布到网络上。
|
||
|
||
本 README 为中文说明，包含项目简介、运行/构建步骤、目录结构、如何编辑笔记以及部署和贡献指南，方便直接发布到 GitHub。
|
||
|
||
## 主要特性
|
||
|
||
- 从本地目录（`public/mengyanote`）递归读取 Markdown 文件并生成静态数据（`src/data`）。
|
||
- 使用 `react-markdown` 渲染 Markdown，支持数学公式（remark/rehype 插件）与代码高亮。
|
||
- 目录树侧边栏、内容渲染器等基础浏览功能。
|
||
- 通过简单脚本将 Markdown 文件转为项目需要的 JSON 数据，便于在静态站点中直接使用。
|
||
|
||
## 技术栈
|
||
|
||
- React 19
|
||
- Vite
|
||
- react-markdown + remark/rehype 插件（remark-gfm、remark-math、rehype-katex、rehype-highlight 等）
|
||
|
||
## 快速开始（Windows / cmd.exe）
|
||
|
||
1. 安装依赖
|
||
|
||
```
|
||
npm install
|
||
```
|
||
|
||
2. 本地开发（会先生成静态数据）
|
||
|
||
```
|
||
npm run dev
|
||
```
|
||
|
||
这会先执行 `node scripts/generateData.js` 从 `public/mengyanote` 读取 Markdown 并生成 `src/data` 下的 `directoryTree.json` / `fileContents.json` / `stats.json`，然后启动 Vite 开发服务器。
|
||
|
||
3. 生成生产构建
|
||
|
||
```
|
||
npm run build
|
||
```
|
||
|
||
4. 预览构建产物
|
||
|
||
```
|
||
npm run preview
|
||
```
|
||
|
||
5. 单独生成数据（不启动服务器）
|
||
|
||
```
|
||
npm run generate-data
|
||
```
|
||
|
||
6. 代码检查
|
||
|
||
```
|
||
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` 中的渲染类名/元素结构。
|
||
|
||
## 如何编辑/添加笔记
|
||
|
||
1. 在 `public/mengyanote` 下增加或修改 `.md` 文件，保持目录组织即可。
|
||
2. 运行 `npm run generate-data`（或 `npm run dev`）以重新生成 `src/data`。
|
||
3. 刷新浏览器查看最新内容。
|
||
|
||
注意：脚本会忽略以 `.` 开头的文件/目录（例如 `.obsidian`）和一些预设项（`node_modules`、`.git` 等）。
|
||
|
||
## 部署建议
|
||
|
||
- 静态站点：`npm run build` 会在 `dist/` 生成静态文件，适合部署到 GitHub Pages、Netlify、Vercel、或任意静态文件托管服务。
|
||
- GitHub Pages：构建后将 `dist/` 的内容发布到 gh-pages 分支或通过 GitHub Actions 自动发布。
|
||
|
||
示例（手工）：
|
||
|
||
1. 构建
|
||
|
||
```
|
||
npm run build
|
||
```
|
||
|
||
2. 将 `dist/` 内容上传到你的静态托管服务或 gh-pages 分支。
|
||
|
||
如果需要，我可以为你添加一个自动部署到 GitHub Pages 的 GitHub Actions 工作流。
|
||
|
||
## 定制渲染样式
|
||
|
||
如果你觉得当前 Markdown 美化太重并想改回更简洁的“图片优先”或原始样式：
|
||
|
||
- 编辑 `src/components/MarkdownRenderer.css`：移除或覆盖过度的样式（字体、背景、代码块高亮等）。
|
||
- 编辑 `src/components/MarkdownRenderer.jsx`：调整渲染器的 className、元素包装或忽略某些 remark/rehype 插件。
|
||
|
||
常见修改点：
|
||
- 移除 KaTeX 或代码高亮：在 `src/components/MarkdownRenderer.jsx` 中删除相应的 rehype 插件 import 与使用。
|
||
- 简化图片样式：在 CSS 中将 img 的 max-width、margin 等属性调整为你想要的样式。
|
||
|
||
## 贡献与许可
|
||
|
||
欢迎提交 Issue 或 Pull Request。仓库包含 `LICENSE`（请查看该文件以确认许可证类型）。
|
||
|
||
为了保持项目干净：
|
||
- 新功能请先创建 issue 讨论。
|
||
- 提交 PR 时附带简短说明和相关截图（如果是 UI 变更）。
|
||
|
||
## 联系方式
|
||
|
||
如需帮助或定制：在 Issue 中描述你想要的样式和示例图片/链接，我可以帮你修改 `MarkdownRenderer.css` / `MarkdownRenderer.jsx` 实现视觉风格。
|
||
|
||
---
|
||
|
||
祝发布顺利！如果你想，我可以：
|
||
|
||
- 帮你把 README 翻译成英文版本并放在 `README.en.md`；
|
||
- 或直接替你修改 Markdown 渲染样式（把渲染改成更像你“图片那种”的风格）。
|
||
|