Hugo模板之Hextra使用记录
原因
Hextra是一个较新的Hugo主题，使用Tailwind CSS提供了现代化的设计。作者是国人，主题也比较符合国人审美。 左侧导航更美观，还提供了一些组件，使得整体美观度更高。
安装
Hextra推荐的安装方式是使用hextra-starter-template，也可以使用Hugo模块或者git子模块来使用。相比Doks，对Hugo的影响较少。
打开 imfing/hextra-starter-template，在页面右上角点击Use this template，创建一个新的仓库，就可以了。
支持部署到 GitHub Pages 和 netlify
基本设置
在hugo.yaml中修改标题，顶部菜单，启用Logo。
title: "潘文斌的文档馆"
menu:
main:
- name: Docs
pageRef: /docs
weight: 1
- name: About
pageRef: /about
weight: 2
- name: Blog ↗
url: "https://www.panwenbin.cn"
weight: 3
- name: Search
weight: 4
params:
type: search
- name: GitHub
weight: 5
url: "https://github.com/panwenbin"
params:
icon: github
params:
navbar:
displayTitle: true
displayLogo: true
logo:
path: images/logo.svg
dark: images/logo-dark.svg
布局
content/docs/下默认是docs布局，content/blog/下是blog布局，其他目录目录是default布局。
面包屑
默认以title生成，可以用linkTitle自定义面包屑文字。通过页面中breadcrumbs: false可以关闭面包屑。
提示框
> [!NOTE]
> 用户应该知道的有用信息，即使是在浏览内容时。
> [!TIP]
> 帮助用户更好地或更轻松地完成任务的建议。
> [!IMPORTANT]
> 用户需要了解的关键信息，以实现他们的目标。
> [!WARNING]
> 需要用户立即注意的紧急信息，以避免问题。
> [!CAUTION]
> 关于某些操作的风险或负面结果的建议。
网站图标
在static目录下，放置网站图标和相关文件。Hextra主题已经预设了常用的图标文件。
- android-chrome-192x192.png
- android-chrome-512x512.png
- apple-touch-icon.png
- favicon-16x16.png
- favicon-32x32.png
- favicon-dark.svg
- favicon.ico
- favicon.svg
- site.webmanifest
代码高亮
文件名
```python
def say_hello():
print("Hello!")
```
文件链接
```go {base_url="https://github.com/imfing/hextra/blob/main/",filename="exampleSite/hugo.work"}
go 1.20
```
行号
```python {linenos=table,linenostart=42}
def say_hello():
print("Hello!")
```
高亮行
```python {linenos=table,hl_lines=[2,4],linenostart=1,filename="hello.py"}
def say_hello():
print("Hello!")
def main():
say_hello()
```
短代码
标签页
{{< tabs items="JSON,YAML,TOML" >}}
{{< tab >}}**JSON**: JavaScript 对象表示法（JSON）是一种基于 JavaScript 对象语法的标准文本格式，用于表示结构化数据。{{< /tab >}}
{{< tab >}}**YAML**: YAML 是一种人类可读的数据序列化语言。{{< /tab >}}
{{< tab >}}**TOML**: TOML 旨在成为一种最小化的配置文件格式，由于其明显的语义，易于阅读。{{< /tab >}}
{{< /tabs >}}
使用 defaultIndex 属性来指定选中的标签页。索引从 0 开始。
{{< tabs items="JSON,YAML,TOML" defaultIndex="1" >}}
{{< tab >}}**JSON**: JavaScript 对象表示法（JSON）是一种基于 JavaScript 对象语法的标准文本格式，用于表示结构化数据。{{< /tab >}}
{{< tab >}}**YAML**: YAML 是一种人类可读的数据序列化语言。{{< /tab >}}
{{< tab >}}**TOML**: TOML 旨在成为一种最小化的配置文件格式，由于其明显的语义，易于阅读。{{< /tab >}}
{{< /tabs >}}
步骤
{{% steps %}}
### 第一步
这是第一步。
### 第二步
这是第二步。
{{% /steps %}}
卡片
{{< cards >}}
{{< card link="../callout" title="提示框" icon="warning" >}}
{{< card link="../callout" title="带标签的卡片" icon="tag" tag= "自定义标签" >}}
{{< card link="/" title="无图标" >}}
{{< /cards >}}
{{< cards >}}
{{< card link="/" title="图片卡片" image="https://source.unsplash.com/featured/800x600?landscape" subtitle="Unsplash 风景" >}}
{{< card link="/" title="本地图片" image="/images/card-image-unprocessed.jpg" subtitle="静态目录下的原始图片。" >}}
{{< card link="/" title="本地图片" image="images/space.jpg" subtitle="资源目录下的图片，由 Hugo 处理。" method="Resize" options="600x q80 webp" >}}
{{< /cards >}}
{{< cards >}}
{{< card link="../callout" title="带默认标签颜色的卡片" tag="标签文本" >}}
{{< card link="../callout" title="带红色标签的卡片" tag="标签文本" tagType="error" >}}
{{< card link="../callout" title="带蓝色标签的卡片" tag="标签文本" tagType="info" >}}
{{< card link="../callout" title="带黄色标签的卡片" tag="标签文本" tagType="warning" >}}
{{< /cards >}}
{{< cards cols="1" >}}
{{< card link="/" title="顶部卡片" >}}
{{< card link="/" title="底部卡片" >}}
{{< /cards >}}
{{< cards cols="2" >}}
{{< card link="/" title="左侧卡片" >}}
{{< card link="/" title="右侧卡片" >}}
{{< /cards >}}
提示框
{{< callout emoji="🌐" >}}
Hugo 可用于创建各种类型的网站，包括博客、作品集、文档站点等。
{{< /callout >}}
{{< callout type="info" >}}
请访问 GitHub 查看最新版本。
{{< /callout >}}
{{< callout type="warning" >}}
**提示框** 是一段简短的文本，旨在吸引注意力。
{{< /callout >}}
{{< callout type="error" >}}
出错了，系统即将崩溃。
{{< /callout >}}
图标
{{< icon "github" >}}
文件树
{{< filetree/container >}}
{{< filetree/folder name="content" >}}
{{< filetree/file name="_index.md" >}}
{{< filetree/folder name="docs" state="closed" >}}
{{< filetree/file name="_index.md" >}}
{{< filetree/file name="introduction.md" >}}
{{< filetree/file name="introduction.fr.md" >}}
{{< /filetree/folder >}}
{{< /filetree/folder >}}
{{< filetree/file name="hugo.toml" >}}
{{< /filetree/container >}}
详情
{{% details title="详情" %}}
这是详情的内容。
支持 **Markdown**。
{{% /details %}}
{{% details title="点击我展开" closed="true" %}}
默认情况下，这部分内容会被隐藏。
{{% /details %}}
总结
相比Doks，结构上更简洁，功能上比Doks更丰富一点，并且美观上更好看。
最后修改于 2025-06-16