# html-md2web-project

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

## Basic Information

- **Project Name**: html-md2web-project
- **Description**: 不要基于mkdocs;
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-24
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

## 核心功能

1.  **一键发布**：
    *   上传 HTML 文件即可自动挂载到 Nginx 容器中。
    *   支持上传 **Markdown (MD)** 或 **ZIP 压缩包**（自动处理图片引用），并渲染为高性能静态网页。
    *   **智能项目转换**：向 HTML 项目添加 MD 文件会自动升级为“MD 站点”，开启高级渲染功能。
    *   支持自定义**子目录**（例如 `/docs/v1/`），实现项目隔离。
2.  **专业级双导航渲染**：
    *   **顶部导航栏 (Top Nav)**：横向展示页面标签，支持多文件快速切换。
    *   **侧边目录 (Sidebar TOC)**：专注当前页面的层级标题（H1-H3），支持锚点平滑跳转。
    *   **LaTeX 支持**：完美预览数学公式（块级与行内）。
    *   **多标签页 (Tabs)**：支持 `::: tabs` 容器语法。
3.  **精准全文搜索**：
    *   **段落级索引**：支持跨文档搜索，并以段落为单位展示结果。
    *   **智能定位**：点击搜索结果可自动跳转至对应文档位置并高亮显示。
4. **页面管理与运维**：
    *   **智能主页路由**：根路径 `/` 默认进入主页。支持使用 `templates/default_page.md` 作为默认页，也可在管理中心将任意已托管页面设为全站主页。
    *   **权限隔离**：管理中心（通过 `.env` 定义路由）提供完整上传与配置功能，确保核心管理操作的安全。
    *   **全功能文件管理**：支持在线查看、新增、删除已托管文件，并可实时修改页面标签名。
    *   **持久化记录**：无数据库依赖，使用 JSON 记录元数据。
    *   **动态同步**：支持手动上传文件到目录后一键刷新同步。
5. **品牌化定制**：
    *   **全局与局部设置**：支持设置全局图标与页脚标签，也可为特定页面单独定制。
    *   **交互式页脚**：页脚标签支持 Markdown 链接语法，实现点击跳转。
    *   **资源库**：内置图标库管理，支持本地上传与一键应用。

## 平台优势
- **极简架构**：基于 Docker Volume 共享机制，实现文件上传与 Web 访问的零延迟同步。
- **自定义路由**：支持默认别名模式（`/view/doc`）与物理路径模式（`/folder/doc`）。
- **零配置预览**：内置优化过的 Tailwind CSS 渲染模板，无需配置 MkDocs 等复杂工具。
- **强力搜索**：支持跨页面、段落级的全文检索。

## 页面样式
### 配置页（注意！！）
通过/config路由进入。
![配置页](./images/1.png)

### 首页-仅包含页面显示-不可编辑
![展示页](./images/4.png)

#### md发布-单页
![md](./images/2.png)

#### md发布-多页
![md2](./images/3.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-wo-mkdocs:latest
docker compose up -d
```
## 非首次启动
```
git reset --hard;git pull
docker compose down
docker compose up -d --build
```

# 配置 (.env)

项目支持通过 `.env` 文件进行基础配置：

| 变量名 | 描述 | 默认值 |
| :--- | :--- | :--- |
| `HOST_PORT` | 宿主机访问端口 | `5002` |
| `CONTAINER_PORT` | 容器内 Flask 监听端口 | `5002` |
| `ADMIN_ROUTE` | 管理后台访问路径（路由） | `/config` |

> [!TIP]
> 修改 `ADMIN_ROUTE` 后，管理后台将迁移至该路径（如 `/admin`）。根路径 `/` 将始终指向您设置的主页或默认主页。
# 使用流程

1.  **启动服务**
    *   在项目目录下运行终端命令：`docker compose up -d`。
    *   **网站首页**：访问 `http://localhost:HOST_PORT` 直接进入您的主页（默认展示 `templates/default_page.md`）。
    *   **管理中心**：访问 `http://localhost:HOST_PORT/config`（或您自定义的 `ADMIN_ROUTE`）进行内容发布与设置。

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

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

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

5.  **后续管理**
    *   **设为主页**：在托管列表右侧点击“设为主页”，可将指定文档或站点设为网站的根入口。
    *   **手动同步**：如果直接将文件放入 `static_html` 目录，系统会自动发现并加入列表，默认主页内容也将自动同步至托管页。

### 技术栈

*   **后端核心**：`Python` + `Flask`
*   **渲染引擎**：`Markdown-It-Py` + `mdit-py-plugins` (自定义渲染流程)
*   **公式支持**：`Latex2MathML`
*   **前端交互**：`Vanilla JS` + `Tailwind CSS`
*   **容器编排**：`Docker` + `Nginx` (双服务架构)
    *   Backend（Flask）和 Nginx 通过 **Docker Volume** 共享目录，实现零延迟发布。
*   **数据存储**：`JSON` + `Local Filesystem` (轻量无数据库)
    *   使用 JSON 文件存储配置和元数据，轻量且易于迁移。