企业官网建设流程全解析

• 前端

本文以本仓库课程 Guide 章节（guide/_index.md）为核心骨架，系统讲解构建 Hugo Blox 站点必须掌握的三件事：内容目录结构与文件命名约定、config/_default/下的站点配置、以及基于 Markdown 与内置短代码（shortcode）的富内容格式化。读完本文，你将能独立规划内容目录、配置菜单与左右侧边栏，并熟练使用 Button、Callout、Cards、Spoiler、Steps、媒体嵌入等全部内置组件。

从 Guide 章节开始：三大主题一目了然

在本仓库的课程体系中，guide/_index.md 是 "Learn Hugo Blox in 10 minutes!" 课程（见 content/courses/hugo-blox/_index.md）中承上启下的指南章节。它本身是一页导航索引：front matter 中通过weight: 2控制章节顺序，sidebar.open: true让侧边栏默认展开，正文则用三张卡片把读者引向三个核心主题：

这张卡片本身就是 Cards 短代码的真实使用案例（后文会详述），展示了一种"Hugo Blox 式"的内容组织方式：用{{< cards >}}把相关页面聚合成导航入口。下文按这三个主题依次展开。

项目结构：四大目录与文件命名约定

4 个主文件夹与 1 个版本文件

Hugo 站点有4 个主文件夹（外加 1 个模块版本文件），本仓库的目录结构与之完全对应：

• content/：存放 Markdown 格式的内容文件（首页、文档页等）。其中_index.md是首页（Hugo 要求首页与归档页必须以_index下划线前缀命名）。本仓库的content/下就有authors/、blog/、courses/、events/、projects/、publications/、slides/等板块。
• assets/：资源目录。
  • assets/media/：存放媒体文件（图片、视频）。本仓库的作者头像、幻灯片 Logo 都位于 assets/media/。
  • assets/media/icons/custom/：上传任何你想使用的自定义 SVG 图标（目录在本仓库中已预留，见 assets/media/icons/custom/）。
• config/_default/：站点配置文件目录。本仓库正好包含 5 个文件，各司其职：
  • hugo.yaml：配置 Hugo 本身（站点标题、URL、Hugo 选项、按文件夹设置页面特性）。例如其中用cascade让/slides/**页面额外输出present格式、配置outputs、markup.highlight代码高亮等。
  • module.yaml：安装或卸载 Hugo 主题与插件。本仓库通过imports引入github.com/HugoBlox/kit/modules/...下的 netlify、blox、slides 模块，并用mounts把社区 blox 挂载到布局目录。
  • params.yaml：配置 Hugo Blox 选项（SEO、分析、站点特性），是功能开关最集中的文件（详见下文"配置"章节）。
  • menus.yaml：配置菜单链接（前提是params.yaml中启用了该菜单）。
  • languages.yaml：配置站点语言，或为多语言站点设置语言级选项。
• static/uploads/：存放希望访客下载的文件，例如 PDF。本仓库的 static/uploads/resume.pdf 就是真实用例。
• go.mod：设定站点使用的 Hugo 主题/插件版本。位于仓库根目录的 go.mod 定义了 HugoBlox Kit 相关模块依赖。

Hugo 文件命名约定

Hugo 提供两种标准页面文件命名方式：TITLE/index.md或TITLE.md（TITLE为页面名）。页面名应小写并使用连字符（-）代替空格。两种方式产出的 URL 结果相同，可任选一种组织方式；文件夹方式的额外好处是页面所有文件（如图片）都收拢在该页面的文件夹内，页面自包含、更便于整体分享。

首页是特例：Hugo 要求首页与列表页（listing pages）命名为_index.md。例如本仓库的 content/blog/_index.md、content/courses/_index.md 都是列表页，而首页则由content/_index.md（若存在）担任。

文档导航与排序

文档导航（Docs Navigation）会根据docs/文件夹中的内容自动生成，默认按字母顺序排序。可通过在 Markdown 文件的 front matter 中添加weight参数改变页面顺序——weight值越小越靠前。原文档给出的示例：

页面example.md：

--- title: My Example weight: 1 ---

页面test.md：

--- title: My Test weight: 2 ---

由于example.md的weight更小，它将排在test.md之前。本仓库的 Guide 章节正是这样排序的：project-structure.md设weight: 1、configuration.md设weight: 2（见 guide/project-structure.md 与 guide/configuration.md），而guide/_index.md本身设weight: 2用于章节排序。

站点配置：config/_default/ 全解析

站点配置全部位于config/_default/目录，guide/configuration.md 从导航、左/右侧边栏三个角度讲解了配置方法。

菜单（Menu）配置

菜单通过menus.yaml定义。站点顶部的main菜单在本仓库中的真实结构（节选自 menus.yaml）为：

main: - name: Bio url: / weight: 10 - name: Experience url: experience/ weight: 20 - name: Projects url: projects/ weight: 30 - name: Courses url: courses/ weight: 40

可以看到每个菜单项包含name、url、weight三个字段，weight控制链接在菜单中的出现顺序。

左侧边栏（Left Sidebar）

左侧边栏的链接自动从内容目录的结构生成：只需添加一个文件夹即可嵌套页面（本仓库content/courses/hugo-blox/guide/下再建formatting/文件夹即形成二级导航，见 guide/formatting/）。

除了自动生成的导航，还可在config/_default/menus.yaml的sidebar段添加额外链接，完整配置示例（原文继承）：

menu: sidebar: - name: "Need help?" params: type: separator weight: 1 - name: "A page" pageRef: "/page-filename-here" weight: 2 - name: "An external link ↗" url: "https://example.com" weight: 3

要点说明：

• type: separator用于渲染一个分隔符标题（如 "Need help?"），本身不可点击；
• pageRef指向站内页面路径（如/page-filename-here）；
• url用于站外链接（示例中的https://example.com请替换为你自己的地址）；
• weight决定链接在侧边栏中的顺序。

右侧边栏与目录（Table of Contents）

右侧边栏的目录（TOC）自动根据 Markdown 文件的标题生成。可选地在页面 front matter 中设置toc: false关闭该页面的目录：

--- title: My Page toc: false ---

这一"页面级覆盖"与本仓库 params.yaml 中hugoblox.content.toc.enable: true的全局默认值相互配合：全局默认开启，个别页面用 front matter 关闭。与此类似的还有math（LaTeX 数学渲染，默认false）、reading_time（阅读时长估算）等开关，均可在params.yaml的hugoblox.content段统一控制（见 params.yaml）。

常用功能配置速查

params.yaml是 Hugo Blox 的核心功能开关所在，除上述content段外，本仓库还展示了这些常用分组（config/_default/params.yaml）：

• identity：站点品牌信息（名称、组织、Schema.org 类型、描述、社交账号）；
• theme：明暗模式（light/dark/system）、主题包与主色覆盖；
• header/footer：顶栏样式（navbar等）、搜索、主题切换、语言切换开关；
• copyright：版权声明与许可证（CC 类型及衍生/商用/共享条款）；
• seo：浏览器标签标题、AI 爬虫引导（seo.ai.allow/disallow）；
• search：站内搜索开关与建议词；
• comments：评论系统（giscus / disqus）开关与凭据；
• analytics：Google Analytics、GTM、Plausible、Fathom 等分析服务接入。

内容格式化：Markdown 与 Hugo Blox 短代码

Guide 章节的 Formatting 主题（见 guide/formatting/_index.md）倡导：用 Markdown + 可复用的 Hugo Blox 组件（短代码）编写丰富、有吸引力的内容。它通过五张卡片组织了 Button、Callout、Cards、Spoiler、Steps 五个短代码，此外格式化目录下还包含媒体嵌入文档（media.md）。下面逐一讲解。

Button：现代、可定制的按钮短代码

Button 短代码提供渐变样式、图标与智能链接处理。基础用法：

{{< button url="/contact" >}}Contact Us{{< /button >}} {{< button url="https://example.com" new_tab="true" style="secondary" >}}Visit External Site{{< /button >}}

第一个按钮指向站内/contact页面，第二个是"新标签页打开"的外部链接按钮。

风格变体（style参数，默认primary）：

{{< button url="#" style="primary" >}}Primary Button{{< /button >}} {{< button url="#" style="secondary" >}}Secondary Button{{< /button >}} {{< button url="#" style="outline" >}}Outline Button{{< /button >}} {{< button url="#" style="ghost" >}}Ghost Button{{< /button >}}

尺寸（size参数，默认md）：

{{< button url="#" size="sm" >}}Small Button{{< /button >}} {{< button url="#" size="md" >}}Medium Button{{< /button >}} {{< button url="#" size="lg" >}}Large Button{{< /button >}} {{< button url="#" size="xl" >}}Extra Large{{< /button >}}

对齐（align参数，默认left）：

{{< button url="#" align="left" >}}Left Aligned{{< /button >}} {{< button url="#" align="center" >}}Center Aligned{{< /button >}} {{< button url="#" align="right" >}}Right Aligned{{< /button >}}

图标（icon+icon_position，默认图标位于文本前）：

{{< button url="#" icon="arrow-down-tray" >}}Download{{< /button >}} {{< button url="#" icon="arrow-right" icon_position="right" >}}Continue{{< /button >}}

图标名称取自 Hero Icons 图标包；icon_position可取值left/right。

圆角（rounded参数，默认md）：

{{< button url="#" rounded="sm" >}}Small Radius{{< /button >}} {{< button url="#" rounded="md" >}}Medium Radius{{< /button >}} {{< button url="#" rounded="lg" >}}Large Radius{{< /button >}} {{< button url="#" rounded="full" >}}Pill Button{{< /button >}}

高级示例——组合参数实现真实场景：

{{< button url="/signup" style="primary" size="lg" align="center" icon="rocket-launch" >}}Get Started Today{{< /button >}}

{{< button url="https://example.com" new_tab="true" style="outline" icon="arrow-top-right-on-square" icon_position="right" >}}View on GitHub{{< /button >}}

{{< button url="/files/document.pdf" style="secondary" icon="document-arrow-down" rounded="full" >}}Download PDF{{< /button >}}

分别是：居中的 CTA 大按钮、新标签页打开的外部链接按钮、胶囊圆角的下载按钮（url指向站内文件如 static/uploads/resume.pdf）。

参数表（完整继承）：

安全特性：按钮短代码会自动处理外部链接的安全属性——外部链接自动添加rel="noreferrer"；在新标签页打开的外部链接添加rel="noopener noreferrer"；在新标签页打开的站内链接添加rel="noopener"。这保证了安全的导航跳转且不损失功能。

无障碍（Accessibility）：内置role="button"属性、aria-label支持、键盘焦点指示、高对比度焦点环以及禁用状态处理。

Callout：GitHub 与 Obsidian 风格的提示块

Hugo Blox 支持 GitHub 与 Obsidian 风格的 Markdown Callout（提示块），用于在文章中强调重要或相关内容（笔记、提示、警告等），兼具最大兼容性与内容可移植性。全部 15+ 种 Obsidian 提示类型均受支持。

信息与笔记类：

> [!NOTE] > 这是一条需要用户知晓的重要信息的提示。 > [!INFO] > INFO 是 NOTE 的别名，样式相同。 > [!ABSTRACT] > 用于摘要、总结或 TL;DR 段落。

动作与任务类：

> [!TODO] > 这是需要完成的事项。 > [!TIP] > 这是一条让工作流更高效的小技巧！ > [!SUCCESS] > 操作成功完成！

问答与交互类：

> [!QUESTION] > 你对这个方案怎么看？ > [!EXAMPLE] > 这里给出一个实现该功能的实际例子。 > [!QUOTE] > "预测未来的最好方式是创造未来。" —— 艾伦·凯

警告与错误类：

> [!WARNING] > 小心！该操作可能带来意想不到的后果。 > [!CAUTION] > 危险！该操作不可逆，可能导致数据丢失。 > [!IMPORTANT] > 这是用户必须理解才能继续的关键信息。 > [!DANGER] > 极度危险，请格外谨慎！ > [!FAILURE] > 操作失败，请检查配置后重试。 > [!BUG] > 已知问题：该功能在 Safari < 14 中无法正常工作。

自定义标题：任何提示块都可以通过+后接自定义文本覆盖默认标题：

> [!WARNING]+ 自定义警告标题 > 这条警告使用自定义标题，而不是默认的 "Warning"。

旧版短代码语法（已弃用）：旧的callout短代码仍然可用，但会显示弃用警告：

{{< callout note >}} 这仍然有效，但已弃用，请改用上面的 Markdown 语法！ {{< /callout >}}

CSS 自定义：Hugo Blox 生成的 Callout 带有语义化 CSS 类与 data 属性，便于定制。每个 Callout 包含：基类.callout、类型专属的 data 属性data-callout="note"、以及组件类.callout-icon、.callout-title、.callout-content、.callout-body。可添加自定义 CSS（例如在站点的assets/css/custom.css中）：

/* 自定义 NOTE 提示块 */ .callout[data-callout="note"] { border-left-width: 8px; box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1); } /* 让 SUCCESS 提示块呼吸闪烁 */ .callout[data-callout="success"] { animation: pulse 2s infinite; } /* 自定义图标样式 */ .callout-icon svg { transition: transform 0.2s; } .callout:hover .callout-icon svg { transform: scale(1.1); } /* 深色模式覆盖 */ @media (prefers-color-scheme: dark) { .callout[data-callout="warning"] { background-color: rgb(92 25 2); border-color: rgb(245 158 11); } }

该 CSS 定制方式与 Obsidian 的 CSS 定制体系一致，样式可跨平台复用。

新语法的优势：可移植（兼容 GitHub、Obsidian 及其他 Markdown 编辑器）、标准化（采用广泛使用的 Markdown Callout 语法）、干净（无需 Hugo 专属短代码）、面向未来（受最新 Hugo 版本支持）、可定制（语义化 CSS 类与 data 属性）、完整（支持全部 15+ Obsidian 提示类型）、多语言（提示标题根据站点语言自动翻译，并可在语言包中定制）。

Cards：卡片式导航

Cards 短代码用于创建卡片，卡片可作为链接或纯文本展示。用法示例：

{{< cards >}} {{< card url="../callout" title="Callout" icon="academic-cap" >}} {{< card url="" title="A card without an icon" >}} {{< /cards >}}

第一张卡片带图标和链接，第二张卡片既无图标也无链接（纯文本卡片）。

参数表：

本仓库中 Cards 短代码有大量真实用例：Guide 章节的 guide/_index.md、课程首页 content/courses/hugo-blox/_index.md 都用{{< cards >}}+{{< card >}}组织章节导航。

Spoiler：折叠内容块

Spoiler 短代码用于切换显示可折叠内容，非常适合"点击查看答案/剧透"。用法：

{{< spoiler text="Click to view the spoiler" >}} 这是折叠内容的正文。 Markdown 是**受支持**的。 {{< /spoiler >}}

text参数设定点击前的提示文字，折叠内容中支持 Markdown 渲染。

Steps：教程步骤序列

Steps 短代码用于展示一系列步骤（例如教程），步骤标题使用Markdown 三级标题（###）表示。用法：

{{% steps %}} ### Step 1 第一步的操作说明…… ### Step 2 第二步的操作说明…… ### Step 3 第三步的操作说明…… {{% /steps %}}

注意这里使用的是{{% %}}百分号围栏：Hugo 中{{% %}}形式会先渲染内部的 Markdown 内容（三级标题会被处理为步骤标题），而{{< >}}尖括号形式不渲染内部 Markdown。本仓库的 getting-started.md 正是用{{% steps %}}组织"从模板创建站点"的四步流程，可作为真实范例对照。

富媒体内容：视频、音频、数学、代码与图标

格式化目录下的 media.md 进一步展示了 Hugo Blox 对技术类内容的全方位支持：嵌入视频、播客、代码、LaTeX 数学，甚至用折叠块"测试学生"。

视频，三种方式任选：

{{< youtube w7Ft2ymGmfc >}} <!-- YouTube --> {{< bilibili id="BV1WV4y1r7DF" >}} <!-- Bilibili --> {{< video src="my_video.mp4" controls="yes" >}} <!-- 视频文件 -->

视频文件可放在assets/media/媒体库，或放在页面自己的文件夹（Page Bundle）中。

播客 / 音频：把 MP3 文件放入页面文件夹或媒体库，然后用 audio 短代码嵌入：

{{< audio src="ambient-piano.mp3" >}}

本仓库的 guide/formatting/ambient-piano.mp3 就是为这个短代码准备的真实音频文件。

用 Spoiler 测试学生：提供简单有趣的自我评估，用spoiler短代码揭示挑战题的答案：

{{< spoiler text="点击查看答案" >}} 你找到答案了！ {{< /spoiler >}}

数学公式：Hugo Blox 支持 $\LaTeX$ 数学扩展，通过在config/_default/params.yaml中切换math选项开启（本仓库 params.yaml 中hugoblox.content.math.enable默认关闭，需开启才能渲染）。行内公式用{{< math >}}$...${{< /math >}}，块级公式用{{< math >}}$$...$${{< /math >}}。之所以要把 LaTeX 包在math短代码里，是为了防止 Hugo 把数学内容误当作 Markdown 处理。块级公式示例：

{{< math >}} $$ \gamma_{n} = \frac{ \left | \left (\mathbf x_{n} - \mathbf x_{n-1} \right )^T \left [\nabla F (\mathbf x_{n}) - \nabla F (\mathbf x_{n-1}) \right ] \right |}{\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2} $$ {{< /math >}}

行内公式示例：{{< math >}}$\nabla F(\mathbf{x}_{n})${{< /math >}}。多行数学可用\\换行（LaTeX 的cases环境）：

{{< math >}} $$f(k;p_{0}^{*}) = \begin{cases}p_{0}^{*} & \text{if }k=1, \\ 1-p_{0}^{*} & \text{if }k=0.\end{cases}$$ {{< /math >}}

代码高亮：Hugo Blox 利用 Hugo 的 Markdown 扩展进行代码语法高亮，代码主题在config/_default/params.yaml中选择（本仓库 hugo.yaml 的markup.highlight段即控制高亮行为，如lineNos开关）。普通围栏代码块即可：

import pandas as pd data = pd.read_csv("data.csv") data.head()

内联图标：用icon短代码在行内插入图标：

{{< icon name="python" >}} Python

结语

至此，Guide 章节的三大主题已经打通：先理解content/、assets/、config/_default/、static/uploads/四大目录与_index.md命名约定，再掌握menus.yaml菜单、左右侧边栏与params.yaml功能开关，最后用 Button、Callout、Cards、Spoiler、Steps 与媒体短代码把内容"写活"。这套知识可以直接套用到本仓库的任意板块：例如给 content/blog 的文章加 Callout 提示、给 content/publications 列表页设计卡片导航、或在 content/slides 演示中嵌入数学公式。若需要更深层的定制（如主题自定义与多语言），可继续阅读课程的 reference 章节（content/courses/hugo-blox/reference/），并以仓库根目录的 hugoblox.yaml 与 config/_default/ 为起点逐步探索。

• 前端