Hugo 主题

上一个/下一个: 所有主题

Hugo-Octopress

为 Hugo 打造的 Octopress 经典主题

  • 作者: Parsia Hakimian
  • GitHub 星数: 158
  • 更新时间: 2024-09-09
  • 许可协议: MIT
下载
Hugo-Octopress

Hugo-Octopress

Hugo-Octopress 是将经典 Octopress 主题移植到 Hugo 的版本。

使用未修改主题的实时演示

  • http://hugo-octopress-test.s3-website-us-east-1.amazonaws.com/.
  • 源代码: https://github.com/parsiya/Hugo-Octopress-Test.

我的个人网站采用紧凑索引 (见下文)

  • https://parsiya.net.
  • 源代码: https://github.com/parsiya/parsiya.net

目录

  • 快速入门
  • 配置
  • 代码高亮
  • Goldmark 与 Blackfriday Markdown 引擎
  • CSS 覆盖
  • 导航菜单
  • 扩展页眉和页脚
  • 侧边栏
    • 侧边栏文本
    • 社交网络图标
    • 侧边栏菜单
    • 最近的文章
  • Shortcodes
    • 代码标题
    • 图片标题
    • 目录
  • 页面
    • 许可页面
    • 未找到或 404.html
    • 分类页面
    • 单独页面
  • 目录
    • toc 配置
    • 在前言中使用 toc
    • 使用 toc Shortcode
    • 编辑器插件
  • Disqus
  • Twitter 卡片
  • 紧凑索引
  • mainSections
  • 自定义网站图标
  • 故障排除
    • Hugo 页面摘要错误
    • 主页上的空帖子链接
  • 问题/待办事项
  • 归属
  • 移植者
  • 主题许可

screenshot

快速入门

将主题添加到您现有的网站或 Hugo 的快速入门。所有命令都从您网站的根目录运行。

如果使用 git 管理您的网站，请将主题添加为 git 子模块

git submodule add https://github.com/parsiya/Hugo-Octopress themes/Hugo-Octopress

或者您可以克隆它

git clone https://github.com/parsiya/Hugo-Octopress themes/Hugo-Octopress

要查看带有示例网站的主题

cd themes/Hugo-Octopress/
hugo serve -vw --source=exampleSite

并在 https://127.0.0.1:1313 查看示例网站。

示例网站最初由 https://github.com/nonumeros 创建。我查看了将近两年后的拉取请求，并且不得不复制/粘贴该网站，而不是解决合并冲突。示例网站还有一个包含主题 shortcodes 的页面。

配置

可以通过修改配置文件中的参数来配置 Hugo-Octopress。sample-config.toml 和 exampleSite/config.toml 都是可行的示例。

代码高亮

此主题使用内置的 Chroma 高亮器和 solarized-dark 主题。请参阅 https://xyproto.github.io/splash/docs/all.html 中的所有支持样式。要更改样式，请在配置文件中将其更改为以下支持的样式之一。

一些控制代码高亮版本 0.60 之后版本的选项。

[markup]
  [markup.tableOfContents]
    endLevel = 8
    startLevel = 1
  [markup.highlight]
    style = "solarized-dark"

有关更多配置选项，请参阅 Hugo 文档中的 https://gohugo.com.cn/getting-started/configuration-markup/#highlight 和 https://gohugo.com.cn/extras/highlighting/。

Goldmark 与 Blackfriday Markdown 引擎

在 0.60 版本之前，Hugo 使用 Blackfriday。现在默认使用 Goldmark。请参阅 https://gohugo.com.cn/getting-started/configuration-markup#highlight 以获取有关设置的信息。

存在一些权衡。主要是 hrefTargetBlank Blackfriday 扩展。它设置为 true，以在新浏览器选项卡中打开外部链接。不幸的是，Goldmark 没有内置此功能。要实现此目的，我们需要使用渲染挂钩。我使用了 Hugo 文档中的

https://gohugo.com.cn/getting-started/configuration-markup#link-with-title-markdown-example.

这适用于 Markdown 链接，但不适用于 linkify 或图片链接。Linkify 链接是粘贴到文档中的直接 URL（例如，https://example.net）。一种解决方法是不使用与此类似的链接（无论如何，这也不在 markdown 标准中），而是使用普通链接。例如，[example.net](https://example.net) 或引用链接。

您可以像这样继续使用 Blackfriday

[markup]
  defaultMarkdownHandler = "blackfriday"
  [markup.blackFriday]
    hrefTargetBlank = true

CSS 覆盖

您可以覆盖内置 CSS 并添加您自己的 CSS。将 CSS 文件放在您网站的 static 目录中。虽然将它们存储在 themes/Hugo-Octopress/static 目录中有效，但不建议这样做（尽量将您的网站和主题分开，以便能够轻松切换主题）。然后修改 customCSS 参数。该路径应相对于 static 文件夹。这些 CSS 文件将在内置 CSS 文件之后通过 header partial 添加。

例如，如果自定义 CSS 文件为 static/css/custom.css 和 static/css/custom2.css，则 customCSS 将如下所示

[params]
  customCSS = ["css/custom.css","css/custom2.css"]

可以自定义导航菜单中的链接（Google 搜索和 RSS 图标之外的所有内容）。导航菜单是使用 layouts/partials/navigation.html partial 生成的。

默认情况下，导航菜单链接将在同一窗口中打开。您可以通过将 navigationNewWindow 参数设置为 true 来更改此行为。指向根 ("/") 的链接将始终在同一窗口中打开。目前，Hugo 不支持向菜单添加自定义属性。

链接按照权重从左到右排序。例如，权重为 -10 的链接将显示在权重为 0 或 10 的链接的左侧。可以将链接添加到配置文件

[[menu.main]]
  Name = "Blog"
  URL = "/"
  weight = -10

[[menu.main]]
  Name = "The other guy from Wham!"
  URL = "https://www.google.com/search?q=andrew+ridgeley"
  weight = -5

[[menu.main]]
  Name = "This theme - add link"
  URL = "https://www.github.com"

[params]
  # If set to true, navigation menu links will open in a new window with the exception of links to root ("/")
  # If this item does not exist or is set to false, then navigation menu links will open in the same window
  navigationNewWindow = true

搜索引擎自定义

[params]
  searchEngineURL = "https://www.google.com/search"

扩展页眉和页脚

将这些文件从 theme/Hugo-Octopress/layouts/partials/ 复制到 your-site/layouts/partials 并修改它们

  • extend_header.html：所有内容都将添加到每个页面上的 head 标签的末尾。
  • extend_footer.html：所有内容都将添加到每个页面上 footer 标签之后。

侧边栏有四个部分，从上到下

  • 侧边栏标题和文本（可选）。
  • 社交网络图标（可选）：指向 GitHub、Mastodon 等的图标和链接。
  • 侧边栏菜单（可选）：侧边栏中的链接。
  • 最近的文章：显示最后 X 篇文章（默认为 5）。

侧边栏是使用 layouts/partials/sidebar.html 中的 partial 生成的。

侧边栏文本

侧边栏文本分为两部分，都可以配置。两者都传递给 markdownify，因此您可以使用 markdown（例如，添加链接或新行）。

  • 侧边栏标题首先出现在 <h1> 标签中。可以使用 sidebarHeader 进行配置。
  • 侧边栏文本出现在标题下方，位于 sidebarText 中。

可以通过在行末尾添加两个空格来添加新行。可以通过两个空行来添加新段落。添加两个新行时，请记住删除缩进，否则新行将被视为代码块。

sidebarHeader = "Sidebar Header"

sidebarText = """Here's a [link to google](https://www.google.com)

New paragraph

Another paragraph which has two spaces in the end to create a new line using markdown  
New line but not a new paragraph
"""

如果您想在此处使用 </br> 而不仅仅是 markdown，则需要在 Goldmark 中启用 HTML 的不安全渲染。您可以像这样操作。

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

Blackfriday 渲染 </br> 标签，并且不需要额外的配置。

社交网络图标

侧边栏社交网络图标配置如下：

[params]
  github = "https://github.com/parsiya/Hugo-Octopress/"
  bitbucket = ""
  gitlab = ""
  twitter = ""
  keybase = ""
  linkedin = ""
  mastodon = ""
  stackoverflow = ""
  youtube = ""
  facebook = ""
  instagram = ""
  bitcoin = ""

图标顺序不幸地被硬编码了。要修改，请复制 your-website/themes/Hugo-Octopress/layouts/partials/social.html 到 your-website/layouts/partials/social.html 并修改顺序。使用 </br> 创建新行。

显示链接的代码（以及使用这些图标的想法）来自 Hyde-x。

图标来自 Font Awesome 和 Fork Awesome。要使用带有方形深色背景的图标，请添加 -square。例如，<i class="fa fa-twitter-square fa-3x"></i>。大小可以是 1 到 5，使用 fa-lg 使它们具有自适应性。

可以通过将 sidebarMenuEnabled 设置为 true 来启用此菜单。它有两个部分：

  • 一个出现在顶部的 <h1> 标签内的标题。可以通过 sidebarMenuHeader 设置。这部分仅支持文本。
  • 一组链接。可以通过使用 [[menu.sidebar]] 标签，以类似于导航菜单项的方式配置它们。将 sidebarNewWindow 设置为 true 以在新窗口中打开这些链接。
[[menu.sidebar]]
  Name = "Google"
  URL = "https://www.google.com"
  weight = 0

[[menu.sidebar]]
  Name = "Hugo"
  URL = "/categories/hugo/"
  weight = 1

最近的文章

最后 x 篇文章可以显示在侧边栏中。此数字由 sidebarRecentLimit 控制。要隐藏此部分，您可以从配置文件中删除 sidebarRecentLimit 或将其设置为零。

短代码

在 Hugo 中创建短代码非常容易，这也是我切换到它的原因之一。我重新创建了 Octopress 中的一些插件。它们为代码块和图像添加标题。这些短代码位于 layouts/shortcodes/ 中。

对于我所有的 Hugo 短代码，请参阅 https://github.com/parsiya/Hugo-Shortcodes。

代码标题

此短代码向代码块添加标题。代码块被包裹在 <figure> 标签中，并使用 <figcaption> 添加标题。它有两个参数，title 是代码块的标题，lang 是传递给 Hugo 的 highlight 函数的语言，以及 linenos=true 以启用行号。

用法和源代码（参数是命名的，而不是位置性的）

{{< codecaption lang="html" title="Code caption shortcode" >}}
<figure class="code">
  <figcaption>
    <span>{{ .Get "title" }}</span>
  </figcaption>
  <div class="codewrapper">
    {{ highlight .Inner (.Get "lang") "linenos=true" }}
  </div>
</figure>
{{< /codecaption >}}

看起来像

picture.

如果标签内的代码溢出，则会在表格中添加水平侧边栏。我花了一段时间才实现这一点，因为 highlight 函数创建了超出我控制的表格。来自 highlight 的输出被包裹在 <div class="codewrapper"> 中，并且滚动条将添加到整个 div 中。CSS 文件中的以下内容（从第 2225 行开始）启用了此行为：

div.codewrapper {
    overflow-x: auto;
    overflow-y: hidden;
    background-color: #002B36;
}

图像标题

此短代码向图片添加标题。由于原始 CSS 文件的组织方式，此短代码不使用 <figure> 和 <figcaption>。Alt 标签也设置为 title。

用法（参数是命名的，而不是位置性的）

{{< imgcap title="Sample caption" src="/images/2016/thetheme/1.png" >}}

结果

<span class="caption-wrapper">
  <img class="caption" src="/images/2016/thetheme/1.png" title="Sample caption" alt="Sample caption">
  <span class="caption-text">Sample caption</span>
</span>

目录

此短代码向主题添加目录。您可以使用它将 toc 添加到页面中的任何位置，使用 {{< toc >}}。

页面

本节讨论主题支持的不同类型的页面。

许可页面

许可页面的地址是 baseurl/license/。在 content 下创建一个包含许可页面文本的 markdown 文件，并在 frontmatter 中将其类型设置为 license。

---
title: "License"
type: license
---

License text

许可页面模板是：layouts/license/single.html。

未找到或 404.html

404.html 页面有两个可选参数，并且都支持 markdown。

  • notFoundHeader：404 页面标题
  • notFoundText：404 页面文本

如果它们未在配置文件中设置，则使用主题的默认页面 (layouts/404.html)。

分类页面

您可以创建分类列表（例如，类别和标签）。设置 generateTaxonomyList = true 以在 baseURL/tags/ 和 baseURL/categories 生成它们。默认情况下，项目按计数排序。sortTaxonomyAlphabetical = true 将排序更改为按字母顺序排列。

[Params]
  generateTaxonomyList = true

  # Alphabetical sort
  # sortTaxonomyAlphabetical = true

要还原，请删除 sortTaxonomyAlphabetical 或将其设置为 false。

注意：从 Hugo 0.33 开始，indexes 已被删除。如果您的分类页面未呈现，请更新到最新版本的 Hugo。模板现在位于：

  • /layouts/category/category.html
  • /layouts/tag/tag.html

单独页面

您可以通过至少两种方式创建单独的页面：

  • 在 content/page 中创建一个新的内容文件。
  • 在 content 内的任何位置创建一个页面，并在 frontmatter 中将类型设置为 page。例如，type: page。

单独页面的模板位于 Hugo-Octopress/layouts/page/single.html。可以通过网站的 layouts/page/single.html 中的文件覆盖它。有关更多信息，请参阅 Hugodocs 中的单页模板。

目录

有三种方法可以将 目录 (ToC) 添加到页面。

toc 配置

使用 Goldmark，您需要在站点的配置中更改目录渲染器的默认值。默认值仅渲染 markdown 标题级别 2 和 3。

[markup]
  [markup.tableOfContents]
    endLevel = 8
    startLevel = 1

请在 https://gohugo.com.cn/getting-started/configuration-markup/#table-of-contents 查看更多信息。

在 Frontmatter 中使用 toc

此 ToC 位于页面顶部，不显示在摘要中。您可以自定义每个页面或全局的 ToC：

  1. 在文章/页面的 frontmatter 中添加一个名为 toc 的变量，并将其设置为 true。

    title: "title"
date: 2016-04-01T20:22:37-04:00
draft: false
toc: true

  2. 通过将 [Params] 下的 tableOfContents 设置为 true 来全局启用它。

    [Params]
  tableOfContents = true

frontmatter 中的 toc 变量具有优先级。如果将其设置为 false，则该页面的全局设置将被忽略。

使用 toc Shortcode

如果您希望目录出现在不同的位置，请使用 shortcode。例如，在我网站的速查表上，它出现在摘要之后。

---
frontmatter
---

summary or whatever.

{{< toc >}}

编辑器插件

有各种编辑器插件可以使用 Markdown 链接在 Markdown 中创建目录。这种方法是自包含的，不依赖于主题或 shortcode。我使用了 VS Code 插件 Markdown All in One。

Disqus

Hugo 支持 Disqus。请注意，Disqus 短名称直接在配置文件中。至少在 v0.134.0 版本中，位置已更改，旧位置将在不久后被弃用。目前（在 v0.135.0 之前），主题仍然支持此位置，但如果您想继续使用最新的 Hugo 版本，则应切换到新位置。

参考: https://gohugo.com.cn/content-management/comments/#configure-disqus。

# new location
# [services]
#  [services.disqus]
#    shortname = "Your disqus shortname"

# old one.
disqusShortname = "whatever"

您可以通过在 frontmatter 中添加 comments: false 来禁用个别页面的评论。

Twitter 卡片

可以在配置文件中的 Params 下启用 Twitter 卡片支持

[params]
  # Twitter card config
  # Enable.
  twitterCardEnabled = true
  # Don't include the @.
  # twitterCardSite = 
  twitterCardDomain = "parsiya.net"
  # Don't include the @.
  twitterCardAuthor = "CryptoGangsta"

启用 Twitter 卡片后，您可以使用 twitterImage 在 front matter 中向您的帖子添加摘要图像

twitterImage: 02-fuzzer-crash.png

注意： 图像 URL 应相对于页面，否则最终 URL 将不正确。简而言之，图像 URL 应为页面包的一部分。在本例中，index.md 和 02-fuzzer-crash.png 都位于同一根目录中。如果图像位于页面包的子目录中，则可以像这样添加：

twitterImage: images/02-fuzzer-crash.png

要修改此模板，请将 your-website/themes/Hugo-Octopress/layouts/partials/custom_twitter_card.html 复制到 your-website/layouts/partials/custom-twitter-card.html 并进行更改。

紧凑索引

原始主题在主页上呈现每个帖子的摘要。我更喜欢更紧凑的索引，并将其用于我自己的网站。您可以通过将其添加到配置文件中来启用它

[params]
  # Set to true to enable compact index. Set to false or remove to go back to classic view.
  compactIndex = true

比较视图（经典 - 紧凑） - 单击查看全尺寸图像

classic index compact index

mainSections

Hugo-Octopress 支持使用配置文件中的 mainSections 属性在主页上显示不同类型的帖子。如果未定义，则 mainSection 将默认为页面数最多的部分。在 Vanilla Hugo-Octopress 设置中，它将在 post 下。但是，您可以在配置文件中添加自己的部分

[params]
  mainSections = ["posts", "blogs"]

请参阅 layouts/partials/classic_index.html 中的代码

<div class="blog-index">
  {{ $paginator := where site.RegularPages "Type" "in" site.Params.mainSections | .Paginate }}
  {{ range $paginator.Pages }}
  <article>
  ...

自定义 Favicon

该主题使用默认的 Octopress favicon。您可以修改它

  1. 将 favicon 添加到配置文件中的 params 下。此路径相对于 static 目录。
    [params]
  favicon = "myicon.png"
  2. 将文件存储在 您的站点 的静态目录中：your-site/static/myicon.png。

故障排除

处理主题时遇到的常见问题。

Hugo 页面摘要错误

没有摘要分隔符 `

，Hugo 使用帖子的前 70 个单词。结果通常不太美观，并且包含原始 HTML。始终在您的帖子中使用摘要分隔符 `。如果您使用紧凑索引，则这无关紧要，因为它不使用摘要。

如果链接也不在摘要分隔符之前，则 Hugo 不会在页面摘要中显示渲染样式链接。您可以在此处阅读更多信息。

引用样式链接如下所示

This is a link to [Example][example-link].

[example-link]: https://www.example.com

有两种解决方法

  1. 不要在摘要中使用引用样式链接。使用普通链接，例如 [示例](https://www.example.com)。
  2. 将引用链接放在摘要分隔符之前。

使用 Hugo 0.57 重建博客后，您可能会在经典索引中看到一个 Posts 链接。更新到 Hugo 0.57.2+ （0.57.1 版本存在问题），它应该可以正常工作。

有关更多信息，请参阅

  • https://github.com/gohugoio/hugoThemes/issues/682

这应该不再是问题，因为主题的最低 Hugo 版本已提高。

问题/TODO

如果您发现任何问题/错误或需要新功能，请使用 GitHub 问题跟踪器。请记住，开发已经有一段时间不是我的日常工作了，我可能在修复问题时会比较慢（如果我问您有关详细信息，请不要感到惊讶）。

css 是一团糟。 CSS 文件直接取自经典的 Octopress 主题。我发现更容易的做法是修改模板以生成类似于 Octopress 输出的 HTML 代码，并使用现有的 CSS 文件。它很庞大（大约 53KB 和 2300 行），并且可能包含从未使用的元素的代码（也包含重复项）。

归属

  • Octopress 由 Brandon Mathis 创建。Octopress 源代码可以在 https://github.com/imathis/octopress 上找到。
  • 一些代码取自 Andrei Mihu 的 Hyde-x Hugo 主题。
  • 侧边栏图标来自 Dave Gandy 和 Fork Awesome 的 Font Awesome。
  • 特别感谢贡献者和所有在问题上提供帮助的人。

移植者：

由 Parsia 移植。

主题许可证

在 MIT 许可证下开源。