Add thissite section with dates workflow explanation

New section documenting how this site works, starting with
how created/lastmod dates flow through archetypes, git, and Hugo.
This commit is contained in:
Jean-Michel Tremblay 2026-04-03 16:55:32 -04:00
parent 45b7bac831
commit 688fd8f16c
3 changed files with 117 additions and 0 deletions

View file

@ -0,0 +1,4 @@
---
title: "This Site"
description: "How this site is built, configured, and maintained."
---

View file

@ -0,0 +1,108 @@
---
title: "How Dates Work on This Site"
date: 2026-04-03
draft: false
tags: ['hugo', 'git', 'workflow']
---
Every page on this site has two dates: **Created** and **Last Modified**.
Neither one is maintained by hand. Here's the full flow.
## Creating a new page
New content is created via Hugo's CLI (running in Docker):
```bash
docker run --rm -v "${SITE_DIR}:/src" -w /src \
ghcr.io/gohugoio/hugo:latest new content/thissite/my-page.md
```
Hugo reads the archetype template at `archetypes/default.md`:
```yaml
+++
date = '{{ .Date }}'
draft = true
title = '{{ replace .File.ContentBaseName "-" " " | title }}'
tags = []
+++
```
At creation time, Hugo substitutes `{{ .Date }}` with the current
timestamp and writes it into the new file's front matter. The result
looks like:
```yaml
---
date: 2026-04-03T14:30:00-04:00
draft: true
title: "My Page"
tags: []
---
```
**That `date` value is baked into the file once and never changes.**
It represents when the page was created. Nobody edits it afterward.
## How "Last Modified" works
The `lastmod` field is **not** stored in the file at all. It's resolved
at build time by Hugo based on this config in `hugo.toml`:
```toml
enableGitInfo = true
[frontmatter]
date = [':default']
lastmod = [':git', ':fileModTime']
```
The resolution chain for `lastmod`:
1. **`:git`** — Hugo calls `git log` to find the author date of the most
recent commit that touched the file. This is the primary source.
2. **`:fileModTime`** — Fallback to the filesystem modification time
(useful when the file hasn't been committed yet, e.g. during local
preview).
So when Hugo builds the site, it inspects the git history for each
content file and injects `.Lastmod` into the page context. Templates can
then render it with `{{ .Lastmod }}`.
## What does git actually track?
Git records the **author date** on each commit. When you edit a file and
commit it, that commit's date becomes the new `lastmod` for that file.
The original `date` in front matter is untouched — it still reflects
creation time.
```
commit abc123
Author: JM <jm@example.com>
Date: Thu Apr 3 14:30:00 2026 -0400
Fix typo in dates page
```
Hugo will see `Apr 3 14:30:00 2026` as the `lastmod` for any file
modified in that commit.
## The full lifecycle
| Step | What happens | Where the date lives |
|---|---|---|
| `hugo new content/thissite/foo.md` | Archetype stamps `date` | In the file's front matter |
| First `git commit` | Git records author date | In git history |
| Edit the file later | `date` in front matter unchanged | Still in front matter |
| `git commit` the edit | Git records a new author date | In git history |
| `hugo build` | Hugo reads `date` from front matter, `lastmod` from git | Injected into page context at build time |
## Key points
- **Created date**: set once by the archetype, stored in front matter,
never changes.
- **Last modified**: not stored in the file. Resolved from git at build
time. Zero maintenance.
- **`enableGitInfo = true`** is required in `hugo.toml` for any of the
git-based date resolution to work.
- **No tracking needed** for `lastmod` — it's derived, not stored.

View file

@ -62,6 +62,11 @@ enableGitInfo = true
name = "Config" name = "Config"
url = "/config" url = "/config"
weight = 11 weight = 11
[[languages.en.menu.main]]
identifier = "thissite"
name = "This Site"
url = "/thissite"
weight = 12
[module] [module]
[[module.imports]] [[module.imports]]