Contents
Combine cleanup, Hugo generation, and Pagefind indexing into a single just gen recipe so they always run in order. Keep source files outside public/. This workflow deletes that directory on every build, including any files accidentally saved there.
Key Points#
- Run cleanup, Hugo, and Pagefind in that order with a single
just gencommand. - Place the
justfileat the repository root, alongsidesite/andnotes/. - Each recipe line runs in a separate shell, so a standalone
cddoes not affect the next line. - Treat
public/as disposable output. Git cannot restore untracked files deleted from it.
Define the Build Order#
The build has three stages: delete the previous output, generate HTML with Hugo, and index that HTML with Pagefind. Pagefind reads the generated files, so it must run after Hugo.
Deleting the output first prevents old pages from lingering after a rebuild. Otherwise, articles removed from the source may remain in public/ and continue appearing in search results.
This setup assumes Hugo, Pagefind, and Node.js are already installed. The supplied environment ran Ubuntu Server 26.04 LTS with just 1.57.0, Hugo v0.165.0+extended, Pagefind 1.5.2, and Node.js v22.22.1. These are the recorded versions, not a claim that they are the latest releases.
Add a justfile#
If just is not yet available on Ubuntu, install it with sudo apt install just. Check the installed version with just --version. Your distribution’s package may differ from the version listed above.
Create a file named justfile at the repository root. In this setup, site/ holds Hugo’s configuration and templates, notes/ holds article sources, and the generated site goes into public/.
# 引数なしで実行したときに利用可能なレシピを表示する。
default:
@just --list
# サイトと検索インデックスを再構築する。
gen:
rm -rf public
hugo --source site --contentDir ../notes --destination ../public --minify
npx -y pagefind --site publicRun and Verify the Build#
Run just to list available recipes and just gen to build the site. Comments immediately before recipe names appear as descriptions in the list. The @ prefix hides the command itself from the output; the command’s results are still displayed.
Hugo’s path arguments matter. With site/ as the source directory, ../notes points to the sibling content directory, and ../public points to the output directory at the repository root. The optional --minify flag reduces whitespace in the generated HTML.
Once the commands finish, check that public/index.html exists. Serve the generated site over HTTP and test both page rendering and search queries. The presence of HTML files alone does not confirm that the search index works. You can also run just gen from inside notes/. just searches parent directories for a justfile and, by default, runs recipes in the directory containing that file.
Watch Shell Boundaries#
In a normal recipe, each line runs in a separate shell. If one line contains cd sub and the next contains pwd, the second line prints the recipe’s working directory. The directory change is lost when the first shell exits.
If two commands need to share shell state, put them on one line, such as cd sub && pwd. The build recipe above avoids this dependency by specifying paths explicitly for each command.
Also, npx -y pagefind does not pin the Pagefind version. For reproducible builds, install a specific version as a project dependency and commit the package manifest and lockfile.
Keep Source Files Out of public#
In the supplied example, an article’s source was accidentally saved inside public/. Its contents survived because it had been copied elsewhere before just gen deleted the original file. Without that copy, recovery would have required another backup.
Because public/ was ignored by Git, deleting the file left no changes in git status to provide a clue. Ignored, untracked files have no commit history to restore from.
The practical rule is simple: write articles in notes/ and treat everything in public/ as reproducible output. If a build fails, you can try again as long as the source is safe. Deleting the only copy of a source file is a different problem.
Next Steps#
Before running just gen, check public/ for source files and move any you find to notes/.
Source: https://zenn.dev/fumika_676/articles/20220236284e11
Contents
