全栈开发日记

Hugo快速入门，看这一篇就够了

2025-02-06 | 8 分钟阅读 | 分类： HUGO

Hugo：用markdown生成静态网站。不瞒你说，本站就是用Hugo生成的。

准备

在开始之前，你需要掌握以下技能：

  • markdown
  • 命令行

你需要安装

快速体验Hugo

创建项目并运行

官方的快速开始中写道：

hugo new site quickstart
cd quickstart
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
echo "theme = 'ananke'" >> hugo.toml
hugo server

在命令行中执行这些代码，即可得到一个hugo网站，可以从浏览器中访问 http://localhost:1313/ 查看。

  • hugo new site quickstart，创建一个名为quickstart的项目
  • cd quickstart，进入quickstart目录
  • git init，初始化git（因为需要用git submodule安装第三方主题）
  • git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke，使用git下载ananke这个主题
  • echo "theme = 'ananke'" >> hugo.toml，修改配置文件，使用ananke这个主题
  • hugo server，运行这个项目，从 http://localhost:1313/ 访问生成的网站

添加内容页面

运行成功后，Ctrl + C 停掉网站，添加点内容页面

  • hugo new content content/posts/my-first-post.md ，执行完毕后，多了一个markdown文件 content/posts/my-first-post.md
  • 执行 hugo server -D，然后重新访问 http://localhost:1313/ ，可以看到新增加的内容

配置网站

打开项目目录下的hugo.toml这个文件，该文件内容为

baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'
theme = 'ananke'
  • baseURL：真正发布网站到服务器时的基础网址
  • title：网站的标题
  • 后续有更多的配置时，都需要写入到这个站点配置文件中

发布网站

到目前为止，只是在本地运行了网站，并没有发布到服务器上

  • 执行hugo进行打包，执行后，会在项目目录下生成public目录，但生成的网站中不会包含这些页面（markdown文件）
    • draft 值为 true 的，代表是草稿
    • date 是未来时间的
    • publishDate 是未来时间的
    • expiryDate 是过去时间的，代表已经过期
  • 具体发布网站可以看 host and deploy，这里讲了好多种发布方式，比如GitHub Pages，我一般是直接放在服务器上，用nginx发布网站。

读到这里，你其实已经可以愉快的写文本类的博客网站了。

  • 创建网站项目
  • 配置网站名称
  • 添加markdown文件，在markdown中写网站内容
  • hugo server 本地查看效果，hugo 打包发布

网上好多入门教程也是写到这里，但如果你想继续深入，请继续阅读。

你也可以通过视频来系统性学习

https://www.giraffeacademy.com/static-site-generators/hugo/

或者从官方文档逐步学习。接下来的内容，将尽可能全的，尽可能简单地介绍hugo的关键内容。

深入学习Hugo

目录结构分析

执行了hugo new site后，得到了以下目录结构，看看就好，会随着使用逐渐熟悉具体用途

├── archetypes ⚠️这里其实是hugo new content使用的模版
│   └── default.md ⚠️hugo new site 就生成了这个模板文件，新md文件自动使用（实际上是最后的选择）
├── assets 这里会放置一些css、js、图片等内容，
├── content ⚠️网站markdown文件都在这里
├── data //json数据文件之类的
├── hugo.toml ⚠️站点的配置文件
├── i18n  //语言国际化
├── layouts //布局
├── static ⚠️放置一些网站的静态资源，如图片，里面的文件可以随意组织
└── themes ⚠️放置hugo主题，可以使用任何你喜欢的第三方主题
当执行hugo后，会生成
├── public    ⚠️网站生成目录
├── resources //一些资源的缓存

Front matter

官方文档地址: https://gohugo.io/content-management/front-matter/

Front matter 是 Hugo 的一个核心功能。

Front matter 位于markdown文件顶部，是 YAML 或者 TOML 格式的，分别以---或+++开头和结束。

Front matter的作用是为页面添加额外的属性数据，这些属性数据可以控制页面的渲染、行为等。

比如常用的属性有

  • title：页面标题
  • date：页面创建时间
  • draft：是否草稿，草稿不会被构建到网站上，除非使用-D参数
  • tags：页面标签数组
  • categories：页面分类数组
  • keywords：页面关键字数组，通常对应网页中的meta标签或用于分类
  • weight：页面权重，用于排序，默认为 0
  • description：页面描述
  • build：构建选项 build options
  • headless：将一个叶子页面包作为一个 headless，创建无头页面资源包。
  • isCJKLanguage: 是否中日韩文，影响文章阅读时间的统计
  • layout：使用特定的模板来渲染
  • slug：覆盖 URL 的最后一段，具体参考URL规则部分
  • url：覆盖整个 URL，具体参考URL规则部分

Page Bundles

官方文档地址: https://gohugo.io/content-management/page-bundles/

Page Bundles，就是一个目录代表一个页面，这个目录里既放了文章内容，也放了文章所需要的资源（如图片），整个目录被称为一个Page Bundles。

Page Bundles又分为以下几种类型：

  • leaf 叶子：包含了 index.md 以及资源的目录，没有子Page Bundles
  • branch 分支：
    • 包含了 _index.md 以及资源的目录，有嵌套的子Page Bundles, 可以是叶子Bundles，也可以是其他分支Bundles；
    • 注意：content 下第一层目录即使没有_index.md, 也是一个分支，主页也是。
  • headless：不发布的内容，但资源可以被其他页面引用, 使用 Front matter 来定义

例子及对比可参考官方文档，不过多描述

Section

官方文档地址: https://gohugo.io/content-management/sections/

section 其实就是Page Bundles 中提到的分支类型：

  • content 目录下的第一层目录
  • 以及任何带有_index.md 文件的目录

Archetypes

官方文档地址: https://gohugo.io/content-management/archetypes/

Archetypes是新文章的模板

hugo new site 命令生成了 archetypes/default.md, 这个文件就是默认的新文章的模板，文件内容为

+++
title = '{{ replace .File.ContentBaseName "-" " " | title }}'
date = {{ .Date }}
draft = true
+++

hugo new content 命令会以这个archetypes/default.md 为模板，生成新的文件。

所以你可以修改这个文件的内容，加上更多的Front matter数据。也可以建立新的模板文件。hugo new content命令会按照规则寻找合适的模板，如果找不到，就会使用默认的模板。

  • archetypes/posts.md
  • archetypes/default.md
  • themes/my-theme/archetypes/posts.md
  • themes/my-theme/archetypes/default.md

模板文件中可以使用函数，就像默认模板中的.Date、.File 那样，具体请看官方文档，但使用第三方主题时，一般用不上，因为第三方作者已经写好了。

模板文件一般是为Front matter服务的，但也可以包含内容。

还可以为叶子类型的页面包创建模板文件，比如

archetypes/
├── galleries/
│   ├── images/       <-- 将会自动生成 images 目录
│   │   └── .gitkeep
│   └── index.md      <-- 和default.md格式相同
└── default.md

使用 --kind 参数可以指定特定的模板文件，例如hugo new content --kind tutorials articles/something.md

Taxonomies

官方文档地址: https://gohugo.io/content-management/taxonomies/

Taxonomies是用来分类文章的机制。

Taxonomies需要在站点配置文件中进行配置，但如果不配置，Hugo 会默认使用标签tags、分类categories作为 Taxonomies。

在文章的Front matter中，我们可以指定文章的分类和标签，就像这样

categories: [Hugo]
tags: [Hugo内容管理]

Hugo 会自动处理分类和标签的链接，点击链接可以进入对应的分类和标签的页面。

https://example.org/categories/hugo/
https://example.org/tags/hugo内容管理/

当然，你可以在站点配置中配置自定义的分类法。

taxonomies:
  category: categories
  series: series
  tag: tags

文件路径与URL的对应关系

所有的 markdown 文章都应该放在 content 目录下。

默认情况下，源文件的目录结构与生成后网址有紧密的联系。

下面这个例子，不需要其他额外的配置，就可以完美运行

content
  └── about
  |   └── index.md       // <- https://example.org/about/
  ├── posts
  |   ├── firstpost.md   // <- https://example.org/posts/firstpost/
  |   ├── happy          // 注意：这个目录是个Page Bundles
  |   |   └── ness.md    // <- https://example.org/posts/happy/ness/
  |   └── secondpost.md  // <- https://example.org/posts/secondpost/
  └── quote
      ├── first.md       // <- https://example.org/quote/first/
      └── second.md      // <- https://example.org/quote/second/

content 目录的特点

  • 在 content 中可以进行任意层级嵌套
  • content/第一级目录 是特殊的，可用于确定布局等，是 section 的一种
  • 内容类型可以简单地分为两种类型：文章类型、列表类型
    • 文章类型：页面展示的就是文章内容
    • 列表类型：页面展示的是文章列表，如主页、分类文章列表页、标签文章列表页等

URL路径解析

  • Hugo 默认使用 pretty URLS形式的网址
  • 在站点配置hugo.yaml 中，配置网站域名 baseURL = "https://example.org"
  • 文章类型和列表类型的网址解析规则不同，官方文档给了两个例子
    • 列表类型: content/posts/_index.md => https://example.org/posts/
    • 文章类型: content/posts/my-first-hugo-post.md => https://example.org/posts/my-first-hugo-post/

URL 管理

官方文档地址: https://gohugo.io/content-management/urls/

通过文章Front matter的 slug、url 可以影响页面的 URL 通过站点配置的 permalinks 可以配置页面的 URL规则

菜单管理

官方文档地址: https://gohugo.io/content-management/menus/

定义菜单的步骤

  • 定义菜单实体
  • 设定每一个实体的国际化配置
  • 使用模板来展示菜单

但往往使用第三方主题已经完成了菜单的定义，只需要按照主题的文档网菜单中添加条目即可。

定义菜单项的三种方法

  • 自动为顶级 section定义，使用站点配置的 sectionPagesMenu: main
  • 使用文章的Front matter menus: main或者是 menu: main
  • 使用站点配置的 menus

在Front matter的方式中，还可以添加其他的属性，如 name、post、pre 等

站点配置的例子

menus:
  main:
  - name: Home
    pageRef: /
    weight: 10
  - name: Products
    pageRef: /products
    weight: 20
  - name: Services
    pageRef: /services
    weight: 30

评论系统

官方文档地址: https://gohugo.io/content-management/comments/

播客的文章大部分情况是给别人阅读的，评论系统非常重要。

由于 Hugo 生成的是静态页面，由于没有数据库，所以没办法将别人的评论记录下来，所以需要使用第三方评论系统，比如 Disqus、Gitment 等。

Hugo 默认支持 Disqus，在站点配置中加入

services:
  disqus:
    shortname: your-disqus-shortname

然后使用 {{ template "_internal/disqus.html" . }} 来呈现评论。

如果使用第三方模板，那么设置方式有可能不同，需要根据模板的文档来设置。

下一步建议

  • 这篇文章只讲了常用的部分，还有一部分需要你去翻阅一下官方文档
  • 如果你使用别人提供的主题，可以进一步参考对应主题的文档，了解如何使用特定的主题
  • 如果你不使用别人的主题，需要完全控制网页，或者是创建主题给别人使用，需要进一步学习主题、模板等知识

标签

HUGO教程

文章目录

鲁ICP备2023028957号鲁公网安备37059002000210