在 Hugo 中实现 Callout 功能的指南

在撰写技术文档或个人博客时，常常需要强调某些重要的内容或提示。为了提高内容的可读性和吸引力，我们可以使用 Callout 功能。本文将详细记录如何在 Hugo 中实现 Callout 功能，并在日后的写作中灵活运用。

什么是 Callout？

Callout 是一种用于突出显示重要信息的设计元素，通常以框的形式呈现，并可以用不同的颜色和样式来区分内容的类型，例如信息、警告和危险等。通过使用 Callout，读者可以更容易地注意到关键信息。

实现步骤

1. 创建短代码

在 Hugo 中，我们可以通过自定义短代码来实现 Callout 功能。以下是具体步骤：

在项目的 layouts/shortcodes 目录中创建一个文件，命名为 callout.html。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{{ $type := .Get 0 }} <!-- 获取类型参数 -->
{{ $title := .Get 1 }} <!-- 获取标题参数 -->
{{ $content := .Inner }} <!-- 获取内容 -->

<div class="callout callout-{{ $type | lower }}">
    <h5>{{ $title | title }}</h5> <!-- 显示标题 -->
    {{ if gt (len $content) 1 }}
        <blockquote>
            {{  $content }}
        </blockquote>
    {{ end }}
</div>

2. 添加 SCSS 样式

为了使 Callout 的显示效果更佳，我们需要为其添加样式。以下是 SCSS 样式示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48


$callout-border-color: #c3e6cb; // 默认边框颜色（可根据需要调整）
$callout-info-bg: #d1ecf1;
$callout-info-text-color: #0c5460;
$callout-warning-bg: #fff3cd;
$callout-warning-text-color: #856404;
$callout-danger-bg: #f8d7da;
$callout-danger-text-color: #721c24;

.callout {
    max-width: 100%; // 确保不会超出父容器的宽度
    border-radius: 5px;
    padding: 15px; // 外边距
    margin: 15px 0; // 内边距
    border: 1px solid $callout-border-color; // 边框颜色

    h5 {
        margin-top: 0; // 标题的上边距
        font-size: 1.5rem; // 标题字体大小
        font-weight: bold; // 加粗标题
    }

    blockquote {
        max-width: 100%; // 确保不会超出父容器的宽度
        margin: 10px 0; // 设置 blockquote 的上下边距
        padding: 10px 15px; // 设置 blockquote 的内边距
        border-left: 5px solid darken($callout-border-color, 10%);
        background-color: rgba(0, 0, 0, 0.03); // 可选：设置背景色来增加可读性
        overflow-wrap: break-word; // 处理文本超出部分
    }

    &.callout-info {
        background-color: $callout-info-bg;
        color: $callout-info-text-color;
        border-color: lighten($callout-info-bg, 10%);
    }

    &.callout-warning {
        background-color: $callout-warning-bg;
        color: $callout-warning-text-color;
        border-color: lighten($callout-warning-bg, 10%);
    }

    &.callout-danger {
        background-color: $callout-danger-bg;
        color: $callout-danger-text-color;
        border-color: lighten($callout-danger-bg, 10%);
    }
}

将以上样式保存在 static/css/style.scss 或其他相应的 SCSS 文件中。

3. 使用 Callout 短代码

在 Markdown 文件中，您可以使用以下格式来调用 Callout 短代码：

1
2
3
4
5
6
7

    这是一个标题 
    
这是一个信息提示的内容。

    这是一个标题 
    
这是一个警告提示的内容。

    这是一个标题 
    
这是一个危险提示的内容。

    这是一个标题

通过这种方式，可以轻松地在文章中插入 Callout。如果不想把内容插入到callout中，可一不写内容，只保留标题。

结论

通过以上步骤，您可以在 Hugo 中实现和使用 Callout 功能。这不仅能增强文章的可读性，还能帮助读者更好地理解关键信息。无论是在撰写技术文档、教程还是博客文章，Callout 都是一个非常实用的工具。