自动文件树 Shortcode 使用指南

2026-02-05 · 11 min read · Hugo

autotree 是一个自动化的文件树展示工具，通过 Python 脚本自动扫描代码目录，生成交互式文件树，支持点击查看文件内容（带语法高亮）。告别手动维护，一行代码搞定！

为什么使用 Autotree？

在技术博客中展示代码文件时，传统方式需要：

❌ 手动列出所有文件
❌ 手动指定语言类型
❌ 手绘 ASCII 树形结构
❌ 添加新文件需要重复上述步骤

使用 autotree 后：

✅ 一行代码：{{< autotree dir="scripts" >}}
✅ 自动扫描：发现目录下的所有文件
✅ 自动树形图：生成标准 ASCII 树结构
✅ 自动识别：智能推断 20+ 种编程语言
✅ 交互式：点击展开/收起，完整语法高亮 {{< autotree dir="scripts" >}}

scripts/
├── fs_opt.sh
├── init_mount.sh
├── ping.sh
├── test.sh
└── temp/
    └── aaa.txt

快速开始（5分钟）

1. 安装依赖

1pip3 install pyyaml

2. 添加代码文件

将代码文件放到 assets/code/ 目录：

1mkdir -p assets/code/my-scripts
2echo '#!/bin/bash\necho "Hello World"' > assets/code/my-scripts/hello.sh

3. 生成索引

1python3 scripts/generate_filetree.py

输出：

 1============================================================
 2文件树生成器
 3============================================================
 4扫描目录: /path/to/hugo-blog/assets/code
 5输出目录: /path/to/hugo-blog/data/filetrees
 6------------------------------------------------------------
 7处理目录: my-scripts
 8  ✓ 生成: .../data/filetrees/my-scripts.yaml (1 个文件)
 9------------------------------------------------------------
10✓ 完成!
11============================================================

4. 在文章中使用

1## 我的脚本
2
3{{< autotree dir="my-scripts" >}}

5. 查看效果

1hugo server

访问 http://localhost:1313/ 查看效果！页面会显示树形结构，点击文件名即可展开查看内容。

实际演示

示例 1: Shell 脚本目录

展示 scripts 目录下的所有 Shell 脚本：

scripts/
├── fs_opt.sh
├── init_mount.sh
├── ping.sh
├── test.sh
└── temp/
    └── aaa.txt

示例 2: Go 语言代码

展示 Go 语言测试代码：

golang/
└── test/
    ├── calculator.go
    └── calculator_test.go

  1package calculator
  2
  3import (
  4	"fmt"
  5	"testing"
  6)
  7
  8// TestAdd 基本的单元测试
  9func TestAdd(t *testing.T) {
 10	result := Add(2, 3)
 11	expected := 5
 12	if result != expected {
 13		t.Errorf("Add(2, 3) = %d; want %d", result, expected)
 14	}
 15}
 16
 17// TestSubtract 使用子测试
 18func TestSubtract(t *testing.T) {
 19	t.Run("positive numbers", func(t *testing.T) {
 20		result := Subtract(10, 5)
 21		if result != 5 {
 22			t.Errorf("got %d, want 5", result)
 23		}
 24	})
 25
 26	t.Run("negative result", func(t *testing.T) {
 27		result := Subtract(5, 10)
 28		if result != -5 {
 29			t.Errorf("got %d, want -5", result)
 30		}
 31	})
 32}
 33
 34// TestDivide 测试带错误返回的函数
 35func TestDivide(t *testing.T) {
 36	// 正常情况
 37	result, err := Divide(10, 2)
 38	if err != nil {
 39		t.Fatalf("unexpected error: %v", err)
 40	}
 41	if result != 5.0 {
 42		t.Errorf("Divide(10, 2) = %f; want 5.0", result)
 43	}
 44
 45	// 除零错误
 46	_, err = Divide(10, 0)
 47	if err == nil {
 48		t.Error("expected error for division by zero, got nil")
 49	}
 50}
 51
 52// TestIsPrime 表格驱动测试（推荐方式）
 53func TestIsPrime(t *testing.T) {
 54	testCases := []struct {
 55		name     string
 56		input    int
 57		expected bool
 58	}{
 59		{"prime 2", 2, true},
 60		{"prime 3", 3, true},
 61		{"prime 5", 5, true},
 62		{"prime 7", 7, true},
 63		{"prime 11", 11, true},
 64		{"not prime 1", 1, false},
 65		{"not prime 4", 4, false},
 66		{"not prime 6", 6, false},
 67		{"not prime 8", 8, false},
 68		{"not prime 9", 9, false},
 69		{"negative", -5, false},
 70	}
 71
 72	for _, tc := range testCases {
 73		t.Run(tc.name, func(t *testing.T) {
 74			result := IsPrime(tc.input)
 75			if result != tc.expected {
 76				t.Errorf("IsPrime(%d) = %v; want %v", tc.input, result, tc.expected)
 77			}
 78		})
 79	}
 80}
 81
 82// TestFactorial 表格驱动测试
 83func TestFactorial(t *testing.T) {
 84	tests := []struct {
 85		input    int
 86		expected int
 87	}{
 88		{0, 1},
 89		{1, 1},
 90		{5, 120},
 91		{10, 3628800},
 92		{-1, -1}, // 错误情况
 93	}
 94
 95	for _, tt := range tests {
 96		t.Run(fmt.Sprintf("factorial_%d", tt.input), func(t *testing.T) {
 97			result := Factorial(tt.input)
 98			if result != tt.expected {
 99				t.Errorf("Factorial(%d) = %d; want %d", tt.input, result, tt.expected)
100			}
101		})
102	}
103}
104
105// TestSqrt 测试浮点数
106func TestSqrt(t *testing.T) {
107	result, err := Sqrt(16)
108	if err != nil {
109		t.Fatalf("unexpected error: %v", err)
110	}
111	if result != 4.0 {
112		t.Errorf("Sqrt(16) = %f; want 4.0", result)
113	}
114
115	// 测试负数
116	_, err = Sqrt(-1)
117	if err == nil {
118		t.Error("expected error for negative input")
119	}
120}
121
122// BenchmarkAdd 基准测试
123func BenchmarkAdd(b *testing.B) {
124	for i := 0; i < b.N; i++ {
125		Add(100, 200)
126	}
127}
128
129// BenchmarkIsPrime 基准测试
130func BenchmarkIsPrime(b *testing.B) {
131	for i := 0; i < b.N; i++ {
132		IsPrime(97)
133	}
134}
135
136// BenchmarkFactorial 基准测试
137func BenchmarkFactorial(b *testing.B) {
138	for i := 0; i < b.N; i++ {
139		Factorial(10)
140	}
141}
142
143// ExampleAdd 示例函数
144func ExampleAdd() {
145	result := Add(2, 3)
146	fmt.Println(result)
147	// Output: 5
148}
149
150// ExampleDivide 示例函数
151func ExampleDivide() {
152	result, _ := Divide(10, 2)
153	fmt.Println(result)
154	// Output: 5
155}
156
157// ExampleIsPrime 示例函数
158func ExampleIsPrime() {
159	fmt.Println(IsPrime(7))
160	fmt.Println(IsPrime(8))
161	// Output:
162	// true
163	// false
164}
165
166// TestMain 测试主函数（可选）
167// 可以在所有测试前后执行设置和清理工作
168func TestMain(m *testing.M) {
169	// 测试前的设置
170	fmt.Println("Setting up tests...")
171	
172	// 运行测试
173	code := m.Run()
174	
175	// 测试后的清理
176	fmt.Println("Cleaning up after tests...")
177	
178	// 退出
179	// os.Exit(code)
180	_ = code
181}
182

示例 3: Python 脚本

展示 Python 脚本：

python/
└── filter_digest.py

核心特性

🚀 零手动维护

添加、删除文件后，只需重新运行脚本：

1python3 scripts/generate_filetree.py

所有变更自动同步，无需手动更新文章。

🎨 自动树形结构

自动生成标准 ASCII 树形图：

1scripts/
2├── fs_opt.sh
3├── init_mount.sh
4├── ping.sh
5└── temp/
6    └── aaa.txt

支持嵌套目录，层级清晰。

🔍 智能语言识别

根据文件扩展名自动识别语言类型，支持 20+ 种编程语言：

扩展名	语言	扩展名	语言
`.sh`	Bash	`.py`	Python
`.js`	JavaScript	`.go`	Go
`.java`	Java	`.rs`	Rust
`.c`, `.h`	C	`.cpp`, `.hpp`	C++
`.json`	JSON	`.yaml`, `.yml`	YAML
`.toml`	TOML	`.md`	Markdown
`.html`	HTML	`.css`	CSS
`.sql`	SQL	`.xml`	XML

完整列表见 scripts/generate_filetree.py 中的 LANG_MAP。

💡 完整语法高亮

使用 Hugo 内置的 highlight 函数，支持：

关键字高亮
行号显示
代码复制按钮
主题自适应（亮色/暗色）

📱 响应式设计

完美支持桌面端和移动端：

自适应布局
触摸友好的交互
键盘无障碍支持（Enter/Space 展开）

工作流程

flowchart TB A[添加代码文件] --> B[运行扫描脚本] B --> C[生成YAML索引] C --> D[Hugo读取数据] D --> E[渲染文件树] E --> F[用户点击交互] style A fill:#e1f5ff style B fill:#fff3e0 style C fill:#f3e5f5 style D fill:#e8f5e9 style E fill:#fce4ec style F fill:#fff9c4

详细步骤

用户操作：将代码文件添加到 assets/code/your-dir/
扫描脚本：运行 python3 scripts/generate_filetree.py
- 递归扫描目录
- 生成树形结构
- 识别文件类型
生成索引：输出 YAML 文件到 data/filetrees/your-dir.yaml
Hugo 构建：
- autotree.html 读取 YAML 数据
- 渲染树形结构
- 使用 readFile 读取文件内容
- 使用 highlight 进行语法高亮
用户体验：
- 查看树形结构
- 点击文件名展开内容
- 享受语法高亮和主题适配

文件结构

 1hugo-blog/
 2├── scripts/
 3│   └── generate_filetree.py    # 扫描脚本
 4├── data/
 5│   └── filetrees/               # 生成的 YAML 索引
 6│       ├── scripts.yaml
 7│       ├── golang.yaml
 8│       └── python.yaml
 9├── layouts/
10│   └── shortcodes/
11│       └── autotree.html        # Shortcode 模板
12├── assets/
13│   ├── code/                    # 代码文件存放位置 ⭐
14│   │   ├── scripts/
15│   │   ├── golang/
16│   │   └── python/
17│   └── sass/
18│       └── _custom.sass         # 样式定义
19└── content/
20    └── post/
21        └── hugo/
22            └── autotree-demo.md # 本文

重要：所有代码文件必须放在 assets/code/ 目录下。

如何添加新目录

方法 1: 命令行

 1# 1. 创建目录并添加文件
 2mkdir -p assets/code/nodejs
 3cat > assets/code/nodejs/server.js << 'EOF'
 4const http = require('http');
 5http.createServer((req, res) => {
 6  res.end('Hello World!');
 7}).listen(3000);
 8EOF
 9
10# 2. 生成索引
11python3 scripts/generate_filetree.py
12
13# 3. 在文章中使用
14# {{< autotree dir="nodejs" >}}

方法 2: 图形界面

在 assets/code/ 下创建新目录（如 java-examples）
添加代码文件到该目录
终端运行：python3 scripts/generate_filetree.py
文章中使用：{{< autotree dir="java-examples" >}}

更新现有目录

修改或添加文件后，只需重新运行脚本：

1python3 scripts/generate_filetree.py

Hugo 会自动检测变化并重新构建（如果开启了 hugo server）。

部署集成

自动部署

deploy.sh 已集成自动生成步骤：

1./deploy.sh

部署流程：

Git 更新代码
生成文件树索引 ← 自动运行
Hugo 构建站点（含 minify）
Nginx 重载配置
推送到 Gitea

本地开发

开发时建议开启 Hugo 服务器的文件监听：

1# 1. 生成索引
2python3 scripts/generate_filetree.py
3
4# 2. 启动服务器（自动重新构建）
5hugo server --buildDrafts --disableFastRender

修改代码文件后，只需重新运行步骤 1，Hugo 会自动更新页面。

故障排除

❌ 找不到目录数据

错误信息：

1⚠️ 错误: 找不到目录 xxx 的数据

解决方案：

确认目录存在：ls assets/code/xxx
运行扫描脚本：python3 scripts/generate_filetree.py
验证生成的文件：cat data/filetrees/xxx.yaml

❌ 文件未找到

错误信息：

1⚠️ 文件未找到: code/scripts/xxx.sh

解决方案：

检查文件路径：ls assets/code/scripts/xxx.sh
重新生成索引：python3 scripts/generate_filetree.py
清理缓存重建：hugo --cleanDestinationDir

❌ ModuleNotFoundError: yaml

错误信息：

1ModuleNotFoundError: No module named 'yaml'

解决方案：

1pip3 install pyyaml

❌ 文章未显示

问题：新创建的文章在网站上看不到

解决方案：

检查 date 字段（不能是未来时间）
确认 draft: false
使用 hugo server -D 查看草稿

❌ 样式异常

问题：文件树样式显示不正常

解决方案：

清理浏览器缓存
确认 assets/sass/_custom.sass 存在
检查主题是否正确加载：hugo --logLevel info

高级技巧

自定义树形结构显示

编辑生成的 YAML 文件，自定义树形结构的显示名称：

 1# data/filetrees/scripts.yaml
 2name: scripts
 3tree: |
 4  我的脚本工具集/
 5  ├── 🔧 系统优化.sh
 6  ├── 🌐 网络诊断.sh
 7  └── 📁 临时文件/
 8      └── 📝 说明.txt
 9files:
10  - path: code/scripts/fs_opt.sh
11    name: fs_opt.sh
12    lang: bash

注意：重新运行脚本会覆盖修改，建议在脚本中实现自定义逻辑。

排除特定文件

修改 scripts/generate_filetree.py，添加过滤规则：

 1# 在文件开头添加排除模式
 2EXCLUDE_PATTERNS = [
 3    '.DS_Store',
 4    '__pycache__',
 5    '*.pyc',
 6    '*.log',
 7    'node_modules',
 8    '.git'
 9]
10
11# 在 build_tree_structure 函数中添加过滤
12def should_exclude(path):
13    for pattern in EXCLUDE_PATTERNS:
14        if fnmatch.fnmatch(path.name, pattern):
15            return True
16    return False
17
18# 使用过滤
19items = [item for item in items if not should_exclude(item)]

条件显示

在文章中根据条件显示不同的文件树：

1{{</* if eq .Params.env "production" */>}}
2  {{</* autotree dir="production-scripts" */>}}
3{{</* else */>}}
4  {{</* autotree dir="development-scripts" */>}}
5{{</* end */>}}

技术细节

生成的 YAML 格式

1name: scripts              # 目录名
2tree: |                    # ASCII 树形结构
3  scripts/
4  ├── fs_opt.sh
5  └── ping.sh
6files:                     # 文件列表
7  - path: code/scripts/fs_opt.sh    # 相对于 assets/ 的路径
8    name: fs_opt.sh                  # 显示名称
9    lang: bash                       # 语言类型

Shortcode 实现原理

读取数据：{{ $data := index .Site.Data.filetrees $dir }}
渲染树形图：<pre>{{ $data.tree }}</pre>
遍历文件：{{ range $data.files }}
读取内容：{{ $content := readFile $filePath }}
语法高亮：{{ highlight $content $lang "" }}
添加交互：JavaScript 实现展开/收起

样式定义

所有样式在 assets/sass/_custom.sass 中：

1.filetree-container        // 主容器
2.filetree-header          // 树形结构头部
3.filetree-toggle          // 文件切换按钮
4.filetree-content         // 文件内容区域
5.filetree-code-wrapper    // 代码包装器

支持亮色/暗色主题自动切换。

性能考虑

构建性能

扫描速度：~100ms（小型项目）
构建时间：与 Hugo 标准构建一致
增量构建：仅更新修改的文件（Hugo 自动处理）

页面性能

文件大小：每个文件树 ~10-50KB（取决于代码量）
加载策略：内容默认隐藏，点击时展开
优化建议：单个目录建议不超过 50 个文件

最佳实践

合理分组：按功能或语言分类目录
控制大小：大文件（>1MB）考虑使用链接
定期清理：删除不需要的示例代码
版本管理：将生成的 YAML 文件纳入 Git

常见问题（FAQ）

Q: 支持哪些文件类型？ A: 支持所有文本文件，包括 20+ 种编程语言。二进制文件不支持。

Q: 可以展示 private 仓库的代码吗？ A: 可以，代码文件在本地，不涉及网络请求。

Q: 如何更新文件列表？ A: 修改代码后运行 python3 scripts/generate_filetree.py 即可。

Q: 是否支持代码搜索？ A: 目前不支持，可以使用浏览器的页面内搜索（Ctrl+F / Cmd+F）。

Q: 可以下载文件吗？ A: 暂不支持，可通过 GitHub 链接提供下载。

Q: 性能如何？ A: 扫描和构建速度快，页面加载按需展开，性能优秀。

总结

autotree shortcode 通过自动化扫描和智能渲染，将复杂的文件展示流程简化为一行代码。无论是展示项目结构、教程代码还是配置文件，都能快速、美观、交互式地呈现给读者。

核心优势回顾：

🎯 一行代码：{{< autotree dir="xxx" >}}
🚀 零维护：自动扫描和更新
🎨 美观：树形结构 + 语法高亮
📱 响应式：完美支持移动端
♿ 无障碍：键盘操作支持