国庆修改
This commit is contained in:
159
README.en.md
Normal file
159
README.en.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# Markdown To Web
|
||||
|
||||
> Turn a local Markdown notes folder into a deployable static React site.
|
||||
|
||||
This project scans all `.md` files inside `public/mengyanote/`, generates JSON datasets (directory tree, file contents, stats) at build time, and renders them client‑side with React + `react-markdown`. The output is a **pure static site** (no server / no DB) suitable for GitHub Pages, Netlify, Vercel, or any static hosting.
|
||||
|
||||
Chinese documentation: see `README.md`.
|
||||
|
||||
## ✨ Features
|
||||
|
||||
- 🚀 One‑command data generation (recursive scan → JSON assets)
|
||||
- 📦 Fully static deployment (no runtime backend needed)
|
||||
- 🧭 Expandable directory tree with stable IDs / paths
|
||||
- 📝 Rich Markdown: GFM (tables, task lists, strikethrough), soft line breaks, math (KaTeX), code highlighting
|
||||
- 🧮 Math via `remark-math` + `rehype-katex`
|
||||
- 💡 Enhanced code blocks: language label + copy button
|
||||
- 📚 Breadcrumb navigation derived from file path
|
||||
- 🔌 Pluggable remark / rehype pipeline (easy to remove / replace)
|
||||
- 🕶 Dark theme (fully customizable via CSS)
|
||||
- 🔍 Multi-path fallback when fetching generated JSON (`/data` → `/src/data` → `./data`)
|
||||
- 🧯 Ignore mechanism via `ignore.json`
|
||||
- 📊 Basic statistics (file count, folder count, timestamp)
|
||||
|
||||
## 🛠 Tech Stack
|
||||
|
||||
- React 19 + Hooks + Context
|
||||
- Vite
|
||||
- `react-markdown` + remark / rehype plugins:
|
||||
- `remark-gfm`, `remark-math`, `remark-breaks`
|
||||
- `rehype-raw`, `rehype-katex`, `rehype-highlight`
|
||||
- Highlight.js theme (replaceable)
|
||||
- KaTeX (optional)
|
||||
|
||||
## ⚡ Quick Start
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run dev # generate data + start dev server
|
||||
npm run build # generate data + build static site (dist/)
|
||||
npm run preview # preview production build
|
||||
npm run generate-data # only regenerate JSON
|
||||
npm run lint
|
||||
```
|
||||
|
||||
## 📂 Key Structure
|
||||
|
||||
```
|
||||
public/
|
||||
mengyanote/ # Source Markdown tree (add your .md here)
|
||||
data/ # Public copy of generated JSON
|
||||
scripts/
|
||||
generateData.js # Node script: scans + emits JSON
|
||||
src/
|
||||
data/ # Generated JSON (consumed in dev/build)
|
||||
components/ # UI (MarkdownRenderer, Sidebar, ...)
|
||||
context/ # AppContext (state + actions)
|
||||
utils/fileUtils.js # Fetch + helpers + breadcrumbs
|
||||
```
|
||||
|
||||
## 🧬 How It Works
|
||||
|
||||
1. `generateData.js` walks `public/mengyanote/` (applying `ignore.json` rules)
|
||||
2. Builds:
|
||||
- `directoryTree.json` (hierarchical tree)
|
||||
- `fileContents.json` (path → raw markdown text)
|
||||
- `stats.json` (counts + timestamp)
|
||||
3. Writes duplicates to `src/data/` (for imports / dev) and `public/data/` (for runtime fetch in final build)
|
||||
4. Frontend loads JSON (tries `/data` → `/src/data` → `./data`) and renders selected file
|
||||
|
||||
```
|
||||
Markdown(.md) --> generateData.js --> JSON (tree, contents, stats) --> React (render)
|
||||
```
|
||||
|
||||
## 🧯 Ignore Rules
|
||||
|
||||
Default ignored: `.obsidian`, `.trash`, `.git`, `node_modules`, any dot‑prefixed file/dir.
|
||||
|
||||
Custom ignore: create `public/mengyanote/ignore.json`:
|
||||
|
||||
```json
|
||||
{ "ignore": ["Drafts", "private", "Scratch.md"] }
|
||||
```
|
||||
|
||||
## 🎨 Customization Cheatsheet
|
||||
|
||||
| Goal | Where | Action |
|
||||
|------|-------|--------|
|
||||
| Remove math | `MarkdownRenderer.jsx` | Drop `remark-math` + `rehype-katex` + CSS import |
|
||||
| Remove code highlighting | `MarkdownRenderer.jsx` | Remove `rehype-highlight` and theme CSS |
|
||||
| New highlight theme | Add dependency | Replace imported highlight style |
|
||||
| Inline code as plain text | Already done | Custom plugin strips inline code styling |
|
||||
| Change image layout | `MarkdownRenderer.css` | Adjust `.markdown-image img` |
|
||||
| Change breadcrumb format | `fileUtils.generateBreadcrumbs` | Modify join logic |
|
||||
|
||||
## 🚢 Deployment
|
||||
|
||||
Build output: `dist/` (fully static).
|
||||
|
||||
Platforms:
|
||||
|
||||
| Platform | Notes |
|
||||
|----------|-------|
|
||||
| GitHub Pages | Push `dist/` to `gh-pages` or use an Action |
|
||||
| Netlify | Build: `npm run build`, Publish: `dist` |
|
||||
| Vercel | Auto-detect Vite |
|
||||
| Any static host / Nginx | Upload `dist/` |
|
||||
|
||||
Example 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";
|
||||
}
|
||||
```
|
||||
|
||||
## FAQ
|
||||
|
||||
**New file not appearing?** Regenerate data: `npm run generate-data` (or rerun dev/build).
|
||||
|
||||
**Ignore not working?** Ensure `ignore.json` sits directly in `public/mengyanote/` and key is exactly `ignore`.
|
||||
|
||||
**Large number of files causes slow load?** Consider splitting `fileContents.json` into per‑file JSON (enhancement idea).
|
||||
|
||||
**Search support?** Not yet. You can integrate `minisearch` or `lunr` during build.
|
||||
|
||||
**Can I support frontmatter?** Extend the generator to parse YAML frontmatter and attach metadata to each node.
|
||||
|
||||
## Roadmap (Open for Contributions)
|
||||
|
||||
- [ ] Full‑text search
|
||||
- [ ] Per‑file lazy loading
|
||||
- [ ] Recent updates panel / changelog
|
||||
- [ ] Frontmatter tags + filters
|
||||
- [ ] RSS / JSON feed generation
|
||||
- [ ] PDF / print friendly mode
|
||||
- [ ] Service Worker caching
|
||||
- [ ] GitHub Actions deploy workflow example
|
||||
|
||||
## Contributing & License
|
||||
|
||||
Issues / PRs welcome. Please open an issue before large feature work; attach screenshots for UI changes. License: see `LICENSE`.
|
||||
|
||||
## Contact
|
||||
|
||||
Open an issue describing:
|
||||
|
||||
- Desired visual style (links / screenshots)
|
||||
- Needed deployment pipeline (e.g., GitHub Pages Action)
|
||||
- Theming or performance concerns
|
||||
|
||||
I can suggest patches or configuration examples.
|
||||
|
||||
---
|
||||
|
||||
Happy publishing! If you build cool themes (minimal / book‑like / image‑first), consider sharing them back. 🙌
|
||||
Reference in New Issue
Block a user