# html-md2web-mkdocs-project

**Repository Path**: aylerh/html-md2web-mkdocs-project

## Basic Information

- **Project Name**: html-md2web-mkdocs-project
- **Description**: Nginx 静态页面发布与管理平台-本地 HTML 文件上传到服务器并访问;特点：（1）有前端页面；（2）可设置nginx的ip和port；多分支：(1)quartz:单md显示-latex好；（2）main-缺点：基于mkdocs;标题导航标签显示不好；底部有技术标签；
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-17
- **Last Updated**: 2026-04-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 概览
这是一个**轻量级的Nginx 静态页面发布与管理平台。
它允许用户通过可视化界面将本地 HTML或markdown(md)或zip（包含图片和md）文件上传到服务器，并立即通过 Nginx 进行访问，同时支持对已发布页面的元数据管理。
[项目位置](https://gitee.com/aylerh/html2web-project)

## 核心功能

1.  **一键发布**：
    *   上传 HTML 文件即可自动挂载到 Nginx 容器中。
    *   支持自定义**子目录**（例如 `/activity/2024/`），实现多项目隔离。（不设置则默认在static_html/根目录下）
2.  **页面管理**：
    *   **持久化记录**：记录上传时间、文件路径。
    *   **信息编辑**：可随时修改页面的“显示名称”和“描述备注”。
    *   **自动发现**：如果直接将文件复制到后台文件夹（FTP/命令行），系统能自动扫描并添加到列表。
3.  **动态配置**：
    *   在前端界面即可设置 Nginx 的访问 IP 和 端口，无需修改代码。
4.  **即时访问**：
    *   上传后生成可点击的跳转链接，直接预览效果。

## 优点
- **灵活别名路由**：
    *   默认模式：`http://127.0.0.1:5001/view/md1`
    *   物理映射：`http://127.0.0.1:5001/folder/md1`
- **自动冲突处理**：如果路由重复，系统会自动添加序号。

## 缺点
- md的latex未正确预览
- md预览中的标题目录显示不正确；

## 页面样式
### 首页：
![首页](./images/1.png)

### md发布
![md](./images/3.png)

超过3页有目录显示：
![3.1](./images/3.1.png)

缺点：无标题导航栏;
### 自带html-md在线编辑与pdf对比：
![md在线编辑与pdf对比](./images/2.png)

# 部署
## 重新构建
打开终端（Terminal / CMD），进入包含 docker compose.yml 的目录。
运行以下命令启动(重新构建镜像并启动)-有更新时：
```
docker compose down
docker compose up -d --build
```
-d: 后台运行。
--build: 确保每次代码修改后都会重新构建 Python 镜像。
## 仅启动：
```
docker compose up -d
```
## 从镜像启动
```
git clone https://gitee.com/aylerh/html2web-project
cd html2web-project
docker pull ayler/html-uploader-web:latest
docker compose up -d
```
# 使用流程

1.  **启动服务**
    *   在项目目录下运行终端命令：`docker compose up -d`。
    *   浏览器访问后台管理地址（默认 `http://localhost:HOST_PORT`）
    * -404 page not found时访问： `http://127.0.0.1:HOST_PORT`。

2.  **初始配置**
    *   点击页面右上角的 **“⚙️ Nginx 设置”**。
    *   输入服务器的 **IP 地址** 和 Nginx **端口**（如 `8081`），确保生成的跳转链接正确。

3.  **发布页面**
    *   **上传**：填写页面名称、描述，选择 HTML 文件。
    *   **分流**（可选）：输入“子目录”名称（如 `activity`），实现路径隔离。
    *   点击“上传并发布”。

4.  **访问与验证**
    *   在下方的列表中，点击绿色的 **“访问”** 按钮，即可跳转查看 Nginx 托管的静态页面。

5.  **后续管理**
    *   **修改信息**：点击“编辑”按钮修改页面的显示名称或备注。
    *   **手动同步**：如果通过 FTP/命令行直接将文件放入 `static_html` 文件夹，只需**刷新页面**，系统会自动发现并添加到列表中。

### 技术栈

*   **后端**：`Python` + `Flask`
    *   处理文件上传、路径计算、JSON 数据读写以及文件系统扫描。
*   **前端**：`HTML5` + `CSS3` + `JavaScript (Vanilla)`
    *   使用 Fetch API 实现异步提交（无刷新上传/修改）。
    *   采用卡片式布局和模态框（Modal）进行交互。
*   **Web 服务器**：`Nginx`
    *   运行在 Docker 容器中，负责高性能的静态资源解析。
*   **容器化**：`Docker` + `Docker Compose`
    *   **双服务架构**：Backend（Flask）和 Nginx 通过 **Docker Volume（挂载卷）** 共享 `static_html` 目录，实现文件共享。
*   **数据存储**：`JSON` + `Local Filesystem`
    *   无数据库依赖，使用 JSON 文件存储配置和元数据，轻量且易于迁移。