目录
将清理、Hugo 生成和 Pagefind 索引创建整合到一个 just gen 配方中,确保始终按顺序执行。请将源文件放在 public/ 之外。这个工作流每次构建都会删除该目录,因此误存其中的文件也会被删除。
要点#
- 用
just gen一条命令依次执行清理、Hugo 和 Pagefind。 - 将
justfile放在仓库根目录,与site/和notes/并列。 - 配方中的每一行都在独立的 shell 中执行,因此单独一行的
cd不会影响下一行。 - 请将
public/视为可随时删除的输出目录。从中删除的未跟踪文件无法通过 Git 恢复。
确定构建顺序#
构建分为三个阶段:删除上次的输出、用 Hugo 生成 HTML、用 Pagefind 为这些 HTML 创建索引。Pagefind 需要读取生成的文件,因此必须在 Hugo 之后执行。
先删除输出,可以防止重新构建后残留旧页面。如果不删除,从源文件中移除的文章可能仍留在 public/ 中,并继续出现在搜索结果中。
此配置假定已安装 Hugo、Pagefind 和 Node.js。所提供的环境为 Ubuntu Server 26.04 LTS,使用 just 1.57.0、Hugo v0.165.0+extended、Pagefind 1.5.2 和 Node.js v22.22.1。这些是记录中的版本,并不代表最新版本。
添加 justfile#
如果 Ubuntu 上尚未安装 just,请运行 sudo apt install just 安装。使用 just --version 检查已安装的版本。发行版提供的软件包版本可能与上述版本不同。
在仓库根目录创建名为 justfile 的文件。此配置将 Hugo 的配置和模板放在 site/ 中,将文章源文件放在 notes/ 中,并将生成的网站输出到 public/。
# 引数なしで実行したときに利用可能なレシピを表示する。
default:
@just --list
# サイトと検索インデックスを再構築する。
gen:
rm -rf public
hugo --source site --contentDir ../notes --destination ../public --minify
npx -y pagefind --site public执行构建并检查#
运行 just 列出可用的配方,运行 just gen 构建网站。配方名称正上方的注释会作为说明显示在列表中。前缀 @ 会隐藏命令本身,但仍会显示命令的执行结果。
Hugo 的路径设置很重要。当源目录为 site/ 时,../notes 指向同级的内容目录,../public 指向仓库根目录下的输出目录。可选的 --minify 标志会减少生成的 HTML 中的空白。
命令完成后,确认 public/index.html 存在。通过 HTTP 提供生成的网站,并测试页面显示和搜索查询。仅有 HTML 文件并不能证明搜索索引正常工作。你也可以在 notes/ 内运行 just gen。just 会逐级向上查找 justfile,默认在该文件所在的目录中执行配方。
注意 shell 的边界#
普通配方中的每一行都在独立的 shell 中执行。即使某一行写了 cd sub,下一行写了 pwd,第二行显示的仍是配方的工作目录。第一个 shell 退出后,目录切换便会失效。
如果两个命令需要共享同一个 shell 的状态,请将它们写在同一行,例如 cd sub && pwd。上面的构建配方通过为各个命令明确指定路径,避免了这种依赖。
另外,npx -y pagefind 不会固定 Pagefind 的版本。要实现可复现的构建,请将特定版本安装为项目依赖,并提交包清单和锁文件。
不要将源文件放在 public 中#
在所提供的案例中,文章源文件被误存到了 public/ 内。由于在 just gen 删除源文件之前,已将其复制到其他位置,因此内容没有丢失。如果没有那份副本,就需要其他备份才能恢复。
由于 public/ 被 Git 忽略,删除文件后,git status 也不会显示可供追查的变更。被忽略的未跟踪文件没有可用于恢复的提交历史。
实际操作中的规则很简单:在 notes/ 中撰写文章,并将 public/ 内的所有内容视为可重新生成的文件。即使构建失败,只要源文件完好,就可以重来。删除源文件的唯一副本,则是另一回事。
下一步#
运行 just gen 之前,请检查 public/ 内是否有源文件,并将找到的文件移至 notes/。
来源: https://zenn.dev/fumika_676/articles/20220236284e11
目录
