# md2html

**Repository Path**: fly_zero/md2html

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-03
- **Last Updated**: 2026-06-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

**Markdown 工作台 (md2html)**

一个轻量的本地 Markdown 预览服务，将指定目录下的 `.md` 文件渲染为 HTML，供前端查看与导航。适合作为本地文档阅读器或临时 Markdown 服务器。

**主要特性**
- 渲染 Markdown 支持代码块、表格与目录（TOC）。
- 将文档内相对图片资源重写为可通过服务访问的 `/asset` 路径。
- 将相互引用的 `.md` 链接重写为内部路由 `/view?file=...`，可在前端直接打开其它 Markdown 文档。

**依赖**
- Python 3.8+
- 在项目根目录有 `requirements.txt`，可以用 pip 安装依赖：

```bash
python3 -m pip install -r requirements.txt
```

**快速开始**

1. 在项目根目录运行服务：

```bash
python3 server.py <PORT> <MARKDOWN_DIR>
# 例如：
python3 server.py 8000 .
```

2. 在浏览器打开：

```
http://127.0.0.1:8000
```

默认页面会列出目录下的 `.md` 文件并在右侧展示渲染后的文档与标题大纲。

**关键文件**
- 服务入口：[server.py](server.py)
- Python 依赖：[requirements.txt](requirements.txt)
- 前端模板： [frontend/page.html](frontend/page.html)
- 静态文件目录： [static](static)

**示例**
- 在 Markdown 中使用相对图片：

```markdown
![示例图片](images/example.png)
```

渲染后图片链接会被改写为类似：`/asset?file=docs/guide.md&path=images/example.png`，服务会返回对应文件内容。

- 在 Markdown 中相互链接：

```markdown
[下一章](../other/next.md)
```

此类相对链接会被转换为 `/view?file=...`，点击将在前端打开目标 Markdown 文档。

**故障排查**
- 如果页面显示 "非法文件路径" 或链接打不开：检查 Markdown 路径是否在启动时指定的 `MARKDOWN_DIR` 目录下，服务会拒绝访问工作目录以外的文件。
- 图片或静态资源 404：确认资源相对于 Markdown 文件的相对路径正确，并存在于磁盘。

**贡献与许可**
- 欢迎提交 issues 与 pull requests。

---
如果需要，我可以把 README 翻译为英文或补充部署/容器化说明。