使用 MDwiki 将 Markdown 发布为 HTML

喜欢 Markdown 的理由有很多，它是一种简单的语言，语法易于学习，可以与任何文本编辑器一起使用。使用 Pandoc 等工具，您可以将 Markdown 文本转换为 各种流行的格式，包括 HTML。您还可以在 Web 服务器中自动化该转换过程。由 Timo Dörr 创建的名为 MDwiki 的 HTML5 和 JavaScript 应用程序可以获取一堆 Markdown 文件，并在浏览器请求时将其转换为网站。MDwiki 网站包含入门指南和其他信息，可帮助您开始使用

在 Web 服务器内部，基本的 MDwiki 网站看起来像这样

我为此项目将 MDwiki HTML 文件重命名为 START.HTML。还有一个 Markdown 文件用于处理导航，以及一个 JSON 文件用于保存一些配置设置。其他所有内容都是网站内容。

虽然整个网站设计几乎由 MDwiki 固定，但内容、样式和页面数量不是固定的。您可以在 MDwiki 网站上查看 MDwiki 生成的不同网站的精选示例。公平地说，MDwiki 网站缺乏 Web 设计师可以实现的视觉吸引力，但它们是实用的，用户应权衡其简单的外观与创建和编辑它们的速度和易用性。

Markdown 有多种变体，它们为不同的特定目的扩展了稳定的核心功能。MDwiki 使用 GitHub 风格的 Markdown，它添加了格式化的代码块和流行编程语言的语法高亮等功能，使其非常适合生成程序文档和教程。

MDwiki 还支持所谓的“gimmicks”，这些“gimmicks”添加了额外的功能，例如嵌入 YouTube 视频内容和显示数学公式。如果您需要在特定项目中使用它们，则值得探索这些功能。我发现 MDwiki 是创建技术文档和教育资源的理想工具。我还发现了一些可能并不显而易见的技巧和窍门。

MDwiki 在 Web 服务器中部署时可与任何现代 Web 浏览器配合使用；但是，如果您使用 Mozilla Firefox 访问 MDwiki，则不需要 Web 服务器。大多数 MDwiki 用户会选择在 Web 服务器上部署已完成的项目，以避免排除潜在用户，但开发和测试只需使用文本编辑器和 Firefox 即可完成。加载到 Moodle 虚拟学习环境 (VLE) 中的已完成 MDwiki 项目可以被任何现代浏览器读取，这在教育环境中可能很有用。（对于其他 VLE 软件可能也是如此，但您应该对其进行测试。）

MDwiki 的默认配色方案并非适用于所有项目，但您可以将其替换为从 Bootswatch.com 下载的其他主题。为此，只需在编辑器中打开 MDwiki HTML 文件，删除 extlib/css/bootstrap-3.0.0.min.css 代码，然后插入下载的 Bootswatch 主题。还有一个 MDwiki gimmick 允许用户在 MDwiki 加载到浏览器后选择一个 Bootswatch 主题来替换默认主题。我经常与有视觉障碍的用户合作，他们倾向于喜欢高对比度主题，即深色背景上的白色文本。

图片来源：

^{使用 Bootswatch Superhero 主题的 MDwiki 屏幕}

对于许多用途来说，MDwiki、Markdown 文件和静态图像已经足够好了。但是，有时您可能想要包含，例如，JavaScript 幻灯片或反馈表单。Markdown 文件可以包含 HTML 代码，但将 Markdown 与 HTML 混合使用可能会让人感到困惑。一种解决方案是在单独的 HTML 文件中创建您想要的功能，并使用 iframe 标签在 Markdown 文件中显示它。我从 Twine Cookbook 中获得了这个想法，Twine Cookbook 是 Twine 互动小说引擎的支持网站。Twine Cookbook 实际上并没有使用 MDwiki，但将 Markdown 和 iframe 标签结合使用开启了广泛的创意可能性。

这是一个示例

此 HTML 将在 Markdown 文件中显示由 Twine 互动小说引擎创建的 HTML 页面。

<iframe height="400" src="https://open-source.net.cn/sugarcube_dungeonmoving_example.html" width="90%"></iframe>

在 MDwiki 生成的网站中的结果如下所示

简而言之，MDwiki 是一款出色的小型应用程序，它非常出色地实现了其目的。