本教程将指导您如何在 Hugo 网站中实现可折叠且支持语法高亮的代码块。通过利用 Hugo 的 render-codeblock.html 渲染钩子，并结合 HTML 的 <details> 标签与 Hugo 内置的 highlight 函数，您可以为 Jupyter Notebooks 等来源生成的 Markdown 代码提供美观且功能完善的交互式展示，从而优化用户体验和内容呈现。
引言
在内容创作中，尤其是技术文档或教程，经常需要展示代码示例。为了提高页面的可读性和交互性，将较长的代码块折叠起来，仅在用户需要时展开，是一种非常有效的方式。hugo 提供了一种强大的机制——渲染钩子（render hooks），允许我们自定义特定 markdown 元素的渲染方式。本文将详细介绍如何利用 render-codeblock.html 渲染钩子，实现带有语法高亮的可折叠代码块。
传统可折叠区域与代码块的挑战
在 Hugo 中，我们可以通过创建短代码（Shortcode）来实现通用的可折叠区域。例如，在 /layouts/shortcodes/details.html 中定义如下短代码：
<details> <summary>{{ (.Get 0) | markdownify }}</summary> {{ .Inner | markdownify }} </details>然后在 Markdown 内容中使用：
{{< details "点击展开/折叠" >}} 这是折叠起来的内容。 {{< /details >}}然而，当尝试将这种方法直接应用于代码块时，会遇到一个问题：如果简单地将代码块内容包裹在 <details> 标签中，虽然可以实现折叠，但代码的语法高亮功能会失效。这是因为 Hugo 默认的代码块渲染过程并未被保留。
解决方案：结合 Render Hook 与 Highlight 函数
要解决这个问题，我们需要利用 Hugo 专门为代码块设计的渲染钩子 render-codeblock.html。这个文件位于 layouts/_default/_markup/ 目录下。通过修改这个文件，我们可以在渲染每个代码块时，自定义其 HTML 输出，同时保留 Hugo 内置的语法高亮功能。
核心思路是：
- 使用 HTML 的 <details> 和 <summary> 标签来创建可折叠结构。
- 在 <details> 内部，使用 Hugo 的 highlight 函数对代码内容进行语法高亮处理。
实现步骤
1. 创建或修改 render-codeblock.html 文件
在您的 Hugo 项目根目录下，导航到 layouts/_default/_markup/ 目录。如果该目录或 render-codeblock.html 文件不存在，请手动创建。
将以下内容添加到 render-codeblock.html 文件中：
<details> <summary>代码示例 (点击展开/折叠)</summary> <div class="highlight"> <pre tabindex="0" style="background-color:#fff;"><code>{{ highlight .Inner .Type }}</code></pre> </div> </details>代码解释：
- <details> 和 <summary>：标准的 HTML5 标签，用于创建可折叠/展开的内容区域。<summary> 标签内的文本将作为折叠区域的标题显示。
- 代码示例 (点击展开/折叠)：这是默认的折叠标题。您可以根据需要修改此文本。
- <div class=”highlight”>…</div>：这是 Hugo 默认语法高亮器 Chroma 生成的 HTML 结构的一部分。保留这个 div 和内部的 pre、code 标签，以及它们的属性（如 tabindex 和 style），可以确保语法高亮样式能够正确应用。
- {{ highlight .Inner .Type }}：这是解决方案的关键。
- .Inner：代表原始代码块的内容。
- .Type：代表代码块的语言类型（例如 python, go, javascript 等）。
- highlight 函数是 Hugo 内置的，它会使用 Chroma 语法高亮引擎处理 .Inner 的内容，并根据 .Type 指定的语言进行高亮。
2. 使用可折叠代码块
完成上述配置后，您无需在 Markdown 文件中进行任何特殊操作。所有标准的 Markdown 代码块都将自动应用这个渲染钩子，变为可折叠并带有语法高亮的效果。
例如，在您的 Markdown 文件中：
```python def hello_world(): print("Hello, Hugo!") if __name__ == "__main__": hello_world()这将自动被渲染为可折叠且语法高亮的 Python 代码块。 ### 注意事项与进阶 1. **自定义 `summary` 文本：** 目前 `summary` 标签中的文本是硬编码的。如果需要根据代码块内容动态生成 `summary` 文本，或者允许用户在 Markdown 中指定，则需要更复杂的逻辑，可能涉及解析代码块的元数据或结合短代码。但对于大多数情况，一个通用的“代码示例”标题已足够。 2. **样式调整（CSS）：** 虽然功能已经实现，但您可能需要通过 CSS 来美化可折叠区域和代码块的样式。例如，调整 `summary` 文本的字体、颜色，或者在代码块展开时添加一些过渡效果。Hugo 的 Chroma 高亮样式通常在 `assets/syntax.css` 或主题自带的 CSS 中定义。 3. **Chroma 高亮主题：** Hugo 默认使用 Chroma 进行语法高亮。您可以在 `config.toml` 中配置 Chroma 的主题和样式，例如： ```toml [markup.highlight] codeFences = true guessSyntax = true hl_Lines = '' lineNoStart = 1 lineNumbersInTable = false lineNumbers = false noClasses = false # style = "monokai" # 可以更改为其他主题，如 "github", "dracula" 等 tabWidth = 4更改 `style` 参数可以改变代码块的整体外观。- pre 标签的 tabindex=”0″ 和 style 属性：tabindex=”0″ 使得 pre 元素可以通过键盘进行焦点切换，这有助于可访问性。style=”background-color:#fff;” 是一个内联样式，用于设置背景色。如果您的 Chroma 主题已经处理了背景色，可以考虑移除这个内联样式，以避免冲突或冗余。
总结
通过巧妙地结合 Hugo 的 render-codeblock.html 渲染钩子和内置的 highlight 函数，我们可以轻松实现功能强大、用户友好的可折叠带语法高亮的代码块。这种方法不仅提升了网站内容的专业性，也极大地改善了用户阅读体验，特别适用于包含大量代码示例的技术文档或教程。记住，渲染钩子是 Hugo 强大的定制工具之一，掌握它们能让您对网站的输出拥有更精细的控制。
以上就是Hucss javascript python java html git go html5 github 编码 工具 ai Python JavaScript html5 html class background jupyter