Hugo 主题
Poison
一个务实的 Hugo 博客主题。基于 mdo 的经典“Hyde”设计。
Poison
演示 - https://poison.lukeorth.com/
Poison 是一款简洁、专业的 Hugo 主题,旨在吸引您的读者。
它也很小巧且注重隐私,没有外部依赖项。没有 JavaScript 框架、图标包或 Google 字体。没有广告或跟踪器污染您的控制台窗口。我们保持简单。一点原生 JavaScript、一点 CSS 和 Hugo 的强大功能。
该网站的所有静态资源(JS 文件、CSS 和字体)都位于主题的 /assets/ 目录中。这样您就知道确切有什么进入您的网站。
查看我们演示网站的分析,以评估社区对该主题的兴趣。
目录
- Poison
- 演示 - https://poison.lukeorth.com/
- 目录
- 功能
- 浅色和深色模式
- 目录
- 评论
- 分析
- 电子邮件新闻简报
- 系列
- KaTeX
- 选项卡
- 美人鱼图表
- PlantUML 图表
- 详情
- 安装
- 如何配置
- 侧边栏菜单
- 首页
- 配置示例
- 自定义 CSS
- 建议/贡献
- 作者
- 移植者
- 许可证
功能
除了 Hugo 自带的标准内置模板和短代码外,Poison 还提供了一些自己独特的功能。
浅色和深色模式
让读者可以选择以浅色或深色模式阅读。用户的偏好存储在本地存储中。首次访问者默认为浅色模式,但您可以在配置文件中更改此设置。
目录
为屏幕足够大的读者(即屏幕宽度 > 1600 像素)提供浮动目录。
如果您不想显示目录,可以在 config.toml
文件中禁用整个站点的目录。
[params]
hideToc: true
或者,您也可以选择在单个帖子的 frontmatter 中设置标志来禁用每个帖子的目录。
---
title: "Example to demonstrate how to hide the table of contents on a single post"
date: 2023-07-10
draft: false
hideToc: true
tags: ["Hugo"]
---
评论
允许用户评论您的帖子,从而促进讨论。Poison 目前为此目的支持两种不同的评论引擎 - Disqus 和 Remark42。
注意:启用评论将添加外部依赖项。
- Disqus 演示网站
- Remark42 演示网站
Disqus 是免费且易于使用的。请查看 Hugo 文档以开始使用。创建 Disqus 帐户后,您可以通过在 config.toml
文件中添加一行代码来在 Poison 主题中激活它。
disqusShortname = 'yourDisqusShortname'
对于不想费心自己托管评论引擎的人来说,这是一个很好的选择;但是,它也有一些缺点。由于 Disqus 免费提供此服务,他们会通过在您的网站上注入第三方广告跟踪器来弥补任何经济损失。这些跟踪器有助于收集和出售有关您用户的信息,同时也对您网站的速度产生负面影响。
即便如此,Disqus 可能仍然是根据您的情况的最佳解决方案。以上段落仅旨在强调其优缺点,而不是完全不鼓励使用它。
Remark42 是一个轻量级的开源评论引擎,不会监视您的用户。缺点是您必须自己托管它。请查看 Remark42 文档以开始使用。我还发现这篇博文在我的网站上设置它时很有帮助。
一切设置完成后,您可以通过在 config.toml
文件的 [params]
部分中包含以下内容来在 Poison 主题中激活它。
[params]
remark42 = true
remark42_host = "https://yourhost.com"
remark42_site_id = "your_site_id"
分析
了解您的用户。Poison 目前支持 Plausible,可通过付费服务或自托管获得。请查看 Poison 演示网站的
注意:启用分析将添加外部依赖项。
在此处查看我们演示网站的 Plausible 分析!
建立 Plausible 实例后,您可以通过在 config.toml
文件中添加三行代码来激活它。
[params]
plausible = true
plausible_domain = "myblog.com"
plausible_script = "https://plausible.myblog.com/js/script.js"
这将在每个页面的 <head>
中插入必要的代码,并允许您的 Plausible 实例收集有关您的用户的有限数据。
作为参考,上面的配置会将以下代码添加到每个页面。根据您的具体环境进行调整。
<script defer data-domain="myblog.com" src="https://plausible.myblog.com/js/script.js"></script>
电子邮件新闻简报
允许用户通过电子邮件订阅您的博客新闻简报。Poison 目前支持 Listmonk,可通过自托管获得。Listmonk 是一个独立的、自托管的、新闻简报和邮件列表管理器。缺点是您必须自己托管它。请查看 Listmonk 文档以开始使用。
建立 Listmonk 实例后,通过在 config.toml
文件中添加以下代码来激活它。
[params]
listmonk = true
listmonk_host = "https://listmonk.your_domain.tld"
listmonk_subscription_list_uiid = "YOUR_NEWSLETTERS_LIST_UIID"
listmonk_subscription_form_text = "Subscribe to my newsletters" # default: Subscribe to my newsletters
listmonk_subscription_success_message = "Thanks for subscribing" # default: Thanks for subscribing
listmonk_subscription_error_message = "Something went wrong" # default: Sorry, something went wrong. Please, try again
这将在每个帖子内容的底部插入一个表单。用户将订阅 listmonk_subscription_list_uiid
参数中指定的新闻简报。
系列
将内容合理地链接并显示到“系列”中(即教程一、教程二等)。
这是通过自定义分类法完成的,因此只需将 series
添加到您要分组的内容的 frontmatter 中即可。
---
title: "Example to demonstrate how to use series"
date: 2022-10-04
draft: false
series: "How to use poison"
tags: ["Hugo"]
---
KaTeX
让您的数学符号更突出。
对于应出现在单独一行的符号,请使用块引用 $$ ... $$
$$ 5 \times 5 = 25 $$
对于应出现在同一行的符号,请使用内联引用 $ ... $
注意:启用 KaTeX 将添加外部依赖项。
选项卡
某些内容以选项卡的形式查看会更好。幸运的是,我们有一个短代码来实现此目的。
这是上面显示的选项卡的代码...
{{</* tabs tabTotal="2" */>}}
{{%/* tab tabName="First Tab" */%}}
This is markdown content.
{{%/* /tab */%}}
{{</* tab tabName="Second Tab" */>}}
{{</* highlight text */>}}
This is a code block.
{{</* /highlight */>}}
{{</* /tab */>}}
{{</* /tabs */>}}
美人鱼图表
您可以嵌入渲染的美人鱼图表。
注意:启用美人鱼图表将添加外部依赖项。
有关如何执行此操作的示例,请访问 Poison 演示网站。
PlantUML 图表
你可以嵌入渲染后的 PlantUML 图表。
注意: 启用 PlantUML 图表会增加外部依赖。
有关如何操作的示例,请访问 Poison 演示站点;
详情
这里有一个用于将详细信息下拉菜单编码到页面中的简码。
这是上面详细信息下拉菜单的代码
{{</* details summary="A detail dropdown" */>}}
Markdown content
{{</* /details */>}}
安装
首先,将此存储库克隆到您的 themes
目录中
git clone https://github.com/lukeorth/poison.git themes/poison --depth=1
接下来,通过添加以下行在您的 config.toml 文件中将 poison
指定为默认主题
theme = "poison"
最后,如果此存储库将来有任何您希望包含在本地副本中的更新,可以通过运行以下命令检索这些更新
cd themes/poison
git pull
有关如何开始使用 Hugo 和主题的更多信息,请阅读官方快速入门指南。
如何配置
成功安装 Poison 后,最后一步是进行配置。
侧边栏菜单
您希望在侧边栏菜单中显示的任何项目必须满足两个要求。它们必须
- 在您的 /content/ 目录中有一个对应的 markdown 文件。
- 在您的 config.toml 文件中声明(如下例所示)。
有两种类型的菜单项
- 单页 – 左侧的关于菜单项就是一个很好的例子。它显示一个指向单个页面的直接链接。对于任意单页,页面内容必须位于
content/<foo>/_index.md
,并且_index.md
的 front matter 必须包含layout: single
。 - 列表 – Posts 菜单项就是一个很好的例子。它显示一个目录,并动态列出其中包含的内容(即页面),并按日期排序。列表项有两个可选配置:一个子标题(如左侧菜单上出现的最近子标题)和一个要显示的最大项目数。
侧边栏菜单项在您的 config.toml 文件中使用字典值进行配置。我已在下面包含一个示例。此外,在下一节中显示的 config.toml 文件中为此提供了一个占位符。
重要提示:您必须在指定路径存在一个 markdown 文件,才能显示您的菜单项。
menu = [
# Dict keys:
# Name: The name to display on the menu.
# URL: The directory relative to the content directory.
# HasChildren: If the directory's files should be listed. Default is true.
# Limit: If the files should be listed, how many should be shown.
# SINGLE PAGE
# Note that you must put your markdown file
# inside of a directory with the same name.
# Example:
# ... /content/about/about.md
{Name = "About", URL = "/about/", HasChildren = false},
# ... /content/foo/_index.md
# {Name = "Foo", URL = "/foo/", HasChildren = false},
# LIST
# This example has a subheading of "Recent"
# and will display up to 5 items.
# Example:
# ... /content/posts/introducing-poison.md
{Name = "Posts", URL = "/posts/", Pre = "Recent", HasChildren = true, Limit = 5},
# Example of a list without a subheading or limit.
{Name = "Projects", URL = "/projects/"},
]
首页
当访问站点的基本 URL 时,例如 your.domain.com/
,会按时间倒序显示最近添加内容的带分页的提要。默认情况下,仅显示 “posts” 页面包中的内容。您可以通过将 front_page_content
参数添加到 config.toml 文件中,来配置要在此页面中包含的页面包名称列表。
[params]
front_page_content = ["posts", "projects"]
示例配置
我建议首先将以下代码复制/粘贴到您的 config.toml 文件中。一旦您看到它的外观,请根据需要调整设置。
注意:要在侧边栏中显示图像,您需要取消注释 remote_brand_image
并设置图像 URL,或取消注释下面的 brand_image
路径,并使其指向项目中的图像文件。该路径相对于 static
目录。如果您没有图像,只需将这两行都注释掉即可。
baseURL = "/"
languageCode = "en-us"
theme = "poison"
paginate = 10
pluralizelisttitles = false # removes the automatically appended "s" on sidebar entries
# NOTE: If using Disqus as commenting engine, uncomment and configure this line
# disqusShortname = "yourDisqusShortname"
[params]
brand = "Poison" # name of your site - appears in the sidebar
# remote_brand_image = 'https://github.com/USERNAME.png' # path to a remote file
# brand_image = "/images/test.jpg" # path to the image shown in the sidebar
description = "Update this description..." # Used as default meta description if not specified in front matter
dark_mode = true # optional - defaults to false
# favicon = "favicon.png" # path to favicon (defaults to favicon.png)
front_page_content = ["posts"] # Equivalent to the default value, add page bundle names to include them on the front page.
# MENU PLACEHOLDER
# Menu dict keys:
# Name: The name to display on the menu.
# URL: The directory relative to the content directory.
# HasChildren: If the directory's files should be listed. Default is true.
# Limit: If the files should be listed, how many should be shown.
menu = [
{Name = "About", URL = "/about/", HasChildren = false},
{Name = "Posts", URL = "/posts/", Pre = "Recent", HasChildren = true, Limit = 5},
]
# Links to your socials. Comment or delete any you don't need/use.
discord_url = "https://discord.com"
email_url = "mailto://user@domain"
facebook_url = "https://facebook.com"
flickr_url = "https://flickr.com"
github_url = "https://github.com"
gitlab_url = "https://gitlab.com"
instagram_url = "https://instagram.com"
linkedin_url = "https://linkedin.com"
mastodon_url = "https://mastodon.social"
matrix_url = "https://matrix.org"
telegram_url = "https://telegram.org"
tryhackme_url = "https://tryhackme.com"
twitter_url = "https://twitter.com"
x_url = "https://x.com"
xmpp_url = "https://xmpp.org"
youtube_url = "https://youtube.com"
signal_url = "https://signal.org"
bluesky_url = "https://bsky.app"
# NOTE: If you don't want to use RSS, comment or delete the following lines
# Adds an RSS icon to the end of the socials which links to {{ .Site.BaseURL }}/index.xml
rss_icon = true
# Which section the RSS icon links to, defaults to all content. See https://gohugo.com.cn/templates/rss/#section-rss
rss_section = "posts"
# Hex colors for your sidebar.
moon_sun_background_color = "#515151" # default is #515151
moon_sun_color = "#FFF" # default is #FFF
sidebar_a_color = "#FFF" # default is #FFF
sidebar_bg_color = "#202020" # default is #202020
sidebar_h1_color = "#FFF" # default is #FFF
sidebar_img_border_color = "#515151" # default is #515151
sidebar_p_color = "#909090" # default is #909090
sidebar_socials_color = "#FFF" # default is #FFF
# Hex colors for your content in light mode.
code_color = "#000" # default is #000
code_background_color = "#E5E5E5" # default is #E5E5E5
code_block_color = "#FFF" # default is #FFF
code_block_background_color = "#272822" # default is #272822
content_bg_color = "#FAF9F6" # default is #FAF9F6
date_color = "#515151" # default is #515151
link_color = "#268BD2" # default is #268BD2
list_color = "#5A5A5A" # default is #5A5A5A
post_title_color = "#303030" # default is #303030
table_border_color = "#E5E5E5" # default is #E5E5E5
table_stripe_color = "#F9F9F9" # default is #F9F9F9
text_color = "#222" # default is #222
# Hex colors for your content in dark mode
code_color_dark = "#FFF" # default is #FFF
code_background_color_dark = "#515151" # default is #515151
code_block_color_dark = "#FFF" # default is #FFF
code_block_background_color_dark = "#272822" # default is #272822
content_bg_color_dark = "#121212" # default is #121212
date_color_dark = "#9A9A9A" # default is #9A9A9A
link_color_dark = "#268BD2" # default is #268BD2
list_color_dark = "#9D9D9D" # default is #9D9D9D
post_title_color_dark = "#DBE2E9" # default is #DBE2E9
table_border_color_dark = "#515151" # default is #515151
table_stripe_color_dark = "#202020" # default is #202020
text_color_dark = "#EEE" # default is #EEE
# NOTE: If using Remark42 as commenting engine, uncomment and configure these lines
# remark42 = true
# remark42_host = "https://yourhost.com"
# remark42_site_id = "your_site_id"
# NOTE: The following three params are optional and are used to create meta tags + enhance SEO.
# og_image = "" # path to social icon - front matter: image takes precedent, then og_image, then brand_url
# this is also used in the schema output as well. Image is resized to max 1200x630
# For this to work though og_image and brand_url must be a path inside the assets directory
# e.g. /assets/images/site/og-image.png becomes images/site/og-image.png
# publisher_icon = "" # path to publisher icon - defaults to favicon, used in schema
[taxonomies]
series = 'series'
tags = 'tags'
自定义 CSS
您可以通过添加自己的 /assets/css/custom.css
文件来覆盖 Poison 静态 CSS 文件中的任何设置。例如,如果您想覆盖标题字体和字体大小,您可以添加以下内容
.sidebar-about h1 {
font-size: 1.4em;
font-family: "Monaco", monospace;
}
建议/贡献
请随时通过在 GitHub 中开启新 issue 来添加新功能的建议。
向这些主要贡献者致以衷心的感谢
- Darius Makovsky (traveltissues)
- Pierre Bourdon (delroth)
- Karl Austin (KarlAustin)
- Diogo Almeida (Diogo-Almeida3)
- Ayden Holmes (eyegog)
作者
Mark Otto
- https://github.com/mdo
- https://twitter.com/mdo
移植者
Luke Orth
- https://github.com/lukeorth
许可证
在 GNU General Public License v3.0 下开源。