Hugo+Github Pages搭建静态网站作为个人博客(2)

发表于： 分类于：
字数： 3143 阅读：≈ 7分钟 浏览： 评论：
温馨提醒

上一篇博客中重点于Hugo的使用，这一篇着重于以Stack主题为例进行博客撰写。

Stack is a simple card-style Hugo theme designed for Bloggers. Here are some of the features: Stack 是一个简单的卡片式 Hugo 主题，专为 Blogger 设计。以下是一些功能：

  • Responsive images support 响应式图像支持
  • Lazy load images 延迟加载图像
  • Dark mode 深色模式
  • Local search 本地搜索
  • PhotoSwipe integration 照片滑动 集成
  • Archive page template 存档页面模板
  • Full native JavaScript, no jQuery or any other frameworks are used 完全原生 JavaScript，不使用 jQuery 或任何其他框架
  • No CSS framework, keep it simple and minimal 没有 CSS 框架，保持简单和最小化
  • Properly cropped thumbnails 正确裁剪的缩略图
  • Subsection support 分段支持
  • Table of contents 目录

Hugo网站文件结构

网站根目录下面的文件夹目录树一般如下所示：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

.
├── archetypes                  
│   └── default.md
├── hugo.yaml                 # 网站配置文件
├── content                   # 站点内的内容都在这里
│   ├── categories              # “分类”页面的首页
│   │   └── Test                # “分类”页面下的一个分类页面
│   ├── page                    # 显示在网站主页左侧边栏菜单的选项
│   │   ├── about               # 左侧边栏菜单中的“关于”页面
│   │   ├── archives            # 左侧边栏菜单中的“归档”页面
│   │   ├── links               # 左侧边栏菜单中的“链接”页面
│   │   └── search              # 左侧边栏菜单中的“搜索”页面
│   └── post                    # 用户写的帖子都放在这里，每个子文件夹对应一个帖子
│       ├── chinese-test
│       ├── emoji-support
│       ├── markdown-syntax
│       ├── math-typesetting
│       ├── placeholder-text
│       └── rich-content
├── data
├── layouts
├── LICENSE
├── README.md
├── resources
│   └── _gen
│       ├── assets
│       └── images
├── static                     # 放用户自定义字体、用户头像、网站小图标等
└── themes                     # 放各种主题
    └── hugo-theme-stack         # stack主题
        ├── archetypes
        ├── assets               #里面有个img存放头像图片位置
        ├── config.yaml          #stack主题的配置文件，优先级低于上面的网站配置文件
        ├── data
        ├── debug.sh
        ├── exampleSite
        ├── go.mod
        ├── i18n                 #多语言支持包
        ├── images               #网站示例的截图存放位置
        ├── layouts
        ├── LICENSE
        ├── netlify.toml
        ├── README.md
        └── theme.toml

主要修改主题内和网站内的config.yaml，具体含义可见 官方手册 。

此外，上面没有显示的是网站根目录下的private文件夹和public文件夹。

  • public文件夹会在运行hugo -D部署网站时生成，是暴露给外界的文件夹，网站上页面的HTML文件都会由Hugo生成并放在public文件夹下。public文件夹内不要放置任何包含用户信息的敏感文件！
  • private文件夹可以由用户创建，这里我们用它来存放网站的SSL证书。

关于网站根目录下各文件夹，更详细的说明可参见Hugo 官方文档 。

配置文件夹config

Hugo支持两种配置方式：

  • 一种是直接在网站根目录的.config文件中配置
  • 另一种是在网站根目录下创建config文件夹，配置放在config文件夹内

第二种配置方式支持将不同的配置项分开放在不同的文件中，相比第一种配置方式可以让配置项的条理更加清晰，因此我们这里选择第二种配置方式。参考配置目录结构如下所示：

1
2
3
4
5
6
7
8

config
  └── _default
      ├── config.yaml
      ├── languages.yaml
      ├── menu.en.yaml
      ├── menu.zh-cn.yaml
      ├── params.en.yaml
      └── params.zh-cn.yaml

关于Hugo的配置，更详细的说明可参考 官方文档 。

[附录1]主题内config.yaml各参数简明含义

  1. Module (模块设置)

    hugoVersion

    : 定义Hugo版本要求。

    • extended: 设置为true表示需要Hugo的扩展版本（支持SCSS和其他高级功能）。
    • min: 需要的最低Hugo版本为0.87.0。

  2. Params (参数设置)

    • mainSections: 定义主要的内容部分，这里是post，也就是文章部分。
    • featuredImageField: 文章中用于展示特色图片的字段名称，默认为image。
    • rssFullContent: RSS中是否提供文章的完整内容，true表示是。

  3. Favicon (网站图标)

    • favicon: 设置网站的favicon路径，如果有一个favicon.ico，可以设置为/favicon.ico。

  4. Footer (页脚)

    • since: 页脚中显示的年份（通常是网站开始的年份），这个字段为空，可以填入年份，如“2024”。
    • customText: 页脚自定义文本，当前为空，可以填写你想显示的内容。

  5. Date Format (日期格式)

    • published: 发布日期的显示格式，这里格式为Jan 02, 2006。
    • lastUpdated: 最后更新日期的显示格式，这里包括日期和时间。

  6. Sidebar (侧边栏)

    • compact: 是否使用紧凑布局，false表示不使用紧凑布局。

    • emoji: 表情符号，可以为空或者自定义一个表情符号显示在侧边栏上。

    • subtitle: 侧边栏的副标题，当前为空，可以添加文字。

    • avatar

      : 头像设置。

      • enabled: 是否显示头像，true表示显示。
      • local: true表示头像从本地文件加载。
      • src: 头像的路径为img/avatar.png。

  7. Article (文章设置)

    • headingAnchor: 设置是否在标题旁边显示锚点，false表示不显示。

    • math: 是否支持数学公式，false表示不支持。

    • toc: 目录设置，true表示显示文章目录。

    • readingTime: 是否显示阅读时间，true表示显示。

    • license

      : 文章版权设置。

      • enabled: 是否启用版权声明，false表示不启用。
      • default: 默认的版权声明，当前设置为“Creative Commons BY-NC-SA 4.0”，但没有启用。

  8. Comments (评论系统)

    • enabled: 是否启用评论，false表示不启用。
    • provider: 默认评论提供者是disqus。
    • 配置了多个评论系统，包括disqusjs, utterances, beaudar, remark42, vssue等。每个评论系统都有自己的设置项，例如Disqus、GitHub Issues（通过utterances）、Beaudar等。这些可以根据需要选择，并填入相关参数，如API密钥、仓库名称等。

  9. Widgets (小工具)

    • homepage: 主页上的小工具列表，当前为空，也就是说默认没有显示任何小工具。
    • page: 页面上的小工具列表，当前为空。

  10. OpenGraph (社交分享卡片)

    • twitter

      : 配置Twitter分享卡片。

      • site: 填写你的Twitter用户名。
      • card: 卡片类型，这里是summary_large_image，表示大图片的分享卡片。

  11. DefaultImage (默认图片)

    • opengraph

      : 配置默认图片的设置。

      • enabled: 是否启用OpenGraph图片，false表示不启用。
      • local: 图片是否为本地图片，false表示不是本地图片。
      • src: 默认图片的路径。

  12. ColorScheme (颜色主题)

    • toggle: 是否允许用户切换颜色主题（比如暗黑模式），true表示启用切换功能。
    • default: 默认颜色主题，这里是auto，表示根据用户系统的设置自动切换。

  13. ImageProcessing (图片处理)

    • cover: 是否启用封面图片处理，true表示启用。
    • content: 是否启用内容图片处理，true表示启用。

[附录2]官方示例提供的根目录内hugo.yaml各参数简明含义

基本信息

  • baseurl: 网站的基础URL。
  • languageCode: 默认语言代码，例如en-us表示英语（美国）。
  • theme: 使用的主题，在这里是hugo-theme-stack。
  • title: 网站的标题。
  • copyright: 网站的版权声明。

语言支持

  • DefaultContentLanguage: 设置默认的语言为英语（en）。
  • hasCJKLanguage: 如果网站主要使用中文、日文或韩文等CJK（中日韩）语言，这个值应设为true，用于正确处理文章摘要和字数统计。
  • languages: 你可以为网站配置多语言支持。在这个例子中，网站支持英语（en）、中文简体（zh-cn）和阿拉伯语（ar）。每种语言可以有独立的标题和描述。

服务设置

  • disqus: 用于网站评论的服务，Disqus是一个流行的评论系统。如果要启用评论，需要更改为你自己的网站短名称。
  • googleAnalytics: 如果你使用Google Analytics（谷歌分析）进行流量统计，可以在这里填入你的追踪ID。

分页和永久链接

  • pagination: 设置分页大小为3，也就是说每页显示3篇文章。
  • permalinks: 自定义文章和页面的永久链接结构。例如，文章会显示为/p/:slug/。

页面参数

  • params: 包含各种网站布局、显示和功能的配置。比如文章是否显示数学公式、阅读时间、许可信息等。

评论功能

  • comments: 你可以选择不同的评论提供者（如Disqus、Utterances、Gitalk等），通过填入相关的配置信息来启用评论。

菜单和小工具

  • menu: 自定义网站菜单和社交链接。这里包括GitHub和Twitter的社交图标链接。
  • widgets: 配置主页和页面上的小工具，例如搜索栏、文章归档、标签云等。

其他配置

  • opengraph: 配置网站在社交平台（如Twitter）的分享卡片。
  • colorScheme: 配置网站的颜色模式（自动、浅色或深色）。
  • imageProcessing: 图片处理选项，例如封面图片和内容图片。

相关内容

  • related: 配置文章之间的相关性推荐，基于标签和分类等条件。

Markdown 渲染

  • markup: 配置如何处理Markdown内容，例如表格、代码高亮、目录等。

两篇附录仅供参考，可能有错误