Hugo Blox Academic CV 快速上手指南:四步搭建并发布你的学术主页
Hugo Blox Academic CV 快速上手指南:四步搭建并发布你的学术主页
本文以 Hugo Blox Academic CV 模板仓库中的 Getting Started 文档 为主体,完整讲解"选择模板 → 配置站点 → 添加内容 → 自动发布"的四步启动流程,并结合本仓库 config/_default/、netlify.toml、package.json 等真实配置与源码逐项佐证。读完本文,你将能够从零创建属于自己的学术 CV 站点,理解站点配置文件的职责分工,掌握本地开发与云端自动发布的完整工作流。
文档定位:十分钟课程的第一站
本仓库内置的 courses/hugo-blox 是一套面向新手的入门课程,其课程主页 content/courses/hugo-blox/_index.md 将目标设定为"10 分钟内学会用 Hugo Blox 创建和编辑你的站点"。而 Getting Started(front matter 中 weight: 1、type: docs)正是这门课程的第一站,后续内容通过课程页底部的卡片导航延伸至 Project Structure、Configuration 和 Formatting。
整篇文档的骨架是一个四步启动流程(文档中使用 steps shortcode 渲染为编号步骤列表),我们逐一展开,并补充仓库中的实现细节。
第一步:创建站点(Create a site)
文档给出的第一步是到模板站选择起始模板。本仓库本身就是一个可直接运行的 Academic CV 模板实例:
- hugoblox.yaml 中声明了模板身份
template.id: "academic-cv"、template.name: "Academic CV",并指定构建所需 Hugo 版本hugo_version: '0.162.0'; - go.mod 声明站点模块为
github.com/HugoBlox/kit/templates/academic-cv,并依赖HugoBlox/kit的netlify、blox、slides三个子模块,主题能力由此引入。
如果你不想从网页端挑选模板,也可以使用 CLI 方式创建站点。仓库 README.md 提供了对应的命令(前提是已安装 Hugo Extended 与 Node.js):
npx hugoblox create site --template academic-cv
创建完成后,你就拥有了与本仓库结构一致的站点骨架:content/(内容)、assets/media/(图片视频等媒体)、config/_default/(站点配置)、static/uploads/(供访客下载的文件,如 PDF 简历)等目录。这些目录的职责划分详见 Project Structure 文档:
content/:存放 Markdown 格式的内容文件,注意首页与列表页必须命名为_index.md;assets/media/:存放图片、视频等媒体,自定义 SVG 图标可放入assets/media/icons/custom/;config/_default/:集中存放全部站点配置文件;static/uploads/:存放可供访客直接下载的静态文件,本仓库中的示例简历即位于 static/uploads/resume.pdf。
第二步:配置你的新站点(Configure)
文档第二步要求配置站点名称、描述与菜单。在 Hugo Blox 模板中,这些全部集中在 config/_default/ 目录下,由五个文件分工协作:
| 配置文件 | 职责 |
|---|---|
| hugo.yaml | Hugo 引擎级配置:站点 URL、默认语言、分页、图片处理、构建选项等 |
| params.yaml | Hugo Blox 业务配置:站点品牌、主题、SEO、分析、评论等 |
| menus.yaml | 导航菜单链接及顺序 |
| languages.yaml | 语言与多语言站点设置 |
| module.yaml | 主题与插件模块的安装/卸载、目录挂载 |
站点名称与描述
站点级品牌信息在 params.yaml 的 hugoblox.identity 段配置:
hugoblox:
identity:
name: "Your Name" # 站点名称,默认显示在导航栏、页脚与浏览器标题
organization: "" # 版权声明中的法人实体,缺省时回退到 name
type: person # person | organization | local_business
tagline: "" # 站点短标语
description: "..." # 站点 meta description,供搜索引擎与社交分享使用
注意 hugo.yaml 中的 title 被留空,其注释明确说明"网站名称在 params.yaml 的 hugoblox.branding.name 下设置"——也就是说,站点名称的单一数据源是 params.yaml,Hugo 侧不再重复配置。
菜单配置
导航链接在 menus.yaml 中定义。本仓库默认菜单展示了两种 URL 写法:首页锚点(/#papers)和常规页面路径(experience/),并用 weight 控制排序:
main:
- name: Bio
url: /
weight: 10
- name: Papers
url: /#papers
weight: 11
- name: Experience
url: experience/
weight: 20
- name: Projects
url: projects/
weight: 30
- name: Courses
url: courses/
weight: 40
多语言与更多可选配置
languages.yaml 默认只启用英文(locale: en-us),文件内注释给出了开启中文等多语言的模板:取消注释 zh 段并指定 locale: zh-Hans、contentDir: content/zh、title 及各语言专属的 menu。若你的站点需要发布多语言内容,取消注释并补上对应语言的 contentDir 目录即可。
在 Configuration 文档 中还补充了两类常见的布局配置:
- 左侧边栏的额外链接:在
menus.yaml的sidebar段追加,支持separator分隔类型、pageRef站内页面与url外部链接三种条目; - 右侧目录(TOC):默认由 Markdown 标题自动生成,可在单页 front matter 中设置
toc: false关闭。
第三步:添加你的内容(Add your content)
文档第三步要求编辑首页并添加文档页面。本仓库展示了 Academic CV 模板典型的内容组织方式。
首页:基于 block 的页面组装
首页 content/_index.md 采用 type: landing 加 sections 列表的方式组装页面,每个 block 渲染一个区域,例如:
sections:
- block: resume-biography-3 # 个人简介区
content:
username: me # 对应 content/authors/ 中的作者目录
button:
text: Download CV
url: uploads/resume.pdf # 指向 static/uploads/ 下的简历
- block: collection # 内容集合区(论文、演讲、新闻等)
id: papers
content:
filters:
folders:
- publications
featured_only: true
可以看到,首页各区块通过 username 与 content/authors/ 目录、folders 与 content/ 下的内容类型(如 publications、events、blog)联动,属于典型的"配置驱动"页面组装方式。
作者数据:data/authors/me.yaml
个人资料(姓名、单位、社交链接、教育经历、工作经历、技能、语言、奖项)统一存放在 data/authors/me.yaml,首页简介、经验页 等都以 username: me 引用它,实现"一处维护、多处复用"。例如:
schema: hugoblox/author/v1
slug: me
is_owner: true
name:
display: Dr. Alex Johnson
role: Senior AI Research Scientist
interests:
- Large Language Models
- Computer Vision
education:
- degree: PhD Computer Science
institution: Stanford University
start: 2015-09-01
end: 2019-06-30
各类内容与文件命名约定
模板内置了完整的示例内容类型:blog/(博客)、publications/(论文,含 conference-paper 等示例,展示 BibTeX 导入、DOI 关联、publication_types、awards、funding 等结构化字段)、events/(演讲)、projects/(项目)、courses/(课程)、slides/(Markdown 幻灯片)、experience.md(经历页)。
命名上,Project Structure 文档 明确指出 Hugo 提供两种页面文件命名方式:TITLE/index.md 或 TITLE.md,页面名应使用小写与连字符(-)而非空格。文件夹方式的好处是页面资源(图片等)与 Markdown 自包含在一个目录内,便于整体迁移分享。首页与列表页则必须使用带下划线前缀的 _index.md。
内容排版方面,可参考 Formatting 课程页,它汇总了可复用的短代码组件:button(按钮)、callout(提示框)、cards(卡片)、spoiler(折叠内容)、steps(步骤列表)等,均配有完整的参数表格与可复制示例。
第四步:发布你的站点(Publish)
文档第四步说明:站点会在你对 GitHub 仓库中文件提交(保存)更改后约 1–5 分钟内自动发布。这一自动化能力由平台构建配置支撑,本仓库提供了完整的实现证据。
Netlify 自动构建配置
netlify.toml 定义了云端自动构建的完整流水线:
[build]
command = """
set -e
pnpm install --verbose --no-frozen-lockfile
hugo --gc --minify -b $URL --logLevel debug --printI18nWarnings --printPathWarnings
pnpm run pagefind
"""
publish = "public"
[build.environment]
HUGO_VERSION = "0.162.0"
GO_VERSION = "1.21.5"
NODE_VERSION = "22"
流水线的三个阶段是:安装依赖(pnpm install)→ 用 Hugo 构建站点(hugo --gc --minify,输出到 public/)→ 用 Pagefind 生成静态搜索索引(pnpm run pagefind)。同时该文件为 deploy-preview(拉取请求预览)和 branch-deploy(分支部署)提供了各自的构建命令,前者额外使用了 --buildFuture 以预览未来发布的内容。这正是"提交后自动发布"的实现基础:每次 push/commit 都会触发云端重新构建。
本地脚本与搜索索引
package.json 中的脚本与上述流水线一一对应:
"scripts": {
"dev": "hugo server --disableFastRender",
"build": "hugo --minify && pnpm run pagefind",
"pagefind": "pagefind --site public"
}
pnpm dev:启动本地开发服务器,--disableFastRender关闭快速渲染以保证完整页面输出,适合边写边预览;pnpm build:本地完整构建并生成 Pagefind 搜索索引;pnpm run pagefind:对public/目录做静态站内搜索索引,这也是 params.yaml 中hugoblox.search.enable: true的配套实现。
部署目标声明
hugoblox.yaml 的 deploy.host: 'github-pages' 声明了模板默认的部署目标为 GitHub Pages,其注释同时列出了 github-pages、netlify、vercel、cloudflare、none 等可选项,你可以按自己的托管平台修改该字段。无论选择哪家平台,产物都是 public/ 下的纯静态文件,这也是"无需服务器、无需数据库、只靠文件即可永久免费托管"这一设计的基础。
后续定制:从入门到深入
Getting Started 文档在四步之后,通过 cards 短代码导出了三条后续学习路径,我们在本仓库中将其转换为仓库根目录下的相对路径,方便直接深入阅读:
- Project Structure(项目结构):文件夹结构、Hugo 文件命名约定、
weight控制文档导航排序; - Configuration(配置详解):导航菜单、左右侧边栏、页面 TOC 的配置方法;
- Formatting(创建内容):按钮、提示框、卡片、折叠、步骤等可复用短代码组件。
这三条路径分别对应"理解目录组织"、"掌握站点配置"、"高效产出内容"三个能力维度,建议按此顺序学习,即可完成从"创建站点"到"深度定制"的完整闭环。
小结:十分钟上手流程回顾
以本仓库为参照,Hugo Blox Academic CV 的完整上手流程可以概括为:
- 创建:选择 Academic CV 模板(或执行
npx hugoblox create site --template academic-cv)获得站点骨架; - 配置:在
config/_default/下按职责修改params.yaml(站点名、描述)、menus.yaml(导航菜单)、languages.yaml(语言)、hugo.yaml(构建选项); - 添加内容:用
username指向 data/authors/me.yaml 维护个人资料,用 block 组装 首页,再按内容类型补充博客、论文、演讲等 Markdown 页面; - 发布:将仓库推送到 GitHub(或 Netlify 等平台),由 netlify.toml 定义的流水线自动构建并发布,通常在提交后 1–5 分钟内生效;本地可用
pnpm dev实时预览、pnpm build验证产物。
所有环节都以可读的 Markdown 与 YAML 文件为载体,没有数据库锁定,随时可以完整迁移。