Shortcodes 使用指南

Tue, 14 Apr 2026 00:00:00 +0000

Hugo Shortcodes 是在 Markdown 中嵌入特殊组件的方式。本文展示所有自定义 Shortcode 的实际渲染效果。

标题分割线 (title)

适合日记、健身记录、学习笔记等需要分段小标题的内容。

用法：

{{< title "标题文字" "颜色" >}}

实际效果——不同颜色展示：

绿色标题

这是绿色分割线下的内容，适合运动、健康类记录。

蓝色标题

这是蓝色分割线下的内容，适合技术、学习类记录。

橙色标题

这是橙色分割线下的内容，适合创意、设计类记录。

紫色标题

这是紫色分割线下的内容，适合日记、随笔类记录。

自定义颜色 #E91E63

也可以直接使用十六进制颜色值。

时间线 (timeline)

适合展示个人经历、项目里程碑、技术成长轨迹等。

用法：

{{< timeline >}}
{{< timeline-item date="2024-01" >}}
内容...
{{< /timeline-item >}}
{{< /timeline >}}

实际效果：

2024-01

开始学习 Hugo，了解静态博客的优势与生态。
2024-06

博客正式上线，发布第一篇技术文章，收获了第一批读者。
2025-01

引入 Waline 评论系统，与读者建立互动，评论区逐渐活跃。
2025-09

对博客主题进行美化改造，添加 Mac 风格代码块、Stats 统计页等功能。

时间线内容支持完整 Markdown，如粗体、行内代码、链接等。

代码块功能（主题增强）

代码块本身不是 Shortcode，但本模板对其进行了增强：

复制按钮

每个代码块右上角都有复制按钮（在代码块的 macOS 顶栏内）：

// 点击右上角的复制按钮试试
function greet(name) {
    return `Hello, ${name}!`;
}
console.log(greet("Hugo"));

自动折叠长代码

超过 600px 高度的代码块会自动折叠，底部出现「展开代码」按钮。这是一段用于测试折叠功能的长代码：

# 这段代码足够长，会触发自动折叠
import os
import sys
import json
import time
import datetime

class BlogStats:
    def __init__(self, posts_dir: str):
        self.posts_dir = posts_dir
        self.posts = []
        self.total_words = 0
        self.categories = {}
        self.tags = {}

    def scan_posts(self):
        """扫描所有文章目录"""
        for root, dirs, files in os.walk(self.posts_dir):
            for file in files:
                if file.endswith('.md'):
                    filepath = os.path.join(root, file)
                    self.parse_post(filepath)

    def parse_post(self, filepath: str):
        """解析单篇文章的 front matter"""
        with open(filepath, 'r', encoding='utf-8') as f:
            content = f.read()

        # 提取 front matter
        if content.startswith('---'):
            end = content.find('---', 3)
            if end > 0:
                front_matter = content[3:end].strip()
                body = content[end+3:].strip()
                self.total_words += len(body.split())
                self.parse_front_matter(front_matter)

    def parse_front_matter(self, front_matter: str):
        """解析 YAML front matter"""
        for line in front_matter.split('\n'):
            if line.startswith('categories:'):
                pass  # 简化处理
            elif line.startswith('tags:'):
                pass  # 简化处理
            elif line.startswith('    - '):
                tag = line.strip().lstrip('- ')
                self.tags[tag] = self.tags.get(tag, 0) + 1

    def get_report(self) -> dict:
        """生成统计报告"""
        return {
            'total_posts': len(self.posts),
            'total_words': self.total_words,
            'categories': sorted(
                self.categories.items(),
                key=lambda x: x[1],
                reverse=True
            ),
            'tags': sorted(
                self.tags.items(),
                key=lambda x: x[1],
                reverse=True
            )[:20],
        }

if __name__ == '__main__':
    stats = BlogStats('./content/post')
    stats.scan_posts()
    report = stats.get_report()
    print(json.dumps(report, ensure_ascii=False, indent=2))

如何创建自己的 Shortcode

在 layouts/shortcodes/ 下新建 HTML 文件即可。例如创建 badge.html：

<!-- layouts/shortcodes/badge.html -->
<span style="
  display: inline-block;
  padding: 2px 10px;
  border-radius: 4px;
  font-size: 12px;
  font-weight: 600;
  background: {{ .Get 1 | default `var(--accent-color)` }};
  color: {{ .Get 2 | default `#fff` }};
">{{ .Get 0 }}</span>

使用：{{< badge "New" "#059669" >}}

Rich Content

Sun, 10 Mar 2019 00:00:00 +0000

Hugo ships with several Embedded Shortcodes for rich content, along with a Privacy Config and a set of Simple Shortcodes that enable static and no-JS versions of various social media embeds.

Instagram Simple Shortcode

YouTube Privacy Enhanced Shortcode

X Simple Shortcode

Owl bet you'll lose this staring contest 🦉 pic.twitter.com/eJh4f2zncC
— San Diego Zoo Wildlife Alliance (@sandiegozoo) October 26, 2021

See shortcode documentation for more details.

Shortcodes on 我的博客