Hugo 主题
蓝莓 Hugo 主题
蓝莓是一个具有许多强大功能的高级 Hugo 主题。这是 Anders Norén 的 Lingonberry WordPress 主题的 Hugo 改编和进一步优化。
蓝莓 Hugo 主题 v4
本指南适用于 v4
版本。对于 v3
,请使用本指南。
重要 v3
不再受支持。如果要从 v3
迁移到 v4
,请阅读迁移指南。
对于那些想要为蓝莓 Hugo 主题做出贡献或自定义它的人,请参阅开发者指南。
蓝莓是一个具有许多强大功能的高级 Hugo 主题。这是 Anders Norén 的 Lingonberry WordPress 主题的改编和进一步优化。
这是一个实时演示站点,可以查看此主题的实际效果。
支持和讨论
此主题的支持通过项目的“问题”和“讨论”部分提供。如果要报告缺陷或错误,请使用“问题”部分。对于任何其他请求,请使用“讨论”部分。
如果要开始讨论,请使用以下准则
- 对于有关特定功能的任何问题,或者如果您需要有关使用或自定义主题的帮助,请使用“问题与解答”(Q&A) 类别。
- 要提出新功能或任何其他改进,请使用“想法”类别。
- 要展示由蓝莓主题支持的博客或网站,请使用“展示和讲述”类别。
- 对于任何其他查询,请使用“常规”类型的讨论。
目录
- 要求
- 快速入门
- 站点初始设置
- 主题安装选项
- 选项 1(推荐):将主题添加为 Hugo 模块
- 选项 2:将主题添加为 Git 子模块
- 选项 3:复制主题文件
- 配置
- 网络服务器
- 免费托管
- 其他教程
- 功能
- 默认文章类型
- 单页
- 页面捆绑
- 顶部导航栏
- 明/暗主题模式
- Algolia 搜索
- 初始设置
- 更新 Algolia 索引
- 手动上传
- 自动上传
- 键盘快捷键
- 转载文章/重复内容
- 估计阅读时间
- 摘要拆分
- 自动摘要拆分
- 手动摘要拆分
- 前言摘要拆分
- 无摘要拆分
- 开放图形元数据
- 目录 (TOC)
- 系列分类
- 图像
- 外部图像
- 图像模态缩放
- 特色图像
- 自动调整图像大小
- 超链接图像
- 视频
- PeerTube 配置
- 音频
- Google Analytics
- 评论
- Commento
- Disqus
- Giscus
- Utterances
- 存档页面
- 响应式设计
- MathJAX 标记
- 禁用 JavaScript 支持
- 精简 JavaScript 大小
- 原始 HTML
- 默认文章类型
- 自定义
- 钩子
- 网站图标
- 404 页面
- 自定义文章类型
- 单个文章
- 语法高亮
- 布局、颜色和字体
- CSS 和 JS 模块
- Cookie 免责声明 (GDPR)
- 翻译
- 鸣谢
- 贡献者
- 许可证
要求
- Hugo(版本 >= 0.125.7 扩展版),请参阅本指南,了解如何安装 Hugo。
- Git,请参阅本指南,了解如何安装 Git。
- Go(版本 >= 1.21),可选,仅当蓝莓主题用作 Hugo 模块时才需要;请参阅本指南,了解如何安装 Go。
快速入门
站点初始设置
- 将蓝莓 Hugo 主题存储库克隆到本地计算机
git clone https://github.com/Lednerb/bilberry-hugo-theme.git
或者,您可以将其下载为 ZIP 文件并提取到 bilberry-hugo-theme
目录中。
- 创建一个新站点
hugo new site my-new-blog
- 删除默认原型
rm my-new-blog/archetypes/default.md
主题安装选项
选项 1(推荐):将主题添加为 Hugo 模块
如果要从主蓝莓 Hugo 主题存储库中将主题文件作为 Hugo 模块拉入,请使用此选项。此选项使您可以轻松地使您站点中的主题保持最新。
- 从站点的根目录将您的网站初始化为 Hugo 模块
cd my-new-blog
hugo mod init github.com/<your-user>/my-new-blog
- 复制示例站点内容,包括
hugo.toml
文件
cp -r bilberry-hugo-theme/v4/exampleSite/* my-new-blog
- 通过更新主题的模块来拉取主题文件
hugo mod get -u
如果您需要有关如何使用 Hugo 模块的更多详细信息,请阅读 Hugo 文档。
选项 2:将主题添加为 Git 子模块
如果要从主蓝莓 Hugo 主题存储库中将主题文件作为 Git 子模块拉入,请使用此选项。此选项还可以使您可以轻松地使您站点中的主题保持最新。
- 复制示例站点内容,包括
hugo.toml
文件
cp -r bilberry-hugo-theme/v4/exampleSite/* my-new-blog
- 在
my-new-blog/hugo.toml
文件中,取消注释选项 2 和 3 的path
属性,并注释掉选项 1 的path
属性
[module]
[[module.imports]]
# Option 1 (recommended): adding the theme as a Hugo module
# path = "github.com/Lednerb/bilberry-hugo-theme/v4"
# Options 2 and 3: cloning/copying the theme files
path = "bilberry-hugo-theme/v4"
- 从站点的根目录将蓝莓 Hugo 主题添加为 Git 子模块
$ git submodule add https://github.com/Lednerb/bilberry-hugo-theme.git themes/bilberry-hugo-theme
选项 3:复制主题文件
如果您想直接自定义和维护自己的主题副本,请使用此选项。
- 复制示例站点内容,包括
hugo.toml
文件
cp -r bilberry-hugo-theme/v4/exampleSite/* my-new-blog
- 在
my-new-blog/hugo.toml
文件中,取消注释选项 2 和 3 的path
属性,并注释掉选项 1 的path
属性
[module]
[[module.imports]]
# Option 1 (recommended): adding the theme as a Hugo module
# path = "github.com/Lednerb/bilberry-hugo-theme/v4"
# Options 2 and 3: cloning/copying the theme files
path = "bilberry-hugo-theme/v4"
- 将上一步中克隆(或解压缩)的主题文件复制到
my-new-blog/themes
目录
cp -r bilberry-hugo-theme my-new-blog/themes/bilberry-hugo-theme
重要提示:请勿更改站点根目录中的 themes/bilberry-hugo-theme
文件夹的名称。重命名此文件夹会破坏您的站点。
配置
要根据您的需要自定义您的网站,请通过调整设置来编辑站点根目录中的 hugo.toml
文件。所有需要配置的参数都已注释掉或禁用。
Algolia 搜索在示例站点随附的 hugo.toml
文件中启用;因此,如果您不打算使用它,请将 algolia_search
属性设置为 false
来禁用它。
网络服务器
- 要构建和提供站点服务,请从站点的根目录执行以下命令
cd my-new-blog
hugo server
免费托管
要免费部署和托管您的网站,您可以使用 GitHub Pages 或 Netlify。
重要提示:在 GitHub Pages 上托管时,您应该在网站的根目录中添加一个名为 .nojekyll
的空文件,以避免 Font Awesome 的图标无法加载的问题。
其他教程
- 使用 Hugo、GitHub 和 Netlify 开始写博客
- 在 Netlify 上配置自定义域名和 HTTPS
- 管理基于 Hugo 的网站的特定于环境的设置
功能
默认文章类型
Bilberry 主题带有一组预定义的文章类型,即 article
、audio
、code
、gallery
、link
、page
、quote
、status
和 video
,其中 article
类型是默认类型。
要创建新内容,请使用 hugo new
命令。内容可以通过两种方式创建:单页或页面包。
单页
要创建新的单页内容,您可以使用以下命令
hugo new <content-type>/my-single-page-content.md
页面包
或者,可以按如下方式创建新的页面包内容
hugo new <content-type>/my-page-bundle-content/index.md
例如,您可以使用以下命令分别创建一个新的单页文章和一个新的页面包相册
hugo new article/my-single-page-article.md
hugo new gallery/my-page-bundle-gallery/index.md
page
文章类型是唯一可以在顶部导航栏中使用的类型。可以使用 weight
前端变量对页面进行排序,该变量应设置为非零值。 weight
值较低的页面将首先显示。
page
内容可以是静态页面,例如 关于 页面,或指向另一个页面(内部或外部)的链接。
link
文章类型始终链接到外部站点,并且可以使用或不使用背景图像。
顶部导航栏
如果要在顶部永久显示带有搜索文本字段和 page
项的导航栏,请在 hugo.toml
文件中将 permanentTopNav
参数设置为 true
。
如果要在向下滚动页面时显示顶部导航栏,请将 stickyNav
参数设置为 true
。但这只有在 permanentTopNav
也设置为 true
时才有效。
请注意,默认情况下,顶部导航栏在移动设备上是最小化的。
浅色/深色主题模式
可以通过将 enableLightDarkTheme
参数设置为 true
来启用浅色和深色主题模式之间的切换
[params]
enableLightDarkTheme = true
Algolia 搜索
Bilberry 主题通过 Algolia SAAS 包含内置的内容搜索。您可以通过单击演示站点上的“汉堡”图标并在搜索文本字段中键入一些内容(例如“支持”)来查看此操作。
初始设置
要为您的站点启用和配置搜索功能,请执行以下步骤
- 在 https://www.algolia.com/ 注册一个免费的 Algolia Search 帐户。
- 添加一个
新应用程序
。您可以选择COMMUNITY
计划。 - 切换到
索引
并创建一个新索引。 - 切换到
API 密钥
并将您的应用程序 ID
、仅搜索 API 密钥
和选择的索引名称
复制到您的hugo.toml
文件中。 - 确保
algolia_search
参数设置为true
。 - 按照“更新 Algolia 索引”部分中的说明进行操作,然后继续下一步。
- 要完成初始设置,请转到新创建的索引的
配置
选项卡,选择刻面
部分中的过滤和刻面
,并在用于刻面的属性
选项中添加带有仅过滤
修饰符的language
属性。如果在添加language
属性后显示未知属性
错误,请忽略它。
更新 Algolia 索引
每次更改文章或发布新文章以更新搜索索引时,都必须重复此步骤。
在站点的根目录中执行 hugo
命令以生成 index.json
文件。
手动上传
- 转到
public/index.json
文件并复制其内容。 - 登录您的 Algolia 帐户,打开您的索引,然后单击
手动添加记录
。 - 粘贴从
index.json
文件复制的文本。 - 在索引的
浏览
选项卡中验证索引记录是否已正确上传。 - 如果您有多语言设置,请确保对所有
public/{LANG}/index.json
文件重复上述步骤。
自动上传
- 切换到
algolia
目录并通过执行以下命令安装所需的依赖项
cd algolia
npm install
- 从
algolia
目录运行data-upload.js
,如下所示
npm run data-upload -- -f ../public/index.json -a <algolia-app-id> -k <algolia-admin-api-key> -n <algolia-index-name>
algolia-admin-api-key
参数(即您的 Algolia 帐户的管理员 API 密钥
)用于创建、更新和删除索引,应保密。- 如果要清除相应的 Algolia 索引,然后再开始新的上传,请添加
-c
或--clear-index
选项。 - 登录您的 Algolia 帐户并在索引的
浏览
选项卡中验证索引记录是否已正确上传。 - 如果您有多语言设置,请确保对所有
public/{LANG}/index.json
文件重复上述步骤。
此外,如果您在 Netlify 上托管基于 Bilberry 主题的网站,您可以阅读这篇关于如何自动将数据上传到 Algolia 索引的撰写文章,或者使用 GitHub Actions 的这篇撰写文章。
键盘快捷键
键入 s
以打开导航栏并将焦点设置到搜索输入字段。要移除焦点,请按 Esc
键。
转载文章/重复内容
如果您需要转载另一个网站的文章或复制您网站上的内容,则应将其链接到原始 URL,以便 SEO 正确处理它。为此,请在您的文章中定义 original_url
前端变量,例如
original_url: "https://example.org/path/to/content"
预计阅读时间
要显示文章的预计阅读时间,请在 hugo.toml
文件中将 showReadingTime
参数设置为 true
。您可以通过将文章的 readingTime
前置变量设置为您想要的值来覆盖预计阅读时间。如果您将此变量设置为 0
,则不会显示阅读时间。
readingTime: 7 # will show "7 MIN READ"
readingTime: 0 # reading time will not be shown
摘要分割
Hugo 可以生成内容摘要,以便在摘要视图(例如主页和标签或类别页面)中用作简短版本,这有三种方式。
自动摘要分割
Hugo 会自动使用您内容的前 70 个字生成摘要,并在后面添加继续阅读链接。
手动摘要分割
将 `
` 摘要分隔符添加到您的内容中。分隔符之前的任何内容都将被 Hugo 用作该内容的摘要。生成的摘要后也会添加继续阅读链接。
前置变量摘要分割
要定义一个与文章开头文本不同的摘要,请使用 summary
前置变量,例如,summary: "这是我的摘要"
。此摘要后面也会添加继续阅读链接。
无摘要分割
如果您想显示整篇文章而不显示继续阅读链接,请在内容文件中将 noSummary
变量设置为 true
。
Open Graph 元数据
默认情况下,以下基本 Open Graph 元数据包含在所有页面中:og:site_name
、og:title
、og:description
、og:type
、og:url
、article:section
、article:published_time
和 article:modified_time
,其中 article:published_time
标记将具有与 date
前置变量相同的 timestamp 值。
可以通过添加以下前置变量来包含其他元数据
publishDate
用于article:published_time
images
用于og:image
audio
用于og:audio
videos
用于og:video
series
用于og:see_also
例如
title: "Open Graph Metadata with Extra Front Matter Variables"
date: 2022-12-19T19:00:00-05:00
publishDate: 2022-12-19T20:00:00-05:00
lastmod: 2022-12-19T21:00:00-05:00
images: ["/img/content/article/open-graph-metadata-with-extra-front-matter-variables/thumbnail.jpg"]
audio: "/audio/icq-remix.mp3"
videos: ["/video/test_mp4_video.mp4"]
series: ["My Cool Series"]
目录 (TOC)
要启用自动创建目录 (TOC),请在您的文章中将 toc
前置变量设置为 true
。如果文章的 markdown 包含适当的标题,Hugo 将在文章开头生成目录。
默认情况下,如果内容的字数大于 400,则会生成目录。 tocMinWordCount
参数在 hugo.toml
配置文件中定义此值。
目录中考虑的标题范围是 H2 (##) 到 H5 (#####) (包括)。此外,如果您想在文章的特定位置显示目录,请将 toc
前置变量设置为 false
,并使用 toc
短代码,如下所示
{{< toc >}}
系列分类
如果您想将一些文章分组为一个系列,则必须为每篇文章添加 series
前置变量,并将其值设置为该系列的名称,例如,series: ["我的新超级系列"]
。
<site-base-url>/series/
处的页面将列出所有系列。要在 markdown 中列出特定系列的所有文章,您可以使用带有相关系列名称的 series
短代码,例如
{{< series "My New Super Series" >}}
图像
外部图像
如果您想使用外部图像(例如存储在另一个服务器或云端的图像)作为文章的特色图像或在 gallery
文章类型中使用,您可以通过将绝对 URL 值设置为适当的前置变量来使用它们
# /content/article/my-external-featured-image-post.md
featuredImage: "https://example.org/images/my-image.jpg"
# /content/gallery/my-external-gallery-post.md
gallery: [
"https://example.org/images/gallery-image1.jpg",
"https://example.org/images/gallery-image2.jpg",
"https://example.org/images/gallery-image3.jpg"
]
图像模态缩放
当您包含大于内容区域的图像时,该图像将变为交互式,并且可以在灯箱中打开更大的版本。模态缩放仅适用于使用标准 markdown 注释添加的图像,例如 
或 
用于带有图例的图像。请注意,此功能不适用于使用原始 HTML 添加的图像。
特色图像
有两种方法可以向文章添加特色图像。第一种方法是使用单页文章,并使用 featuredImage
前置变量,该变量的值应该是相对于基本 URL 的路径或绝对 URL。
或者,当使用页面包文章时,预期的特色图像应命名为 featuredImage.*
,其中 *
是图像文件扩展名,例如 jpg
、png
等。此外,它应放置在相关的页面包中,例如
content
└── article
└── my-post-with-featured-image
├── featuredImage.png
└── index.md
自动图像大小调整
Bilberry 主题包括内置的自动裁剪和调整大小功能,仅适用于特色和图库图像,默认情况下处于激活状态。但是,如果您想禁用它,请在 hugo.toml
文件中将 resizeImages
参数设置为 false
。此外,可以通过将 resizeImages
前置变量设置为 false
在文章级别禁用此功能。
要裁剪和调整特色图像的大小,应将其命名为 featuredImage.*
并放置在页面包的文件夹中。
注意:通过 featuredImage
前置参数定义的特色图像将不被裁剪和调整大小。
超链接图像
如果要将图像显示为超链接,请使用 hyperlink-image
短代码,如下所示
{{< hyperlink-image "<image-text>" "<image-url>" "<link-url>" >}}
视频
支持以下视频托管提供商:YouTube、Vimeo、Prezi、Bilibili 和 PeerTube。还支持以 MP4
格式存储在外部或站点 static
文件夹中的视频。有两种方法可以显示视频嵌入。
第一种方法是使用 video
类型的文章。使用以下命令创建您的视频文章
hugo new video/<post-name>.md
然后设置适当的前置变量,同时删除其他变量
youtube: "<youtube-video-id>" # https://www.youtube.com/watch?v=M7IjJiZUutk -> "M7IjJiZUutk"
vimeo: "<vimeo-video-id>" # https://vimeo.com/239830182 -> "239830182"
prezi: "<prezi-video-id>" # https://prezi.com/v/5z9shnq7jzxs/what-to-study/ -> "5z9shnq7jzxs"
bilibili: "<bilibili-video-id>" # https://www.bilibili.com/video/BV1Sx411T7QQ -> "BV1Sx411T7QQ"
peertube: "<peertube-video-id>" # https://vids.tekdmn.me/w/w7WGHX7Lb6mCrbrpF3Xb8V (entire URL)
mp4video: "<video-file-url>" # location of video file (only mp4)
mp4videoImage: "<image-video-file-url>" # location of poster image
例如,如果 MP4
视频及其图像存储在 static
文件夹中,您可以按如下方式设置相应的前置变量
mp4video: "/<video-file-name>.mp4"
mp4videoImage: "/<image-video-file-name>.png"
第二种方法是在 article
类型的文章中使用 markdown 内容中的 video
短代码,如下所示
<!-- YouTube -->
{{< video type="youtube" id="<youtube-video-id>" >}}
<!-- Vimeo -->
{{< video type="vimeo" id="<vimeo-video-id>" >}}
<!-- Prezi -->
{{< video type="prezi" id="<prezi-video-id>" >}}
<!-- bilibili -->
{{< video type="bilibili" id="<bilibili-video-id>" >}}
<!-- PeerTube -->
{{< video type="peertube" id="<peertube-video-id>" >}}
<!-- MP4 external -->
{{< video type="mp4" url="<video-file-url>" imageUrl="<image-video-file-url>" >}}
<!-- MP4 in site's static folder -->
{{< video type="mp4" url="/<video-file-name>.mp4" imageUrl="/<image-video-file-name>.png" >}}
PeerTube 配置
因为没有一个 PeerTube 站点,所以您需要指明您的视频使用哪些站点,这意味着您不能只使用视频 ID。而是复制整个观看 URL,它将被转换为要使用的正确的嵌入 URL。
如果您想开始在 PeerTube 上托管您的视频,但不知道加入哪个实例,则有一个实例查找器。
音频
支持以下音频流媒体提供商:Mixcloud、SoundCloud、Spotify 和 TuneIn。还支持以 Ogg
、MP3
或 WAV
格式存储在外部或站点 static
文件夹中的音频文件。有两种方法可以显示音频嵌入。
第一种方法是使用 audio
类型的文章。使用以下命令创建您的音频文章
hugo new audio/<post-name>.md
然后设置适当的前置变量,同时删除其他变量
spotify: "<spotify-track-id>" # https://open.spotify.com/track/3W2lz1sg6m4sEzjmoTjmdE?si=0659fd12179840dd -->
3W2lz1sg6m4sEzjmoTjmdE
soundcloud: "<soundcloud-track-url>" # https://soundcloud.com/lightbooks/alchemist-08-new-world-order-snip
tunein: "<tunein-track-id>" # https://tunein.com/embed/player/t117894382/" --> t117894382
mixcloud: "<mixcloud-track-id>" # https://www.mixcloud.com/scienceforthepeople/445-ai-ant-intelligence/ -->
scienceforthepeople/445-ai-ant-intelligence
audiofile: "<audio-file-url>" # location of audio file (only ogg, mp3, or wav formats)
例如,如果一个 MP3
音频文件存储在 static
文件夹中,您可以将 audiofile
前端变量设置为如下:
audiofile: "/<audio-file-name>.mp3"
第二种选择是在 article
类型的文章的 Markdown 内容中使用 audio
短代码,如下所示:
<!-- Mixcloud -->
{{< audio type="mixcloud" id="<mixcloud-track-id>" >}}
<!-- SoundCloud -->
{{< audio type="soundcloud" id="<soundcloud-track-url>" >}}
<!-- Spotify -->
{{< audio type="spotify" id="<spotify-track-id>" >}}
<!-- TuneIn -->
{{< audio type="tunein" id="<tunein-track-id>" >}}
<!-- MP3 external -->
{{< audio type="audiofile" url="<audio-file-url>" >}}
<!-- MP3 in site's static folder -->
{{< audio type="audiofile" url="/<audio-file-name>.mp3" >}}
Google Analytics
Bilberry 主题内置支持 Google Analytics 的 v3 和 v4 版本。要启用它,请在 hugo.toml
中设置 services.googleAnalytics.ID
属性的值。
[services]
[services.googleAnalytics]
ID = 'G-XXXXXXXXXX'
评论
要允许读者在您的文章下发表评论,您可以使用 Commento、Disqus、Giscus 或 Utterances。
给开发者/贡献者的提示:如果您想提交一个新的评论引擎与 Bilberry 主题集成,它必须满足以下条件:
- 该引擎应作为 SAAS 提供,即您只需创建一个帐户并在引擎的网站上配置必要的设置即可。
- 如果该引擎作为 SAAS 提供,则必须有一个免费套餐。
- 集成第三方评论服务所需的所有配置步骤必须仅在
hugo.toml
文件中进行,而不在部分文件或任何其他文件中进行额外配置。
Commento
如果您想使用 Commento 云服务(非免费),请按照本指南操作。
如果您想使用自托管的 Commento,请按照这些说明进行操作。
然后在 hugo.toml
文件中取消注释 commentoJsURL
参数
#[...]
[params]
#[...]
# Commento
commentoJsURL = "https://127.0.0.1:8080/js/commento.js"
Disqus
要允许读者在您的文章下留言,请在 Disqus 网站上免费注册。然后创建一个新站点,并在 hugo.toml
文件中将 disqusShortname
参数设置为您站点的短名称
#[...]
[params]
#[...]
# Disqus
disqusShortname = "lednerb"
您可以在您的网站上或使用 Disqus 管理面板管理和审核评论。
Giscus
请按照 Giscus 网站上的说明进行操作。完成 GitHub 存储库的先决条件并选择讨论类别后,将自动生成 giscusRepositoryId
和 giscusCategoryId
的值。然后,在 hugo.toml
文件中,将 giscus
参数设置为 true
,并将上述属性设置为相应的值
#[...]
[params]
#[...]
# Giscus
giscus = true
giscusJsUrl = "https://giscus.app/client.js"
giscusRepository = "Lednerb/bilberry-hugo-theme"
giscusRepositoryId = "R_kgDOGX153A" # generated by Giscus website
giscusMapping = "pathname"
giscusCategory = "General"
giscusCategoryId = "DIC_kwDOGX153M4B_2Vz" # generated by Giscus website
giscusTheme = "light"
giscusDarkTheme = "dark"
giscusReactions = "1"
giscusEmitMetadata = "0"
giscusLanguage = "en"
giscusCrossOrigin = "anonymous"
Utterances
请按照 Utterances 网站上的说明进行操作。完成 GitHub 存储库的先决条件后,在 hugo.toml
文件中将 utterances
参数设置为 true
#[...]
[params]
#[...]
# Utterances
utterances = true
utterancesJsUrl = "https://utteranc.es/client.js"
utterancesRepository = "Lednerb/bilberry-hugo-theme"
utterancesIssueTerm = "pathname"
utterancesLabel = "Comment"
utterancesTheme = "github-light"
utterancesCrossOrigin = "anonymous"
存档页面
当您将 themes/bilberry-hugo-theme/exampleSite/content/archive.md
文件复制到您站点的 content
目录后,存档页面将在 <site-base-url>/archive/
中可用。默认情况下,已发布的内容按年份分组。要按年和月对内容进行分组,请将 archiveDateGrouping
参数设置为 2006-01
值。
要在页脚中显示存档链接,请将 showArchive
参数设置为 true
。
要将存档链接添加到顶部导航栏,请使用以下命令创建一个新页面
hugo new page/archive.md
然后,在新建的 content/page/archive.md
文件中,将 link
前端变量设置为 /archive/
值,并完全删除 target
变量。
响应式设计
Bilberry 主题经过优化,可在所有设备(即台式机、平板电脑和智能手机)上呈现良好效果。
MathJAX 标记
要启用 MathJAX 标记支持,请在 hugo.toml
文件中将 enable_mathjax
参数设置为 true
。
禁用 JavaScript 支持
虽然此主题有很多功能只能在启用 JavaScript 的情况下工作,但它也完全支持禁用 JavaScript。禁用 JavaScript 不会破坏您网站的任何样式或基本功能。
您可以通过在浏览器中禁用 JavaScript 来测试演示站点的行为。
精简的 JavaScript 大小
默认情况下,此主题的 JavaScript 包包含 Moment.js 库,该库足够大,尽管它们增加了真正的价值。
因此,为了减小下载的 JavaScript 包的大小,您可以选择是否通过 enableMomentJs
配置参数保持启用 Moment.js 库(目前是默认设置)。将其设置为 false
会使包大小减少约 262 kB(gzip 压缩)。
原始 HTML
如果您想在 Markdown 内容中包含原始 HTML,请在 hugo.toml
文件中将 unsafe
设置为 true
[markup.goldmark]
[markup.goldmark.renderer]
unsafe = true
自定义
钩子
如果您需要将您的网站与第三方服务集成或进一步自定义,您可以使用以下钩子部分:hooks/head-end.html、hooks/body-start.html 和 hooks/body-end.html。将相关文件复制到您站点根目录的 layouts/partials/hooks
文件夹中,并添加必要的代码,例如,此 hooks/body-end.html 文件中包含与 Umami 网络分析的集成。
<script async defer src="https://analytics.umami.is/script.js"
data-website-id="29b02d61-3df1-433f-8bb7-cba0ec70c9f7"></script>
网站图标
要添加网站图标,请按照以下步骤操作
- 访问 https://realfavicongenerator.net/ 网站,并根据您的需要生成网站图标。
- 将生成的文件复制并粘贴到您站点的
/static
文件夹中。 - 编辑
/layouts/partials/favicon.html
文件,然后从生成的说明中复制并粘贴 HTML 代码。
重要提示:您必须按照快速入门说明操作或手动将 /layouts/partials/favicon.html
文件从主题复制到您站点的 /layouts
目录。
此外,请查看有关如何向基于 Bilberry 主题的网站添加网站图标的教程。
404 页面
要自定义您的 404 页面,请将 themes/bilberry-hugo-theme/layouts/404.html
文件复制到您站点的 layouts/404.html
,并根据您的需要编辑该文件,例如,更改消息、图标类等。
自定义文章类型
使用 Bilberry 主题,您可以轻松创建新的文章类型。例如,假设您想创建一个名为 book
的新类型。那么您应该执行以下操作
- 将默认的
themes/bilberry-hugo-theme/layouts/partials/content-type/article.html
复制到您站点的layouts/partials/content-type/
文件夹中。 - 将文件重命名为您的自定义文章类型,即
book.html
。 - 自定义新创建的文件,例如,将气泡中的图标更改为 Font Awesome Icon 网站上可用的
fa-book
<i class="fas fa-fw fa-book"></i>
- 要创建新文章,请使用
book
文章类型前缀
hugo new book/my-favorite-book.md`
如果您想使用自定义的前言变量,请在您网站的 archetypes/
目录中创建一个 book.md
原型。
单独的文章
您可以按照以下方式自定义您的文章
要将文章从博客索引中排除,但仍然显示在类别中,请在文章的前言中添加
excludeFromIndex: true
。要将一篇或多篇文章固定到索引页面的顶部,请取消注释
hugo.toml
文件中的pinnedPost
参数。然后将其值设置为文章的相对 URL,例如/article/installing-bilberry-theme/
。当固定多篇文章时,相对 URL 值应以逗号分隔。pinOnlyToFirstPage
参数允许您选择是否仅在索引页上显示固定的文章,还是在所有页面上都显示。可以通过在文章的前言中指定一个 font-awesome 图标,为每篇文章声明一个自定义图标,例如,固定文章的
icon: fa-thumb-tack
。如果您想更改默认的文章类型(例如,将
article
文章类型的铅笔图标替换为另一个图标),请将原始内容类型文件复制到您网站的layouts/partials/content-type/
目录中并在那里进行编辑。否则,当您将主题更新到最新版本时,您的更改将被覆盖。
语法高亮
您文章中代码块的语法高亮使用 Hugo 内置的 Chrome 代码高亮器实现。您文章中代码块的高亮可以在站点级别或每个代码块进行自定义。
要在站点级别更改默认配置,请调整 hugo.toml
文件的 [markup.highlight]
部分中的属性。例如,您可以将默认的 monokai
样式更改为来自 Chroma Style Gallery 的样式。
每个代码块都可以个性化以下参数:linenos
、hl_lines
、linenostart
、anchorlinenos
、lineanchors
和 hl_inline
,例如
```java {linenos=inline, hl_lines=“7-12 21-26”}
// … 代码
```
阅读 Hugo 的文档以了解更多详细信息。
布局、颜色和字体
站点布局和样式使用 SCSS 以及仅用于依赖项管理的 npm 实现。布局、颜色和字体可以通过在 assets/sass/theme.scss
文件中定义的变量进行自定义。
例如,如果您想自定义 $base-color
变量,您应该在您网站的 hugo.toml
文件中定义 baseColor
参数。
$base-color: {{ .Param "baseColor" | default "#1d1f38" }};
[params]
baseColor = "#ff8080"
CSS 和 JS 模块
此主题支持热插拔 CSS 和 JavaScript 扩展,可以使用您网站的 hugo.toml
文件中的 css_modules
和 js_modules
列表参数指定。模块可以指定为相对于 static
目录(例如,exampleSite/static/custom.css
)或作为 URL。
[params]
css_modules = ["custom.css","//cdnjs.cloudflare.com/ajax/libs/cookieconsent2/3.1.0/cookieconsent.min.css"]
模块按照它们在列表中出现的顺序导入,并在默认的 Bilberry CSS 和 JS 文件之后立即处理。
Cookie 免责声明 (GDPR)
您可以使用 cookie 同意解决方案,通过加载所需的资源作为外部 CSS 和 JS 模块来添加 cookie 同意信息。
使用 cookie 同意网站上的配置器生成所需的初始化代码,并将其添加到本地 static/init-cookieconsent.js
文件中,例如
// https://cookieconsent.insites.com/download/#
window.addEventListener('load', function () {
window.cookieconsent.initialise({
'palette': {
'popup': {
'background': '#cc0033'
},
'button': {
'background': '#fff'
}
}
})
})
然后,您只需要修改 hugo.toml
文件即可加载本地初始化脚本和库。您可以下载文件并将它们放在您网站的 /static
目录中,也可以使用 CDN 直接引用它们。将这些文件存储在您的网站上可以减少外部依赖项、提高隐私并允许您在离线环境中开发您的网站。
css_modules = ["//cdnjs.cloudflare.com/ajax/libs/cookieconsent2/3.1.0/cookieconsent.min.css"]
js_modules = ["//cdnjs.cloudflare.com/ajax/libs/cookieconsent2/3.1.0/cookieconsent.min.js","init-cookieconsent.js"]
翻译
Bilberry 主题内置了对多语言网站的支持,目前支持 20 多种语言的翻译。
欢迎提交新语言翻译的请求或改进现有翻译!
鸣谢
Bilberry 主题的灵感来自 Anders Norén 创建的 WordPress 主题 Lingonberry。
Bilberry 是为出色的 HUGO 静态站点生成器设计的主题。
特别感谢 @Ipstenu 在这个主题中的帮助,该主题帮助创建了 Algolia 索引的 index.json
。
贡献者
非常感谢这些出色的人们。此项目遵循 all-contributors 规范。欢迎任何形式的贡献!
许可证
Bilberry Hugo 主题在 MIT 许可证下获得许可。