# MDWeb

**Repository Path**: chwang1986/mdweb

## Basic Information

- **Project Name**: MDWeb
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-09
- **Last Updated**: 2026-04-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MDWeb

> 把本地 Markdown 文件夹变成可浏览网站的全栈项目

---

## 项目简介

MDWeb 是一个轻量级的全栈 Web 应用，核心功能是将本地按文件夹组织的 Markdown 文件自动渲染成结构清晰、可在浏览器中浏览的网站。

---

## 核心功能

- 📁 自动读取指定文件夹下的 Markdown 文件，按子文件夹分类展示
- 📂 支持嵌套文件夹结构，最大深度 4 层
- ➕ 向文件夹添加 .md 文件即可更新网站内容，无需重启
- 🔢 通过配置文件控制文件夹和文件的显示顺序
- 📄 网页端实时渲染 Markdown 内容，支持代码高亮、表格、Todo list
- 📌 支持置顶文件配置
- 🕐 首页动态展示最近更新的文章
- 🎨 支持浅色/深色模式切换，界面更友好
- 📱 响应式设计，支持手机和平板访问
---

## 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| 后端 | Python 3 + FastAPI | 现代 Python Web 框架，自动生成 API 文档，异步支持 |
| 前端 | Vue 3 + Vite | 组件化前端框架，Vite 提供极速开发体验 |
| Markdown 渲染 | markdown-it | 插件生态丰富，支持代码高亮、数学公式扩展 |
| 任务列表 | markdown-it-task-lists | 支持 Markdown 任务列表语法 |
| 代码高亮 | highlight.js | 支持多种编程语言，主题丰富 |
| 配置 | `_config.json` | 每个文件夹下的可选配置文件，控制排序和显示名称 |
| 版本控制 | Git | 从第一天开始纳入版本控制 |
| HTTP 请求 | axios | 前端与后端 API 通信路由 |
| 路由 | vue3-router | 前端页面路由管理 |

---


## 项目结构

```
MDWeb/
├── backend/                # 后端代码
│   ├── routers/            # 路由模块
│   │   └── files.py        # 文件相关 API 路由
│   ├── services/           # 业务逻辑
│   │   └── file_service.py # 文件服务实现
│   ├── config.py           # 配置文件
│   ├── main.py             # 应用入口
│   └── requirements.txt    # Python 依赖
├── frontend/               # 前端代码
│   ├── public/             # 静态资源
│   ├── src/
│   │   ├── api/            # API 调用
│   │   │   └── index.js    # API 封装
│   │   ├── assets/         # 静态资源
│   │   ├── components/     # 组件
│   │   │   └── SideBar.vue # 侧边栏组件
│   │   ├── router/         # 路由配置
│   │   │   └── index.js    # 路由定义
│   │   ├── views/          # 页面
│   │   │   ├── ArticleView.vue # 文章页面
│   │   │   └── HomeView.vue    # 主页
│   │   ├── App.vue         # 应用主组件
│   │   ├── main.js         # 应用入口
│   │   └── style.css       # 全局样式
│   ├── .env                # 本地环境变量（不提交 Git）
│   ├── .env.example        # 环境变量模板（提交 Git）
│   ├── index.html          # HTML 模板
│   ├── package-lock.json   # 依赖锁定文件
│   ├── package.json        # 前端依赖配置
│   └── vite.config.js      # Vite 配置
├── md_files/               # Markdown 文件存储
│   ├── git使用规范/
│   ├── 代码编写规范/
│   ├── markdown基础知识/
│   ├── 办事指南/
│   ├── 日常生活/
│   └── 联系方式/
├── docs/                   # 项目开发文档
│   ├── 00_启动记录.md
│   └── 01_项目启动零七八碎的记录.md
├── .gitignore              # Git 忽略文件
├── README.md               # 项目 README
├── package-lock.json       # 依赖锁定文件
├── package.json            # 项目依赖配置
└── requirements.txt        # Python 依赖
```

---

## 快速开始

### 1. 克隆仓库

```bash
git clone https://gitee.com/chwang1986/mdweb.git
cd mdweb
```

### 2. 配置后端

```bash
cd backend

# 创建虚拟环境（推荐）
python -m venv venv

# 激活虚拟环境
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt
```

编辑 `backend/config.py`，将 `MD_ROOT` 指向你的 Markdown 文件夹：

```python
# 默认指向项目根目录下的 md_files 文件夹
MD_ROOT = "../md_files"

# 可以修改为你自己的 Markdown 文件夹路径
# MD_ROOT = "/path/to/your/markdown/folder"
```

### 3. 配置前端

```bash
cd frontend
npm install
```

复制环境变量模板：

```bash
cp .env.example .env
```

编辑 `frontend/.env`，填入你的后端地址：

```
# 本机访问用 localhost
VITE_API_BASE_URL=http://localhost:8000/api

# 局域网访问，改成你电脑的局域网 IP（Windows 用 ipconfig 查询）
# VITE_API_BASE_URL=http://192.168.x.x:8000/api
```

### 4. 启动服务

**后端：**

```bash
cd backend
venv\Scripts\activate   # Windows
uvicorn main:app --reload --host 0.0.0.0
```

访问 `http://localhost:8000/docs` 查看自动生成的 API 文档。

**前端：**

```bash
cd frontend
npm run dev
```

访问 `http://localhost:5173` 查看页面。

### 5. 局域网访问（手机/平板）

1. 查询电脑局域网 IP：

```powershell
# Windows
ipconfig
# 找到"无线局域网适配器 WLAN"下的 IPv4 地址，例如 192.168.1.100
```

2. 修改 `frontend/.env`：

```
VITE_API_BASE_URL=http://192.168.1.100:8000/api
```

3. 确保前端和后端都以 `--host 0.0.0.0` 启动（已在 `vite.config.js` 中配置）

4. 手机与电脑连接同一 WiFi，访问 `http://192.168.1.100:5173`

---

## Markdown 内容文件夹结构（例子）

```
md_files/                       # MD_ROOT 指向这里
├── site_config.json            # 网站配置（置顶文件等）
├── git使用规范/                 # Git 相关规范文档
│   ├── Git基础操作.md
│   └── Git工作流程.md
├── 代码编写规范/                # 各种编程语言的代码规范
│   ├── java/                   # Java 代码规范
│   │   └── Java项目开发规范.md
│   ├── matlab/                 # Matlab 代码规范
│   │   └── Matlab项目开发规范.md
│   └── python/                 # Python 代码规范
│       └── Python项目开发规范.md
├── markdown基础知识/            # Markdown 语法指南
├── 办事指南/                   # 日常办事流程
├── 日常生活/                   # 生活相关内容
└── 联系方式/                   # 联系信息
```

### `_config.json` 说明

控制文件夹的显示顺序和名称：

```json
{
  "title": "Python 基础",
  "order": 1,
  "description": "变量、函数、面向对象等基础概念"
}
```

### `site_config.json` 说明

配置首页置顶文件：

```json
{
  "pinned": [
    { "folder": "文件夹名", "file": "文件名.md", "label": "描述文字" },
    { "folder": "文件夹名", "file": "文件名.md", "label": "描述文字" }
  ]
}
```

---

## API 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/recent` | 获取最近更新的文章列表 |
| GET | `/api/pinned` | 获取置顶文件列表 |
| GET | `/api/folders` | 获取所有文件夹列表 |
| GET | `/api/folders/{folder}/files` | 获取指定文件夹下的文件列表 |
| GET | `/api/folders/{folder}/files/{file}` | 获取单篇文章的原始内容 |
| GET | `/api/tree` | 获取完整的目录树结构 |
| GET | `/api/file/{file_path:path}` | 通过相对路径获取文件内容 |

---

## 开发记录

本项目的完整开发过程记录在 `docs/` 文件夹下，包括每次迭代的决策、遇到的问题和解决方案。

---


## License

MIT