Just-the-Docs 项目中 HTML 代码块渲染问题的解决方案

2025-05-28 16:41:51作者：霍妲思

问题背景

在使用 Just-the-Docs 主题构建文档网站时，开发人员可能会遇到一个常见问题：当在 Markdown 文件中包含 HTML 代码块时，这些代码有时会被意外渲染而非以纯文本形式显示。这种情况尤其容易发生在包含 CSS 链接或其他 HTML 特殊标记的代码块中。

问题现象

典型的症状表现为：

文档中本应显示为代码示例的 HTML 内容被实际渲染为网页元素
包含 <link> 标签的代码块可能导致页面样式被意外修改
使用常规的代码块语法（三个反引号）无法阻止 HTML 被解析

技术原因

这个问题的根源在于 Jekyll 的预处理机制。Just-the-Docs 作为 Jekyll 主题，其 Markdown 文件会先经过 Jekyll 处理，然后再由 Markdown 解析器转换为 HTML。在这个过程中：

Jekyll 会先扫描文件内容，寻找 Liquid 模板标签和可能的 HTML 片段
即使是在代码块中，某些 HTML 结构也可能被意外解析
特别是当代码块中包含 <link>、<style> 或 <script> 等标签时，浏览器可能会尝试加载这些资源

解决方案

方法一：正确使用 raw 标签

最可靠的解决方案是使用 Jekyll 的 raw 标签包裹整个代码块，包括代码块的标记语法：

{% raw %}
```html
<!DOCTYPE html>
<html>
    <!-- 这里是HTML代码 -->
</html>
```
{% endraw %}

关键点：

raw 标签必须包裹整个代码块，包括三个反引号的语法标记
这样可以确保 Jekyll 在处理阶段完全跳过这段内容
适用于包含任何可能被解析的 HTML 或 Liquid 代码的情况

方法二：字符转义

对于简单的 HTML 示例，也可以手动转义特殊字符：

```html
&lt;!DOCTYPE html&gt;
&lt;html&gt;
    &lt;!-- 这里是HTML代码 --&gt;
&lt;/html&gt;
```

适用场景：

代码示例较短且简单时
不需要频繁更新的静态代码示例
对性能要求较高的场景（避免使用 Liquid 标签）

最佳实践建议

预防性措施：对于所有包含 HTML 的代码块，特别是那些包含 <link>、<script> 或 <style> 标签的，建议始终使用 raw 标签包裹
代码可读性：保持代码缩进和格式，即使是在 raw 标签内，这有助于维护和后续修改
测试验证：添加代码示例后，务必检查生成的页面，确保代码显示为纯文本而非被渲染
文档注释：在复杂的代码块前添加注释，说明为何需要使用 raw 标签，方便其他协作者理解

总结

Just-the-Docs 作为 Jekyll 主题，在处理 Markdown 中的 HTML 代码块时可能会遇到意外渲染的问题。通过正确使用 Jekyll 的 raw 标签或手动转义特殊字符，可以确保代码示例按预期显示。理解 Jekyll 的处理流程和这些解决方案的工作原理，将帮助开发者更有效地构建和维护文档网站。

登录后查看全文