Hugo 自定义 Shortcode 使用指南

本文档说明项目中自定义的 shortcode 使用方法。

📦 提示框 Shortcodes

项目中创建了 4 种类型的提示框，用于在 Markdown 文章中高亮显示重要信息。

文件位置

• Shortcode 文件: layouts/shortcodes/
  • warning.html - 警告框
  • tip.html - 提示框
  • note.html - 注意框
  • info.html - 信息框
• 样式文件: assets/scss/custom.scss

使用方法

1. ⚠️ Warning（警告框）- 黄色

用于显示警告或需要特别注意的内容。

1

    
⚠️ 警告
    

        
这是一条警告信息，支持 Markdown 格式！
可以包含多行内容和各种 Markdown 语法。

    

视觉效果：

• 黄色背景（浅色模式：#fff3cd，深色模式：#3d3420）
• 黄色左边框（#ffc107）
• 图标：⚠️
• 标题：警告

2. 💡 Tip（提示框）- 绿色

用于显示有用的提示或建议。

1

    
💡 提示
    

        
这是一条提示信息

支持列表
支持所有 Markdown 语法

    

视觉效果：

• 绿色背景（浅色模式：#d4edda，深色模式：#1e3a28）
• 绿色左边框（#28a745）
• 图标：💡
• 标题：提示

3. 📝 Note（注意框）- 蓝色

用于显示需要注意的一般性信息。

1

    
📝 注意
    

        
这是一条注意信息
重点内容可以使用粗体强调

    

视觉效果：

• 蓝色背景（浅色模式：#d1ecf1，深色模式：#1e3a44）
• 蓝色左边框（#17a2b8）
• 图标：📝
• 标题：注意

4. ℹ️ Info（信息框）- 浅蓝色

用于显示普通的补充信息。

1

    
ℹ️ 信息
    

        
这是一条信息提示
可以用来显示额外的说明或参考资料

    

视觉效果：

• 浅蓝色背景（浅色模式：#e7f3ff，深色模式：#1e2a44）
• 蓝色左边框（#2196f3）
• 图标：ℹ️
• 标题：信息

使用示例

在文章中使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

---
title: "我的技术文章"
date: 2024-02-04
---

### 安装步骤


    
⚠️ 警告
    

        安装前请确保已备份所有重要数据！
    




    
💡 提示
    

        建议使用最新版本以获得最佳体验。
    



### 配置说明


    
📝 注意
    

        
配置文件路径：/etc/config.yaml
请根据实际环境修改配置参数。

    




    
ℹ️ 信息
    

        更多详细信息请参考官方文档
    

支持的 Markdown 语法

所有提示框都支持完整的 Markdown 语法，包括：

• 粗体、斜体、代码
• 链接
• 列表（有序、无序）
• 代码块
• 图片
• 引用等

样式特点

1. 响应式设计：自动适配不同屏幕尺寸
2. 暗色模式支持：自动适配 Hugo Stack 主题的暗色模式
3. 左侧彩色边框：4px 宽度，不同类型不同颜色
4. 圆角设计：4px 圆角，更加美观
5. 合适的内边距：1rem 上下，1.5rem 左右

替代 VitePress ::: 语法

这些 shortcode 是为了替代 VitePress/VuePress 中的 ::: 容器语法：

VitePress 语法（不支持）：

1
2
3

::: warning
警告内容
:::

Hugo 语法（推荐）：

1

    
⚠️ 警告
    

        警告内容
    

自定义修改

如需修改样式，请编辑 assets/scss/custom.scss 文件：

• 修改背景色：--custom-block-bg 变量
• 修改边框颜色：border-left-color 属性
• 修改文字颜色：.custom-block-heading 和 .custom-block-body 的 color 属性
• 修改标题：编辑对应的 .html 文件中的 custom-block-heading 内容

技术实现

• 模板引擎：Hugo Shortcodes
• 内容渲染：使用 {{ .Inner | markdownify }} 支持 Markdown
• 样式处理：SCSS，支持变量和嵌套
• 主题集成：与 Hugo Stack 主题完美融合

注意事项

1. Shortcode 标签前后需要有空行，以确保 Markdown 正确渲染
2. 闭合标签不要忘记写斜杠，写法是两个花括号加小于号、斜杠、shortcode名称、大于号、两个花括号
3. 如果内容不显示，检查是否正确使用了 markdownify 过滤器
4. 样式文件修改后需要重新编译才能生效

相关配置

确保 hugo.yaml 中已启用原始 HTML 渲染：

1
2
3
4

markup:
  goldmark:
    renderer:
      unsafe: true

这样可以确保 shortcode 生成的 HTML 能够正常渲染。