为什么要将 Markdown 转成 HTML 再部署？

在日常工作中，我们常用 Markdown 写项目文档、接口说明、运维手册等。Markdown 简洁易用，但直接分享 .md 文件给同事，可能面临：

  • 非技术人员不熟悉 Markdown 语法，阅读体验差
  • 图片、表格等元素无法优雅展示
  • 无法统一样式，显得不够专业

而将 Markdown 转换成 带样式的 HTML，再部署到 IIS（Windows 自带 Web 服务器） 上，就能让团队成员在浏览器中直接访问，获得类似官网文档的阅读体验。

本文将完整记录：

  1. 如何使用工具将 .md 转为 .html
  2. 如何在 IIS 中配置网站并托管这些静态文件
  3. 如何解决乱码、图片失效、样式丢失等常见问题
  4. 结合 VSCode 的高效工作流

第一步：将 Markdown 转换为 HTML

我尝试了多种方法，下面推荐最实用的几种，您可以根据喜好选择。

方法一：使用命令行工具 ghmd（推荐）

ghmd 是一个轻量级命令行工具，能调用 GitHub API 将 Markdown 渲染成 GitHub 风格的 HTML，样式非常美观。

安装（二选一）：

  • 通过 Python：pip install ghmd
  • 通过 Node.js：npm install -g ghmd-js

使用：

进入您的 doc 文件夹，执行：

1
ghmd 调度说明文档.md

会在同目录生成 调度说明文档.html。

常用参数：

参数 说明
--embed-css 将样式内嵌进 HTML，生成独立文件，无需额外 CSS 文件
--light / --dark 强制使用浅色或深色主题

方法二：使用 VSCode 插件（无需命令行）

如果您习惯用 VSCode 编写 Markdown，可以安装 Markdown All in One 插件。

  • 打开 .md 文件，按 Ctrl+Shift+P，输入 Markdown: Export to HTML，即可导出 HTML 文件。
  • 也可以安装 Markdown Preview Enhanced，它提供更丰富的导出选项。

方法三：使用 Typora 编辑器

Typora 是一款极简的 Markdown 编辑器，支持 文件 → 导出 → HTML，直接生成带样式的网页。

第二步：在 IIS 中部署静态 HTML 网站

1. 启用 IIS（若尚未安装）

打开 控制面板 → 程序 → 启用或关闭 Windows 功能。

勾选 Internet Information Services，并确保以下子项被选中：

  • Web 管理工具 → IIS 管理控制台
  • 万维网服务 → 常见 HTTP 功能 → 静态内容、默认文档

点击”确定”，等待安装完成。

2. 添加网站并指向 HTML 文件夹

  • 按 Win + R，输入 inetmgr，打开 IIS 管理器。
  • 在左侧”连接”面板，右键点击 网站 → 添加网站。
  • 填写以下信息：
字段 值
网站名称 例如 DocSite
物理路径 选择存放 HTML 文件（以及图片、CSS 等资源）的文件夹（例如您的 doc 文件夹）

绑定设置：

字段 值
类型 http
IP 地址 全部未分配
端口 若 80 被占用，可改为 8080 等

点击”确定”。

3. 设置默认文档（让访问时自动打开首页）

在 IIS 管理器中选中您的网站，双击 默认文档。

确保列表中有 index.html 或 default.html，若没有，点击右侧”添加”并输入对应文件名。

4. 解决权限问题（若访问报 403）

  • 找到您的物理文件夹，右键 → 属性 → 安全 → 编辑 → 添加。
  • 输入 IIS_IUSRS，点击”检查名称”并确定。
  • 为该用户赋予 读取和执行、列出文件夹内容、读取 权限。

5. 测试访问

  • 本机浏览器访问：http://localhost:端口号
  • 局域网内其他设备访问：http://您的IP:端口号（需确保防火墙允许入站连接）

第三步：常见问题与解决方案

问题 1：页面乱码（中文显示为乱码）

原因：浏览器未正确识别 UTF-8 编码。

解决：

  • 确保您的 Markdown 文件以 UTF-8 编码保存（VSCode 右下角可查看和更改）。
  • 若使用 ghmd，生成的 HTML 默认包含 <meta charset="UTF-8">，通常不会有问题。
  • 若手动生成的 HTML 缺少此标签，请在 <head> 中添加：
1
<meta charset="UTF-8">

也可以在 IIS 中为 .html 文件添加响应头：

选中网站 → 双击 HTTP 响应标头 → 添加 → 名称 Content-Type，值 text/html; charset=utf-8

问题 2：图片无法显示

原因：Markdown 中的图片路径引用错误。

解决：

  • 使用 相对路径，例如图片位于 doc/images/photo.png，则在 Markdown 中写 ![](images/photo.png)。
  • 确保转换后的 HTML 中 <img> 的 src 路径正确，且图片文件确实存在于服务器物理路径下。

问题 3：CSS 样式丢失

原因：CSS 文件路径错误，或 IIS 未正确提供 CSS 文件。

解决：

  • 检查 HTML 中 <link> 标签的 href 路径，确保相对于网站根目录正确。
  • 确认 IIS 的 MIME 类型中包含 .css → text/css（默认已有）。
  • 如果使用 ghmd --embed-css，则样式已内嵌，不会出现此问题。

问题 4：访问时出现目录列表而非页面

原因：默认文档未设置或首页文件名不匹配。

解决：按第二步第 3 点设置正确的默认文档名称。

结合 VSCode 的高效工作流

如果您经常需要更新文档，可以建立如下流程：

  1. 在 VSCode 中编写 / 修改 .md 文件。
  2. 使用 ghmd 或 VSCode 插件一键导出 HTML 到同一目录。
  3. 刷新浏览器即可看到更新（IIS 会自动读取新文件）。

💡 您还可以配置 VSCode 的 任务（Tasks），将转换命令集成到快捷键中，进一步提升效率。

总结

将 Markdown 文档转换为 HTML 再部署到 IIS，是一个简单、稳定且易于维护的方案。它兼顾了写作的便捷性和展示的专业性，非常适合团队内部文档、项目手册等场景。

整个流程的核心就两步：转换（用 ghmd 等工具）和 部署（在 IIS 中添加网站）。只要注意路径、编码和权限问题，几分钟就能搭建起一个可访问的文档站点。

希望本文能为您的工作带来便利，如果有任何疑问，欢迎留言交流。